Cookiecutter Python

A simple cookiecutter for any Python package.

Easily publish to PyPI from your local machine or automated via Github actions.

Automated linting and testing, locally and on Github.

Ready-to-use documentation and api-docs pipeline.

Features

• Ready-to-release:
  • Extensive documentation on how to release your package
  • Github actions to run tests and release to PyPI
  • Makefile targets to test, build and release your code from your local machine
• Easy documentation: ready-to-rumble, Read the Docs compatible sphinx configuration with Markdown support ((almost) no more Restructured Text)
• Poetry dependency management
• Test pipeline with pytest and tox
• Linting and code check pipeline with pre-commit, including:
  • black - the uncompromising code formatter
  • ruff - all in one, super fast linter written in rust. Combines functionality of flake8, isort, pydocstyle and many other tools.
  • mypy - check code, find type errors
  • yamllint - print warnings about badly formatted yaml files

Inspired by cookiecutter-pypackage.

Requirements

• This cookiecutter makes use of new features from Poetry 1.2.0 released on 2022-08-31. Make sure to follow the upgrade process if you are still running an older version of poetry.

Usage

# install cookiecutter and poetry into the current environment for the current user
pip install --user cookiecutter poetry

cookiecutter gh:mariushelf/cookiecutter_python
cd <your_project_slug>

# Write your code and tests now.
# Document everything in Markdown.

# Then run your tests with different Python versions (using tox):
make test

# Generate documentation
make docs

# and publish your code
make publish

# Or push to Github and create a Github release which gets automatically published
# to PyPI.

Development

Running tests

The CI/CD pipeline checks all aspects of the cookiecutter template, including the test that the template build, and that its own linting and tests pass.

To run the tests locally, you can use the following command:

# run in current Python environment
make test

# run in all supported Python versions
make test-all

Troubleshooting

• mypy checking can find a lot of bugs without even running the code, but sometimes it is too strict. There are a lot of things you can configure, but if it's a one of on just one or two lines of your code, you can tell mypy to ignore that specific line by appending # type: ignore to it.
• The required version of poetry is 1.2.0. If you get problems regarding poetry or the pyproject.toml, make sure to check your poetry version and update it if necessary.