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
│   ├── index.md                  - Main page
│   ├── changelog.md              - Changelog file
│   ├── 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.yml                   - Deploy website
│   ├── lint.yml                  - Check code with ruff
│   ├── type.yml                  - Check static typing with ty
│   ├── tests.yml                 - Run unit tests
│   └── pypi.yml                  - New PyPI release
├── pyproject.toml            - Configuration, metadata, dependencies
├── README.md                 - Project overview, generated by README.qmd
├── justfile                  - Common commands needed when developing
├── LICENSE                   - License file
├── .gitignore                - Git ignore rules
├── .pre-commit-config.yml    - Pre commit hooks
├── release.sh                - Trigger PyPI release
└── mkdocs.yml                - Documentation website configuration



How to use this template

You'll need the following to use this template:

  • Git: version control
  • uv: package and project manager
  • just: a command runner (alternative to make)

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
  • Rename the package_name directory with your actual package
  • Replace info in pyproject.toml
  • Change the LICENSE file to your actual license (optional)


Initialize the project

just init


Run tests

just test

To generate a code coverage badge and see your code coverage, run:

just coverage


Documentation website

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

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

  • Preview locally:
just preview
  • 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 ./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.yml

  • 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.

Since the distribution of new versions is reserved for a few people, feel free to remove it from the git tracker with:

git rm --cached release.sh

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



Still have some questions? Open an issue!