python-project-standards

Binding engineering standards for Python projects, and the tooling that enforces them:

• template/: a Copier template containing the standards documents (docs/standards/), pre-commit hooks, GitHub Actions (CI with a 100 % coverage gate, automatic SemVer releases from Conventional Commits, CodeQL, nightly mutation testing, weekly drift and audit), and strict ruff / pyright / pytest configuration.
• standards: a CLI (this package) that turns the rules into checks: commit messages, branch names, suppressions, doc impact, version ↔ tag, hook ↔ CI parity, consistency of the standards documents, mutation score, template drift and installed hooks.

Full documentation of every feature: docs/.

Shift left, by design

The standards follow one principle: every rule has a gate, and every gate runs at the earliest stage that can run it. This repository is held to its own standards. Its gates:

29 gates. 21 run on your machine before code leaves it (pre-commit / pre-push hooks); CI reruns every one of them, and scheduled jobs add the slow and the external checks.

Gate	💻 commit	💻 push	☁️ CI	🌙 nightly	📅 weekly
pre-commit-hooks: check-added-large-files · check-case-conflict · check-merge-conflict · check-toml · check-yaml · detect-private-key · end-of-file-fixer · trailing-whitespace	✓		✓
gitleaks (gitleaks)	✓		✓
ruff format (ruff-format)	✓		✓
ruff check (ruff-check)	✓		✓
pyright (changed files) (pyright)	✓		✓
no silent suppressions (suppressions)	✓		✓
uv.lock in sync (uv-lock)	✓		✓
actionlint (actionlint)	✓		✓
zizmor (workflow security) (zizmor)	✓		✓
conventional commit message (commit-msg)	✓

Start a project

uvx copier copy --trust gh:wghami/python-project-standards my-project
cd my-project && git add -A && git commit -m "chore: render from python-project-standards"

Keep a project current

uvx copier update --trust

A weekly job in every project runs standards check-template-drift and opens an issue when a newer release of this template exists.

Change a standard

Edit the document under template/docs/standards/ and its enforcement (CLI, hooks or workflows) in the same PR. CI renders a sample project from the PR and runs its whole pipeline. Merging releases a new version automatically. See 11-keeping-standards-current.md.

Develop

uv sync
uv run pre-commit install
uv run pytest --cov