template-python

Template repository for Python projects: a src/ package with a console entry point, pytest tests, GitHub Actions for tests, static analysis, tutorials, documentation and PyPI publishing, and an Astro + Starlight documentation site.

Documentation: https://max-models.github.io/template-python/

Use the template

Create a repository from this template, then rename the package:

bash setup_project.sh my-app
rm setup_project.sh

This replaces template-python with my-app everywhere, moves src/app to src/my_app, and points the entry point, tests and docs at it.

Install

With uv:

make install    # uv sync --extra dev, plus the pre-commit hooks
uv run template-python

Or create and activate a Python environment (3.10 or newer):

python -m venv env
source env/bin/activate
pip install --upgrade pip

Install the code and requirements with pip:

pip install -e .

Run the code with:

template-python

The test, docs and dev extras install the test runner, the documentation tooling and the linters:

pip install -e ".[dev]"

Development

Formatting and linting use ruff, type checking pyright, run by pre-commit and in CI:

make lint     # ruff check, ruff format --check, pyright
make test     # pytest with coverage

Commit messages follow Conventional Commits; see CONTRIBUTING.md.

Build docs

The documentation in docs/ is an Astro + Starlight site: hand-written pages, the notebooks in tutorials/ executed and published as pages, and the API reference generated from the docstrings with starlight-pydocs. It needs Node 22 or newer.

make docs-install     # npm packages and the Python docs extra
make docs-notebooks   # execute tutorials/*.ipynb and convert them to pages
make docs-dev         # live preview at http://localhost:4321/template-python/
make docs-build       # the static site in docs/dist

Build the README

README.md is rendered from README.qmd with Quarto:

make readme

Releases

release-please keeps a release PR open on main from the commit messages. Merging it tags the release, updates CHANGELOG.md and publishes the package to PyPI with trusted publishing (OIDC). The one-time PyPI and GitHub configuration is described in the publishing guide.