Python Package Blueprint (with an Agent-Ready Development Environment)

A template for starting a new Python package: src/-layout packaging with hatchling and git-tag-derived versions, uv for dependency locking, ruff + mypy --strict + a 100%-coverage pytest gate, and a devcontainer with the same tools baked in for both humans and coding agents. Every piece is wired up and exercised end to end - see src/example_package/ and tests/ for a working (if trivial) example.

What's included

• Packaging: pyproject.toml builds a real sdist/wheel (uv build) via hatchling; the version comes from git tags (hatch-vcs), not a hand-maintained field. src/example_package/py.typed ships type info downstream (PEP 561).
• Dependency management: uv.lock pins exact versions for both runtime ([project.dependencies]) and dev tooling ([dependency-groups], PEP 735). package-lock.json does the same for the npm-based formatters.
• Logging: LOG_LEVEL / LOG_FORMAT pick the threshold and the shape - human-readable text, or one JSON object per line (built with json.dumps, with the timestamp, exception and extra={...} fields a log pipeline expects). Diagnostics go to stderr so stdout stays the command's output.
• Quality gates: ruff (lint + format), mypy --strict, codespell, pytest with a 100% coverage floor, prettier, and markdownlint-cli2 - see scripts/ below.
• Security: pip-audit and npm audit check locked dependencies against advisory databases; zizmor lints the GitHub Actions workflows; CodeQL scans the source itself (.github/workflows/codeql.yml - public repos only, see the note at the top of that file). .github/workflows/audit.yml reruns the dependency audits weekly; .github/dependabot.yml keeps every pin (Python, npm, the Dockerfile's base images, Actions) current.
• CI: .github/workflows/ci.yml runs the same gates on every push/PR, plus a build job that verifies the built wheel actually installs and runs.
• Local gates: .githooks/pre-push runs lint + test before every push (activated automatically inside the devcontainer).
• Devcontainer: .devcontainer/ gives both a human's editor and coding agents (Claude Code, Codex) an identical, tool-complete environment.

Quickstart

Open the repo in the devcontainer (VS Code's "Reopen in Container", or any Dev Containers-compatible tool) - everything below is pre-installed there. Outside the devcontainer:

uv sync    # Python runtime + dev tooling, from uv.lock
npm ci     # prettier / markdownlint-cli2, from package-lock.json

Everyday commands

Special commands

For local simulation (manual, by-hand checks)

• scripts/dev_local_simulation
  • Builds the package and publishes it to the local pypiserver in .devcontainer/docker-compose.yml, then installs and runs that build - a manual, by-hand check.

Using this as a template

1. Rename src/example_package/ to your real package name and delete the sample code and tests inside it (tests/test_core.py, tests/test_cli.py) - keep tests/test_node_version_consistency.py and tests/conftest.py. logging_config.py (and its tests) is meant to be kept and adapted rather than deleted.
2. Update [project] in pyproject.toml: name, description, the packages path under [tool.hatch.build.targets.wheel], and [project.scripts] if you don't want a console script.
3. Add your runtime dependencies to [project.dependencies].
4. Update this README.

URLs

• GitHub repo
• PyPI package

License

MIT - see LICENSE.