Cookiecutter Python package repo review

From blank page to up and running in one command

The Cookiecutter website puts the draw of their program to developers quite succinctly:

For Developers

Start new projects quickly the "right way" without rebuilding the plumbing every time

For Organizations

Scale company best practices and save developer time with repeatable templates your whole team can use

They also pitch it as a way to learn a new framework/language as a beginner, which I'd not thought of it as: but I suppose I do effectively use them to study specific aspects of program organisation in isolation.

I used to use sites like Kenneth Reitz's Hitchiker's Guide To Python for this sort of study, but the website became unavailable a while ago and I've been gleaning what I can by example ever since.

cookiecutter-hypermodern-python was the package that sparked my interest in using the library, though if anything it lists a few too many tools (a "more the merrier" approach that I begin to suspect has an air of showing off or showcasing rather than practicality), and uses Poetry which I'm not keen on.

It handles the JSON transformation of variables and conditional license file creation correctly (below I review some with more awkward approaches).
It uses Nox, a relative of tox you configure with Python instead of a tox.ini file, which is satisfying in a dogfooding kind of way but isn't something I yearn for enough to switch over to, for now anyway.
- See the noxfile.py module if you're curious about how that looks.
It also uses typeguard (very neat runtime type checker I'd heard of but didn't know was a pytest plugin), and pyupgrade (which I feel could save me time when working alongside others who still use some old syntax I prefer not to see but also don't love converting by hand, like str.format() calls).
Documentation is done with Sphinx, and its plugins autodoc (auto-generating docs for modules) and napoleon (for Google-style docstrings). These are reliable staples in Python docs: check them out if you're not familiar and want a reference to begin adapting.

The official cookiecutter site links to a few example Python project templates, which I'll briefly review below.

cookiecutter-pylibrary

Enhanced template for Python libraries

This library actually rejected a suggestion to include Poetry, asking in return "what problem would this solve?" and didn't get a reply.

The tox.ini config here is pretty complex, littered with lots of if conditions which is a bit out of hand for a simple demo. Seems to do the code coverage step carefully, which may be worth reviewing if you're interested in that.

The .pre-commit-config.yaml likewise includes too many options: including the silly alternative to Black that LinkedIn put out called Blue. A little bewilderingly too many options here, perhaps developed to impress users rather than be straightforward in practice.

cookiecutter-pypackage

A Python package template

Not a whole lot here to comment on. Has a nice conditional test template that'll test the CLI if you choose to make one. I'd forgotten you could have completely empty test functions if you give a docstring. Again a little overengineered. I'm wary of templating a Makefile myself but I respect their effort!

hatch

From the Python Packaging Authority themselves:

A modern project, package, and virtual environment manager for Python

Er, despite being listed there, this project doesn't actually use cookiecutter ?

Besides the point, but the docs for this are really nice, built with mkdocs (manually handling GitHub Pages deployment in docs-release.yml)

Some links if you want to read more on this alternative to Sphinx for your docs:

cookiecutter-pytest-plugin

This is an official pytest example library,

Minimal template for authoring pytest plugins that help you to write better programs

This template has a really nice set of options that reflect the reality of packaging: you don't always want docs, and you may want to use mkdocs or sphinx for different projects; and you can even choose the license. On the downside, you have to delete the licenses directory yourself unless you want copies of irrelevant licenses lying around. I'm not sure at a glance how the docs options work here, they haven't got a conditionally generated mkdocs.yml file... 🤔

python-package-template

Project structure for your next Python package with state-of-the-art libraries and best development practices

Despite the claim to 'best practices', this one doesn't yet have code coverage, which is a pretty basic requirement for me. Again there's a _licences directory that will be unused cruft.

Uses a cache in the build.yml workflow, but otherwise for me the priorities here are all wrong. Also puts a lower() call in one of the directory names, rather than doing this in the cookiecutter.json, so URLs have brackets in which doesn't play nicely with markdown.

template-python

A template for new Python libraries

A much better set of priorities: isort, black, pylint static analysis, mypy, pydocstyle, and again mkdocs. They also helpfully provide a list of projects using the template. Once again, uses poetry to manage dependencies.

Cookiecutter Data Science

is an interesting idea, but I don't think there's such a standardised way of presenting DSci projects IRL

Some of the other repos have a bit of a "the more the merrier" approach, rather than focussing on the few tools that can bring the biggest benefit. I personally find the array of tools in some of these projects a little overwhelming, and prefer to adapt a smaller number of tools to my preferences than accept the default configs for a large number of 'best practice' tools.

This post is the 1st of Package templating, a series covering how to generate a skeleton for a Python package with minimal barrier to setup with best practices like linting, pre-commit hooks and tests on CI. Read on for discussion of Creating a Cookiecutter templated Python package