Python Project Template

A comprehensive, opinionated template for modern Python projects -- featuring uv packaging, Ruff for linting and formatting, justfile, pytest testing with code coverage upload to codecov, MkDocs documentation with configuration for Read The Docs, pre-commit hooks, .editorconfig, .devcontainer, GitHub Actions CI, GitHub issue and pull request templates, architectural decision record (ADR) templates and automated semantic releases.

The goal is to help you start writing code immediately without having to spend time deciding what tools or conventions to use.

How to use this template

1. 🌱 Create a New Repository on GitHub
   1. Click "Use this template".
   2. Choose “Create a new repository”.
   3. Pick a name for your new project (for example, my-awesome-package).
   4. Clone your new repo locally
2. 🏡 Customise the repository
   1. Rename your package directory cd src; mv package_name my_package
   2. Update pyproject.toml with your package name, author, and description.
   3. Update all references to package_name in:
      • package_name/tests/
      • docs/
      • release-please-config.json
      • GitHub Actions workflow
      • This README (including badge links)
   4. Update the "package-name" field in release-please-config.json with your package name for automatically bumping the version number in uv.lock (see release-please issue #2561).
   5. Customise this README with a description of your project and planned features.
   6. Customise the documentation configuration in mkdocs.yml (see the Material for MkDocs documentation for details)
   7. Clear the CHANGELOG.
   8. Enable automated releases by permitting GitHub Actions to open PRs (Settings -> Actions -> Workflow permissions) and add an initial commit hash to bootstrap the release-please in .release-please-manifest.json.
   9. Enable publishing to GitHub Pages (Settings -> Pages) and/or add your project to RTD.

🚀 Features

• Python project directory structure
• README template with badges
• Packaging and dependency management via uv: pyproject.toml
• Linting and formatting via Ruff: .pre-commit-config.yaml
• Testing framework using pytest
• CI using GitHub Actions: .github/workflows/ci.yaml
  • Pre-commit hooks (linting and formatting)
  • Automated tests
  • Package build with smoke test
• Templates for GitHub issues: bug report (01-bug.yml) and feature request (02-feature.yml)
• Template for GitHub pull request: .github/pull_request_template.md
• Docs (MkDocs + mkdocstrings): mkdocs.yml
  • Automated deployment to gh-pages branch via GitHub action: .github/workflows/docs-pages.yaml
  • Configuration for Read The Docs integration: .readthedocs.yaml
  • Template for documenting architectural decisions: docs/architecture/adr/template.md.
  • ADR to explain the rationale for using ADRs: docs/architecture/adr/001-use-architectural-decision-records.md.
• Release automation via GitHub action from release-please: .github/release-please-config.json
• Citation metadata, automatically updated for each new release: CITATION.cff
• BSD-3-Clause: LICENSE
• EditorConfig configuration for consistent coding style across editors: .editorconfig

📦 Installation

Working in a development container

A Dockerfile and configuration in ./devcontainer can be used in VSCode or GitHub Codespaces to work in a pre-configured development environment. It uses a Python 3.14 base image and installs uv, just and all Python dependencies.

To open the project in the container VSCode, you will need to add the Dev Containers extension and download Docker (or Podman -- and configure VSCode to use podman instead of Docker) -- see the VSCode tutorial on devcontainers for more details on using devcontainers. Then run:

Dev Containers: Reopen in Container

Manual installation

1. Install uv
2. Clone and install the project using uv:

git clone https://github.com/gemmadanks/python-project-template
cd python-project-template
uv sync --all-groups

1. Install just.
2. Install pre-commit hooks (only needs to be done once)

just pre-commit-install

Hook definitions: .pre-commit-config.yaml

🏁 Quickstart

from package_name.greet import say_hello
print(say_hello("World"))

🧪 Common Tasks

Several common tasks have been added as recipes to a justfile in the root of the repository:

just install               # uv sync
just test                  # run quick (non-slow) tests
just test-notebooks
just lint                  # ruff check
just format                # ruff format
just type-check            # pyright type-check
just docs-serve            # live docs
just docs-build            # build docs
just pre-commit            # run all pre-commit hooks
just clean                 # remove generated files and folders

📚 Documentation

• Configuration: mkdocs.yml
• Content pages (following the Diátaxis framework):
  • docs/index.md
  • docs/reference.md (autogenerated API documentation from docstrings via mkdocstrings).
  • docs/tutorials.md
  • docs/explanation.md
• Architecture pages
  • Template for documenting architectural decisions: docs/architecture/adr/template.md.
  • ADR to explain the rationale for using ADRs: docs/architecture/adr/001-use-architectural-decision-records.md.
  • Index of ADRs: docs/architecture/adr/index.md.

🔄 Releases

Managed by release-please: (conventional commits drive semantic versioning and an autogenerated CHANGELOG). - Configuration: .github/release-please-config.json - Version source: pyproject.toml

📂 Project Structure

.
├── src/
│   └── package_name/              # Source package
│       ├── __init__.py
│       └── greet.py               # Example module (replace with real code)
├── tests/                         # Test suite
│   ├── conftest.py
│   └── unit/
│       └── test_greet.py          # Example unit test (replace with real tests)
├── docs/                          # Documentation (Diátaxis layout)
│   ├── index.md                   # Documentation homepage
│   ├── tags.md                    # Tag index
│   ├── reference/
│   │   └── index.md               # API reference (mkdocstrings)
│   ├── tutorials/
│   │   └── index.md               # Tutorials overview
│   ├── how-to/
│   │   └── index.md               # How-to guides
│   ├── explanation/
│   │   └── index.md               # Conceptual guides
│   └── architecture/
│       ├── index.md               # Architecture overview
│       └── adr/                   # Architectural decision records
│           ├── index.md           # ADRs index
│           ├── template.md        # Template for new ADR
│           ├── 001-use-architectural-decision-records.md
│           └── 002-manage-dependencies-with-uv.md
├── notebooks/                     # Jupyter notebooks
│   └── example.ipynb
├── .github/
│   ├── workflows/
│   │   ├── ci.yaml                # Lint / test / build
│   │   └── release-please.yaml    # Automated releases
│   ├── ISSUE_TEMPLATE/            # Issue forms
│   │   ├── 01-bug.yml
│   │   └── 02-feature.yml
│   ├── pull_request_template.md   # Pull request template
│   └── dependabot.yml             # Dependency update automation
├── .pre-commit-config.yaml        # Pre-commit hook definitions
├── .devcontainer/                 # Dev container configuration
│   ├── devcontainer.json
│   └── Dockerfile
├── pyproject.toml                 # Project metadata + dependencies (uv)
├── uv.lock                        # Locked dependency versions (uv)
├── README.md                      # Project overview (you are here)
├── mkdocs.yml                     # MkDocs configuration
├── CITATION.cff                   # Citation metadata
├── LICENSE                        # License
├── CHANGELOG.md                   # Generated by release-please (post-release)
├── .release-please-manifest.json  # Release-please state
├── release-please-config.json     # Release-please configuration
├── .python-version                # pyenv version pin
├── justfile                       # justfile containing recipes for common tasks
├── .editorconfig                  # Ensures consistent code style across editors
└── .gitignore

Note that while it is common practice to keep the config files at the root of the repository, and this is what I recommend, it is possible to customise the location of some of them if you prefer (e.g. the path to release-please-config.json [can be specified in the release-please.yaml file for the GitHub action] (https://github.com/googleapis/release-please-action?tab=readme-ov-file#advanced-release-configuration) and the path to the mkdocs.yaml can be configured using the --config-file option and setting the path in the .readthedocs.yaml file.)

🤝 Contributing

Use conventional commit messages (feat:, fix:, docs:, etc.). Ensure:

• Lint & format clean
• Tests pass
• Docs build without warnings
• ADR drafted for architecturally significant changes

Suggestions and improvements to this template are very welcome — feel free to open an issue or pull request if you spot something that could be refined, added or removed.

📖 Citation

If used in research, cite via CITATION.cff.

🛡 License

BSD-3-Clause – see LICENSE.

Happy coding! 🚀