Skip to content

Getting Started

Requirements

  • Python 3.11–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

Upgrading from 0.7.1

0.7.2 keeps the 0.7.1 API. The Docker image, Makefile PYTHON_VER, and .python-version use CPython 3.13.16. The supported range is still Python 3.11–3.14. Full notes: CHANGELOG 0.7.2.

Upgrading from 0.7.0

0.7.1 drops Python 3.10 (requires-python is >=3.11, <3.15). Callers already on 3.11–3.14 keep the 0.7.0 scheduler and HTTP contracts. Full notes: CHANGELOG 0.7.1.

Upgrading from 0.6.x

0.7.0 is a breaking release. Full notes: CHANGELOG 0.7.0. Callers of 0.6.6 must at least:

  • Compare Channel.send to "ok" (not treat the result as bool; "full" / "stopped" are truthy).
  • Treat IJobStore.put and Job.save as returning bool (False means skipped, not applied).
  • Enable only one of httpServer / httpsServer; server.run raises if both are true.
  • From an already-running event loop, do not call Job.scheduled(); apply INIT→SCHEDULE, await Channel.send, then job.save().

Scheduler and HTTP details: Scheduler, Network and SSE.

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. If those ports are down, the marked tests skip (coverage is not a CI backstop). CI sets PYPEPPER_REQUIRE_DEVENV=1 so a missing devenv fails the job.

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