Skip to content

Python package template

A python package template that contains everything you need to:

  • create
  • configure
  • test
  • document
  • deploy


root/
├── package_name/             - Main package directory
│   ├── __init__.py
│   └── main.py/
├── tests/                    - Unit tests
│   ├── __init__.py
│   └── test_main.py
├── docs/                     - Documentation
│   ├── README.qmd                - Quarto document that generates README.md
│   ├── index.md                  - Main page
│   ├── contributing.md           - A contributing guide
│   ├── examples.md               - Usage examples
│   ├── stylesheets/              - CSS for the documentation
│   └── reference/                - API reference of the package
├── .github/workflows/        - CI/CD
│   ├── doc.yaml                  - Deploy website
│   ├── lint.yaml                 - Check code with ruff
│   ├── tests.yaml                - Run unit tests
│   └── pypi.yaml                 - New PyPI release
├── scripts/                  - Miscellaneous
│   ├── release.sh                - Trigger PyPI release
│   └── coverage.sh               - Create/update/display code coverage
├── pyproject.toml            - Configuration, metadata, dependencies
├── README.md                 - Project overview, generated by README.qmd
├── LICENSE                   - License file
├── .gitignore                - Git ignore rules
├── .pre-commit-config.yaml   - Pre commit hooks
└── mkdocs.yaml               - Documentation website configuration

How to use this template

Go to the Github repo here.

Create a new repo

  • Click on Use this template and Create a new repository
  • Clone your repo
git clone https://github.com/your_name/package_name.git

Replace with your package info

  • Replace all your_name with your GitHub username or organization
  • Replace all package_name with your actual package
  • Replace info in pyproject.toml
  • Change the LICENSE file to your actual license (optional)

Install dependencies

uv sync --all-groups
uv pip install -e .
uv run pre-commit install

Run tests

uv run pytest

To generate a code coverage badge and see your code coverage, run ./scripts/coverage.sh

Documentation website

The documentation is based on mkdocstrings, but feel free to use another framework.

You only have to set up GitHub Pages to the gh-pages branch, and .github/workflows/doc.yaml will handle the deployment.

  • Preview locally:
uv run mkdocs serve
  • Footer of the site:

The footer of the documentation website is defined in overrides/partials/footer.html. If you don’t know HTML/CSS, chatGPT can help you here!

  • Change main color:

In docs/stylesheets/style.css, change the color value to change the overall style of site:

:root {
  --primary-color: #0096c7;
}

Make a new PyPI release

New PyPI releases are made via 2 scripts:

  • release.sh

  • When you run .scripts/release.sh 1.0.0 (to release the 1.0.0 version, for instance), it will commit, tag that commit and push.

  • .github/workflows/pypi.yaml

  • When a git tag matching v1.2.3 format is pushed, it will make a new PyPI release (in short).

This relies on trusted publishing, which you need to configure. This step is important (on security aspects), so make sure you understand what is happening. Feel free to spend some time reading the scripts and the official documentation.

If you don’t plan to make PyPI releases, just delete .scripts/release.sh and .github/workflows/pypi.yaml.

Update the README

The README.md file is dynamically generated by docs/README.qmd, a Quarto document.

This is optional (you can use a plain README.md and delete docs/README.qmd), but it has many benefits:

from package_name import add_digit

# The output here is not hardcoded
print(add_digit(2, 5))

7

It works perfectly well with most IDEs. You can install Quarto here.

To generate README.md, run (make sure your venv is activated):

quarto render docs/README.qmd --output-dir ..



Still have some questions? Open an issue!