Skip to content

Getting Started

Requirements

  • Python 3.10–3.14
  • uv >= 0.10.7 (recommended for local installs)
  • Docker (optional; required for DB helper integration tests)

Install

make build-prepare

This cleans build output and installs development dependencies from requirements-dev.txt.

For runtime-only dependencies:

uv pip install -r requirements.txt

Validate locally

make lint    # ruff + mypy on pypepper/
make check   # lint + mutable class-attr guard
make test    # check + pytest with coverage (>= 90%; branch coverage enabled)

Local and CI upload branch coverage (branch = true). Codecov project compares overall coverage vs the PR base; patch compares changed lines vs an auto target; both allow a 1% threshold.

DB-backed helper tests expect services from devenv/ci.yaml on localhost:

docker compose -f devenv/ci.yaml up -d --wait
make test

Run examples

Prefer curated domain imports in application code:

from pypepper.common.config import config
from pypepper.scheduler import Job, setup_from_config

config.load_config("./conf/app.config.yaml")
# Durable scheduler.jobStore backends are not applied by load_config alone:
setup_from_config(config.get_yml_config())

For a guided walkthrough (expected COMPLETE output and common pitfalls), see Tutorial: First service.

HTTP server

python example/server/app.py --config ./conf/app.config.yaml

Default HTTP port comes from conf/app.config.yaml (network.httpServer.port, typically 55550). The example calls setup_from_config after load_config.

Scheduler example

python example/scheduler/app.py

Runs load_config → setup_from_config → Job.scheduled → Worker through COMPLETE. See Scheduler.

SSE example

Inject a local API key (config ships with empty validKeys):

export PYPEPPER_SSE_API_KEY=your-local-key
python example/sse/app.py

Connect:

curl -N -H "X-API-Key: $PYPEPPER_SSE_API_KEY" http://localhost:55550/sse/echo

Keep sse.authentication.enabled: true for anything beyond local experiments. To temporarily allow auth-off locally, export PYPEPPER_SSE_ALLOW_AUTH_OFF=1 (see SSE security notes).

Documentation site

Online: https://jovijovi.github.io/pypepper/

Local preview (same content as the published site):

make docs        # mkdocs build --strict
make docs-serve  # local preview

Push to main deploys the site via GitHub Pages (.github/workflows/docs.yml).

Release

Tag-triggered PyPI publishing: see Release.

Summary: bump version in pyproject.toml, merge to main, then git tag vX.Y.Z && git push origin vX.Y.Z (tag must match the pyproject version). Configure PyPI Trusted Publisher once as described in that guide.

Next steps

  • Read Architecture for module boundaries
  • Follow a domain guide under Guides
  • Browse the API Reference for signatures and types
  • Optional: enable Tracing (console and/or local Jaeger)
  • Maintainers: Release to PyPI via Git tag