garysmall/wolt-python-package-cookiecutter

Cookiecutter for rapidly creating modern & high-quality Python packages

Wolt Python Package Cookiecutter

A cookiecutter (project template) for rapidly developing new open source Python packages. Best practices with all the modern bells and whistles included.

Example projects which use Wolt Python Package Cookiecutter

• jerry-git/pytest-split

Features

Automatic updates to the projects generated from this cookiecutter

• Powered by cruft
• Keep your project up-to-date with best practices

Continuous integration

• Powered by Github Actions
• Testing against multiple different versions

Documentation

• Automatically published as GitHub Pages
• Powered by mkdocs-material
• Auto-generated API documentation from docstrings via mkdocstrings
• See the extensive list of MkDocs plugins which can help you to tune the documentation to fit your project's needs

Automated releases

• Publishing to PyPI when a release is made in GitHub

Changelog management

• Gently enforced: Keep a Changelog
• GitHub releases get their description automatically populated based on the changelog content
• The Unreleased section is automatically updated when a release is done
• Changelog is embedded in the documentation

Bells and whistles

• Poetry for managing dependencies and packaging
• pre-commit for running all the goodies listed below
• mypy for static type checking
• flake8 (with multiple plugins) for linting (e.g. style and complexity checks, commented code, etc.)
• black for auto-formatting the code
• isort for auto-sorting imports
• autoflake for auto-removing unused imports

Automation

• Updates to the best practices (via GHA workflow which runs cruft update and creates a PR)
• Dependency updates (via GHA workflow which creates a PR)

Usage

Make sure you have cruft installed. Alternatively, you can use cookiecutter if you are not interested in getting updates to the project "boilerplate" in the future.

Create a new project:

cruft create https://github.com/woltapp/wolt-python-package-cookiecutter

The CLI interface will ask some basic questions, such the name of the project, and then generate all the goodies automatically.

After that you can make it a proper git repo:

cd <your-project-slug>
git init
git add .
git commit -m "Initial project structure from Wolt Python Package cookiecutter"

We update this cookiecutter template regularly to keep it up-to-date with the best practices of the Python world. You can get the updates into your project with:

cruft update

Configure secrets

PYPI_TOKEN

Required for publishing the package to PyPI. You can generate a token by logging into PyPI and navigating to Add API token in your account settings.

AUTO_UPDATE_GITHUB_TOKEN

This cookiecutter template comes with an auto update feature if the project was created using cruft. A GitHub action automatically checks for updates and creates a pull request.

Generate personal access token and use it as the value for AUTO_UPDATE_GITHUB_TOKEN secret. When creating the access token, the following permissions have to be granted

• repo
• workflow

After the first release

The first release will create gh-pages branch which will contain the static files for the documentation. Enable GitHub Pages in the Pages section of the repository settings.