Python project template

An opinionated Cookiecutter template for Python projects.

Features

• Provide a src/ layout.
• Package metadata into setup.cfg.
• Command-line argument parsing with argparse or Click.
• Extensive linting with Flake8, isort and Mypy.
• Code formatting with Black.
• Unit testing with Pytest and Coverage.py.
• Sphinx support with automatic API documentation.
• Automated testing with tox.
• Git repository initialization.
• Continuous integration with GitLab CI or Travis CI.

References

• https://hynek.me/articles/testing-packaging/
• https://blog.ionelmc.ro/2014/05/25/python-packaging/#the-structure
• https://github.com/python-attrs/attrs
• https://github.com/audreyr/cookiecutter-pypackage/

Quickstart

Install the latest Cookiecutter if you haven't installed it yet, preferably in a virtualenv:

pip install cookiecutter

Generate a Python package project:

cookiecutter . -o ~/repos/

Configuration

The following configuration keys are available:

author_name and author_email: Name and email address of the author. Used in package metadata.

project_title: The project display title, with capitals, whitespaces and whatnots. Used in the README file and in the project documentation.

project_slug: The lowercase, dash-separated version of the project title. Used as toplevel directory name and in package metadata.

project_description: A short sentence to describe the project. Used in the README file, project docstrings and package metadata.

project_url: Homepage of the project. Used in package metadata.

project_license: License of the project. Used to generate the license file and in package metadata.

project_copyright: Copyright notice. Used in the project documentation and package metadata.

project_package: Name of the toplevel Python package.

project_prog: If the project is a program, the name of the main console script.

version_scheme: Versioning scheme used by the project, either semantic versioning or calendar versioning. Used in the project changelog.

project_version: The initial project version.

python_min_version: Minimum Python version to be supported.

cli_parser: Command-line parsing library to use in the entry point, either Click or argparse. If not set, no console script is generated.

linter: Optional source code linter (Flake8).

type_checker: Optional type checker (Mypy).

code_formatter: Optional source code formatter (Black).

test_suite: Optional framework to run unit tests (Pytest with Coverage.py).

doc_generator: Optional documentation generator (Sphinx).

vcs: Optionally initialize a new SCM repository (Git).

ci: Optionally generate a CI configuration file. Both GitLab CI and Travis CI are supported.