A GitHub template with my python package configurations.
To make sure that the all the tools are available in your virtual environment (and that you are running your code with its latest modifications), install the package in editable mode by running:
pip install --editable ".[dev]"Important
Please note that this template represents my personal understanding of the current best practices.
It is advised to do further research before implementing these configurations in your environment.
Feel free to open a new issue if you have any questions or suggestions.
This template package relies on the synchronized cooperation of several exceptional tools.
These tools include:
- Codecov - Code coverage
- Pre-Commit - Git hooks running on commits
- Hatch - Package building
- MyPy - Static type checking
- Pytest - Testing and code coverage
- Ruff - Formatting and linting
- Tox - Orchestration of the above tools
For documentation:
- Sphinx - Documentation building
- ReadTheDocs - Documentation hosting
- GitHub Pages - Documentation hosting
Codecov is used to check the code coverage of the tests.
It also provides a badge that can be added to the README file.
Codecov is set up to be part of the tox reusable workflow, but for this action it is important to generate the coverage report using the --cov-report=xml flag in the pyproject.toml file.
Pre-Commit is used to run certain checks on the code before it is committed.
These checks are defined in the .pre-commit-config.yaml file.
To use pre-commit is has to be installed in the virtual environment and also added to the git hooks by running pre-commit install.
In this repository pre-commit is set up for a number of general issues and to run formatting and linting checks with ruff.
Call pre-commit by running:
pre-commit run --all-filesHatch is primarily used to build the package, but it can also be used to run certain tests in isolated environments.
If the package building is more complex and requires additional settings or files it is recommended to read the hatch documentation.
In this repository hatch is set up with the local path of the package as it differs from the one specified in the pyproject.toml file which is used for publishing to PyPI.
The isolated environment settings for hatch are defined in the hatch.toml file.
I was thinking about replacing tox with hatch, but for now tox fits more into my workflows.
Python by default is a dynamically typed language, but being explicit about types can help to avoid bugs.
MyPy makes sure that the types are correct and consistent throughout the code.
The mypy related settings are defined in the pyproject.toml file.
In this repository MyPy is set up be strict and it also checks for some additional issues.
Call mypy by running:
mypy src testsPytest is a modern testing framework for python.
It is way too complex to explain it here, but it runs all the tests from the tests directory and also checks the code coverage.
Its settings are defined in the pyproject.toml file.
Call pytest by running:
pytestRuff is a formatter and linter that is built on top of a lot of open source tools.
It is very fast and unifies all the useful code quality solutions into a single tool.
By default it is not too strict, but I like to make it strict by selecting all the available rules.
The exact configuration is defined in the ruff.toml file.
If for some reason it makes sense not to comply with a certain rule, it can be disabled for that line using # noqa: <rule number>.
Call ruff by running:
ruff check src testsTox is useful for running the above tools in an isolated environment.
It makes sure that the package setup is consistent and that the tools are working as expected.
It can be used to test different python versions and different testing scenarios.
In this repository tox is set up to use python 3.11, 3.12 and run pytest, ruff, mypy and documentation tests.
The settings are specified in the tox.ini file.
Call tox by running:
toxThe documentation is built with Sphinx and it is hosted both on ReadTheDocs and GitHub Pages.
Both of these services are recommended, however ReadTheDocs requires a bit more setup, but I prefer it as it does not require an extra feature branch to be present.
The following settings are enabled in my repository settings:
Code/About:
- Releases
General/Features:
- Issues
- Preserve this repository
General/Pull Requests:
- Allow merge commits
- Allow squash merging
- Allow rebase merging
- Automatically delete head branches
Branches/Branch protection rules:
main
Protect matching branches
- Require pull request reviews before merging
- Dismiss stale pull request approvals when new commits are pushed
- Require status checks to pass before merging
pre-commit.ci - prtox / tox (3.11)tox / tox (3.12)
- Do not allow bypassing the above settings
Environments:
pypi
- Deployment protection rules:
- Required reviewers:
daniel-mizsak - Allow administrators to bypass configured protection rules
Pages/Build and deployment:
- Source: Deploy from branch
- Branch:
gh-pages(root)
Add a new pending publisher:
- PyPI Project Name:
python-package-template-pypi(has to match the project name inpyproject.toml) - Owner:
daniel-mizsak - Repository name:
python-package-template - Workflow name:
release.yml
(I am currently not using trusted publishing, as it does not support getting called from a reusable GitHub workflow.
Instead, I am calling my PyPI publishing workflow with an API token.)
I am trying to use this template in all of my repositories and also contribute back here with new best practices I find. Some of my other repositories that may be interesting to look at:
- falcon-formation - Create evenly distributed hockey teams.
- checkmark - Automated assessment generator and evaluator system.
- pythonvilag-website - Source code that powers the Python Világ website.
- private-lecture-automation - Automation tools for private lecture management.
I have also integrated some of the above mentioned tools into my vscode settings. You can find them in my macos-setup repository.