python-boilerplate

A best-practices template project for Python modules

This boilerplate gives you a production-ready Python project structure with modern tooling. Clone it, rename it, and start coding - linting, formatting, type checking, testing, and CI are already configured. No more setting up the same tools for every new project.

Setup

• Create a new repository using this template.
• Make sure that python is installed and available on system path.
• Make sure uv is installed. This usually just means python -m pip install uv.
• Rename the project using the provided script: ./rename_template.sh.
• Run make to initialize the project configuration and build everything.
• Refer to the Makefile to learn about the various operations available. Most of them are just facades for uv.

Features

• Basic project/module organization according to https://packaging.python.org
• Makefile bootstrapping script
• uv with virtual environments and project builds
• Ruff for linting and code formatting (replaces black, flake8, isort)
• Security scanning via Ruff's flake8-bandit rules
• Unit testing with pytest
• mypy for static type checking
• PEP 561 compliant (py.typed marker included)
• Publishing to PyPi.org
• vscode editor configuration including plugin recommendations, debugging support, unit test discovery and on-save formatting
• Github actions continuous integration with multi-python testing
• Dependabot for automated dependency updates
• Executable script so after package installation you can run from the CLI using my_module_cli

Resources

• http://packaging.python.org/
• https://packaging.python.org/en/latest/distributing.html
• https://pypi.org/
• https://github.com/pypa/sampleproject
• https://www.python.org/dev/peps/
• https://www.python.org/dev/peps/pep-0008/
• https://www.kennethreitz.org/essays/why-you-should-use-vs-code-if-youre-a-python-developer
• https://code.visualstudio.com/docs/python/python-tutorial

Licensing

This project is licensed under Apache License 2.0.