The Cookiecutter website puts the draw of their program to developers quite succinctly:
Start new projects quickly the "right way" without rebuilding the plumbing every time
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
toxyou configure with Python instead of a
tox.inifile, 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.pymodule if you're curious about how that looks.
- See the
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
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.
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.
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.
.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.
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!
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
Some links if you want to read more on this alternative to Sphinx for your docs:
- Guide to documenting a Python package with
- The best MkDocs plugins and customizations
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
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... 🤔
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.
A template for new Python libraries
A much better set of priorities:
pylint static analysis,
mkdocs. They also helpfully provide a list of projects using the template. Once again,
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