👋 Welcome

Every team starts a new Python service the same way: wiring up logging, health checks, configuration, error formats, a container image. It takes two to four weeks, and every team's result is a little different.

PyFr aims to make that a ten-minute step instead — and to make the result the same good one every time.

The generated code is yours. 🎁 A generated service imports no PyFr package: no framework to upgrade, no runtime dependency on us, and nothing to lock you in. The one thing PyFr publishes is the updater, pyfr-cli, which runs at update time and is never imported. A generated project still receives later template fixes: just update pulls them into itself through an ordinary git merge.

✅ Status: M0–M8 done

The template is usable — uvx cookiecutter gh:EmadMokhtar/pyfr generates a project whose just check passes: three combinations are rendered for real and run through their own just check-all on every merge to main and every night, and all eight are rendered and lint-checked on every pull request and merge. M7, the conversion into a template, is complete: the template renders from twelve prompts, prunes the backends you do not choose, gives a generated project its own workflows and its own documentation site about itself, and records the template version it came from. M8, template updates, is complete too: just update pulls a later template version into a generated project through a git merge, and a weekly workflow opens the pull request for it. See the roadmap for what each milestone delivered. The reference service is rendered from that template; it is the complete, running service you can run, read, and copy from right now.

PyFr is built in three phases:

The rule behind that order: never debug Jinja and Python at the same time. 🙂

M0 through M8 — the reference service, its conversion into a template, and template updates for generated projects — are complete. See the roadmap for what each milestone delivered.

🚀 Try it in one command

uvx cookiecutter gh:EmadMokhtar/pyfr

cookiecutter asks twelve questions — the project's name, its author, which of PostgreSQL, Redis and S3 it gets, its port, its licence — and every one has a default. The hook then prunes what you did not choose, runs git init, uv sync and pre-commit install, and makes the first commit, each step best effort, so an offline laptop still gets a whole project.

Then cd into it, just up, and open http://localhost:8000/docs. 👋

The getting started guide explains each prompt and what the hook does; the generated project's own site takes it from there.

📦 What's in the box

Every item below already runs in the reference service today — nothing here is a promise:

• ⚡ FastAPI, with an application factory and a lifespan.
• 🧱 Four layers — domain, services, infrastructure, api — with the dependency rule enforced by a build check, not by code review.
• ✅ Configuration validated at startup. A bad value stops the process with a readable message and exit code 78, instead of causing a 500 an hour later.
• 📋 Structured logging — one JSON object per line on standard output, with third-party records passing through the same chain.
• 💚 Three health endpoints answering three different questions. Liveness never checks a dependency, so a database hiccup cannot restart every instance at once.
• 🚨 RFC 9457 Problem Details error responses.
• 🔗 Correlation identifiers binding one value to every log line a single request produced.
• 🛑 Graceful shutdown, so a rolling deployment does not drop live requests.
• 🔒 A hardened container image: non-root, no build tools, no shell utilities in the final layer, and reproducible installs from a lock file.
• 📖 Its own documentation site, built from its own docs/ and deployed to GitHub Pages by its own workflow — the reference service's site is the worked example.

M1–M6 have since added persistence, OpenTelemetry, contract testing, cache and object storage, release automation, and supply-chain auditing, scanning and publishing — the roadmap lists what each one delivered.

📚 Documentation

Two sites, deployed together. PyFr's site is about the template: generating a project, how the template is built and tested, and why it is a template rather than a framework. The reference service's site is about the service: it is the documentation every generated project ships about itself, rendered here for the reference answers.

The design specification and milestone plans live in docs/superpowers/. They contain the reasoning behind the decisions the site describes, and are deliberately not published.

🛠️ Development

The repository root and the reference service are two separate Python projects, each with its own pyproject.toml. They are never synced together. The template body, {{cookiecutter.project_slug}}/, is the source of truth: edit it, run just regen, and the reference service is rendered from it — never edit examples/reference-service/ by hand.

# The template and its tests: both sites build, the root suite, the golden diff
uv sync --group dev --group docs && just check

# The reference service
cd examples/reference-service && uv sync && just check

# PyFr's documentation site, with a live preview
just docs-install && just docs

The contributing guide has the whole loop: the regeneration and golden diff, backends and pruning, the two documentation sites and every root just recipe.

🤝 Contributing

Issues, questions, and pull requests are all welcome — including "I read this and it didn't make sense," which is one of the most useful things you can send while the project is this young.

Commit messages and pull request titles must follow Conventional Commits. The contributing guide has the rest.

🙏 Credits

PyFr's architecture is influenced by GoFr, the Go microservice framework — the context-driven layering and the emphasis on developer experience, adapted to Python's ecosystem and to a template rather than a library.

⚖️ License

Mozilla Public License 2.0.