Home

Awesome

Python Package Template

<a href="https://github.com/browniebroke/pypackage-template/actions/workflows/ci.yml?query=branch%3Amain"> <img src="https://img.shields.io/github/actions/workflow/status/browniebroke/pypackage-template/ci.yml?branch=main&label=Test&logo=github&style=flat-square" alt="CI Status" > </a>

Project template for a Python Package using Copier.

Features

Usage

Generate a new project with:

copier copy --trust "gh:browniebroke/pypackage-template" path-to-project

This will prompt you for a few questions and create new directory with the name you used as project slug.

Note: the --trust option is required because this template may execute some tasks after generating the project, like initialising the git repo, installing dependencies and so forth. These are all listed in the copier.yml of this repo, under the _tasks key. They are all optional and safe to run. You can take my word for it, or better, check the code yourself!

Start developing

The project uses uv for dependencies management and packaging. Make sure you have it installed in your development machine. To install the development dependencies in a virtual environment, type:

uv sync

This will also generate a uv.lock file, you should track this file in version control. To execute the test suite, call pytest inside uv's virtual environment via uv run:

uv run pytest

Check out the uv documentation for more information on the available commands.

GitHub Actions

When you first push to GitHub, it'll start a ci GitHub workflow that you can see in the "Actions" tab of your repository. This workflow runs a couple of jobs:

A labels workflow will also run and synchronise the GitHub labels based on the .github/labels.toml file.

Secrets

The workflows need a few secrets to be setup in your GitHub repository:

If you have the GitHub CLI installed and chose to set up GitHub, they will be created with a dummy value (changeme).

Automated release

By following the conventional commits specification, we're able to completely automate versioning and releasing to PyPI. It runs on every push to your main branch, as part of the release job of the ci.yml workflow. You shouldn't need to create a token, but you'll need to setup trusted publisher for the project.

Trusted publisher setup

The first time you push, the workflow will try to create a release in PyPI, however the project doesn't exist there yet, which seems like a chicken and egg situation. Luckily, you can add a trusted publisher before creating the PyPI project here: https://pypi.org/manage/account/publishing/. Here are the infos that you should use:

If the release phase failed the first time, you might have to remove the release and tag from GitHub, and perhaps tidy up the changelog.

How it works

Here is an overview of what it's doing:

For more details, check out the conventional commits website and Python semantic release GitHub action.

Optional: Django package

If your package is a reusable Django app, you should answer "yes" to the question "Is the project a Django package?". This will generate a bit more boilerplate for you to make it easier to develop and test:

Migrations

You should be able to use the provided manage.py to create migrations for your reusable app. Create or change your models and run uv run python manage.py makemigrations.

Pre-commit

The project comes with the config for pre-commit. If you're not familiar with it, follow their documentation on how to install it and set it up.

Documentation

The project assumes that the documentation will be hosted on Read the Docs and written in Markdown with the MyST parser for Sphinx.

To enable it, you might need to go into your dashboard and import the project from Github. Everything else should work out of the box.

Dependencies update

The project dependencies are kept up to date with Renovate which requires the Github app to be installed.

The main advantage of Renovate over Dependabot is the auto-merge option, which is configured to automatically merge minor/patch updates with all the CI checks passing. It supports a variety of package managers, including uv, GitHub actions and pre-commit hooks which are used by default.

All contributors

This is a specification that help you highlight every open source contribution in your README. This is easy to maintain as it comes with a GitHub bot to do the updates for you, so more manual updates on the contributors file.

If you never used it before, you will have to install the Github app and give it access to your repo.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --> <!-- prettier-ignore-start --> <!-- markdownlint-disable --> <table> <tbody> <tr> <td align="center" valign="top" width="14.28%"><a href="https://browniebroke.com/"><img src="https://avatars.githubusercontent.com/u/861044?v=4?s=80" width="80px;" alt="Bruno Alla"/><br /><sub><b>Bruno Alla</b></sub></a><br /><a href="https://github.com/browniebroke/pypackage-template/commits?author=browniebroke" title="Code">💻</a> <a href="#ideas-browniebroke" title="Ideas, Planning, & Feedback">🤔</a> <a href="https://github.com/browniebroke/pypackage-template/commits?author=browniebroke" title="Documentation">📖</a></td> <td align="center" valign="top" width="14.28%"><a href="https://cloudreactor.io/"><img src="https://avatars.githubusercontent.com/u/1079646?v=4?s=80" width="80px;" alt="Jeff Tsay"/><br /><sub><b>Jeff Tsay</b></sub></a><br /><a href="https://github.com/browniebroke/pypackage-template/commits?author=jtsay362" title="Code">💻</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/34j"><img src="https://avatars.githubusercontent.com/u/55338215?v=4?s=80" width="80px;" alt="34j"/><br /><sub><b>34j</b></sub></a><br /><a href="https://github.com/browniebroke/pypackage-template/commits?author=34j" title="Code">💻</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/kroimon"><img src="https://avatars.githubusercontent.com/u/628587?v=4?s=80" width="80px;" alt="Stefan Rado"/><br /><sub><b>Stefan Rado</b></sub></a><br /><a href="https://github.com/browniebroke/pypackage-template/commits?author=kroimon" title="Documentation">📖</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/codejedi365"><img src="https://avatars.githubusercontent.com/u/17354856?v=4?s=80" width="80px;" alt="codejedi365"/><br /><sub><b>codejedi365</b></sub></a><br /><a href="https://github.com/browniebroke/pypackage-template/commits?author=codejedi365" title="Code">💻</a></td> <td align="center" valign="top" width="14.28%"><a href="https://www.habet.dev"><img src="https://avatars.githubusercontent.com/u/82916197?v=4?s=80" width="80px;" alt="Abe Hanoka"/><br /><sub><b>Abe Hanoka</b></sub></a><br /><a href="https://github.com/browniebroke/pypackage-template/issues?q=author%3Aabe-101" title="Bug reports">🐛</a></td> </tr> </tbody> </table> <!-- markdownlint-restore --> <!-- prettier-ignore-end --> <!-- ALL-CONTRIBUTORS-LIST:END -->

This project follows the all-contributors specification. Contributions of any kind welcome!