A reasonable modern Python cookiecutter

A reasonable modern Python cookiecutter with support for libraries, clis and services.

Not everything needs to be the fanciest and shiniest, sometimes it is better to use reasonable modern tools that will not change and fit into existing systems.

A generated example can be found at https://github.com/vikahl/python-example

Basic ideas

• Always package the Python code as a library, even if is a service that will not be distributed through PyPI. Doing this makes it easy to write tests or extend functionality in various directions.
• Use Setuptools as the build system. It is a proven build system that supports the latest standards. I do not see a reason to use another system.
• Use Github Actions to run tests configured in tox and build and upload to PyPI for libraries. Authentication is done using trusted publishers.
• Selection for library, cli and/or service support.

Template settings

• project_name: Human friendly name for the project.
• description: Short description of the project. Added to the README and package.
• module_name: Project name, following specification in PEP 508. Will be suggested based on the project name.
• author: Name of the project author. Added in package metadata (pyproject.toml) and in some cases the license.
• email: Email for the project author. Added in package metadata (pyproject.toml).
• homepage: Homepage for the project. Added in package metadata (pyproject.toml).
• license: Select a license for the project. Will add a trove classifier (in pyproject.toml) and a license file. If another license is needed they can be replaced later.
• version: Initial version.
• min_python: Minimum Python version that is supported. Tox will generate test environments for all newer versions. Backported modules might be used for older Python versions.
• library: Toggle library functions, adds a Github workflow for uploading to PyPi.
• cli: Toggle cli functions, adds a basic cli (based on Typer) with entrypoint defined in pyproject.toml.
• service: Toggle service functions, adds a dockerfile and instructions on compiled requirements.
• architecture: Set the architecture for the Dockerfile.

Linters and tools

A note about configs: This template aims to collect all configuration in pyproject.toml, except for tox which uses tox.ini until tox better supports pyproject.toml.

The linters and formatters are configured in tox and can be invoked by running tox. Github Actions ensures the same linters and formatters are run in CI.

• Setuptools: Packaging tool. Uses pyproject.toml for package configuration.
• tox: Test automation framework. Run in Github actions and can be run locally.
• Black: Code formatter, formats the code in a consistent way. No special config.
• Isort: Formats import statement to keep them consistent and tidy. Minimal config in pyproject.toml to be compatible with Black.
• Pylint: Linter. Although a bit noisy it catches many common mistake. Configured in pyproject.toml.
• Mypy: Type checker. Configured in pyproject.toml.
• Pytest: Python testing framework. Used for the tests.
• Pytest-cov: Pytest plugin to measure code coverage.
• Pip-tools (service only): Used to compile requirements for the service.

Questions, comments or thoughts

File an issue!