Python Project Foundry¶
Create an opinionated, production-ready Python package/library repository from one interactive command.
uvx python-project-foundry ./my-project
Create your first project See what gets generated
What you get¶
| Area | Included |
|---|---|
| Package | src/ layout, typed public API, tests, examples, and package metadata |
| Quality | Ruff, BasedPyright, Pytest, Hypothesis, coverage, and pre-commit hooks |
| Security | Bandit, pip-audit, detect-secrets, CodeQL, dependency review, and Scorecard |
| Documentation | MkDocs Material, generated API reference, and GitHub Pages workflow |
| Delivery | Wheel and source builds, SBOM, artifact attestations, PyPI trusted publishing |
| Development | uv lockfile, Make targets, dev container, Docker images, and Nox matrix |
Typical workflow¶
- Scaffold — answer the package/library repository questionnaire.
- Review — inspect the generated files and run
make check. - Publish — explicitly create and push the GitHub repository.
- Develop — use the generated Make targets and automation.
- Update — preview and merge changes from newer Foundry releases.
Scaffolding is local by default. GitHub resources are created only when you run
the publish command.
Find what you need¶
| Goal | Start here |
|---|---|
| Generate a project interactively | Quickstart |
| Understand or choose questionnaire answers | Configure a project |
| Work in the generated repository | Develop a generated project |
| Apply a newer template release | Update a generated project |
| Create the GitHub repository and Pages site | Publish to GitHub |
| Run without prompts | Automate generation |
| Resolve a failure | Troubleshooting |
| Look up every CLI option | Command-line reference |