kreczko / cookie

Modern Python Package Cookiecutter

Scikit-HEP: cookie

A cookiecutter template for new Python projects, either targeting Scikit-HEP inclusion, or for general software packages - the only Scikit-HEP specific parts are in the defaults. What makes this different from other cookie cutter templates for Python packages?

• Designed from the Scikit-HEP developer guidelines: Every decision is clearly documented and every tool described.
• Template generation tested in GitHub Actions using nox.
• Seven different backends to choose from for building packages.
• Includes a backend for C++ bindings using pybind11, with wheels produced for all platforms using cibuildwheel.

Be sure you have read the Scikit-HEP developer guidelines first, and possibly used them on a project or two. This is not a minimal example or tutorial. It is a collection of useful tooling for starting a new project using cookiecutter, or for copying in individual files for an existing project (by hand, from {{cookiecutter.project_name}}/).

During generation you can select from the following backends for your package:

1. setuptools: The classic build system. Most powerful, but high learning curve and lots of configuration required.
2. pybind11: This is setuptools but with an C++ extension written in pybind11 and wheels generated by cibuildwheel.
3. poetry: An all-in-one solution to pure Python projects. Replaces setuptools, venv/pipenv, pip, wheel, and twine. Higher learning curve, but is all-in-one. Makes some bad default assumptions for libraries.
4. flit: A modern, lightweight build system for pure Python projects. Replaces setuptools, no MANIFEST.in, setup.py, or setup.cfg. Low learning curve.
5. flit621: Flit, but with PEP 621 style configuration (hidden feature).
6. trampolim: A modern PEP 621 builder with support for tasks, allowing arbitrary Python to run during the build process if needed. Python 3.7+ only (for building from source, wheels can be anything).
7. whey: A modern PEP 621 builder with some automation options for Trove classifiers.

To use:

Install cookiecutter, ideally with brew install cookiecutter if you use brew, otherwise with pipx install cookiecutter (or prepend pipx run to the command below, and skip installation). Then run:

cookiecutter gh:scikit-hep/cookie

Answer all the questions. If you are not making a Scikit-HEP repo, just enter a different org name. (You can also use pipx run cookiecutter without installing).

Check the key setup files, pyproject.toml, and possibly setup.cfg and setup.py (pybind11 example). Update README.md. Also update and add docs to docs/.

There are a few example dependencies and a minimum Python version of 3.6, feel free to change it to whatever you actually need/want.

Contained components:

• GitHub Actions runs testing for the generation itself
  • Uses nox so cookie development can be checked locally
• GitHub actions deploy
  • Be sure to add a token
  • C++ backend uses cibuildwheel for wheel builds
• Dependabot keeps actions up to date periodically, through useful pull requests
• Formatting handled by pre-commit
  • No reason not to be strict on a new project; remove what you don't want.
  • Includes MyPy - static typing
  • Includes strong Flake8 checking
  • Includes auto fixes for common flake8 problems
  • Includes Black - standardizing formatting
  • Includes isort for nice import sorting/grouping
  • Includes PyUpgrade - keeps old Python syntax out
  • Includes spell checking
• A ReadTheDocs-ready Sphinx docs folder and [docs] extra
• A test folder and pytest [test] extra
• A noxfile is included with a few common targets

Setuptools only:

• Setuptools controlled by setup.cfg and a nominal setup.py.
  • Using declarative syntax avoids needless boilerplate that is often wrong (like incorrectly handling the encoding when opening a README).
  • Easier to adapt to PEP 621 eventually.
  • Any actual logic can sit in setup.py and be clearly separate from simple metadata.
• Versioning handled by setuptools_scm
  • You can easily switch to manual versioning, but this avoids duplicating the version as git tags and in the source, and versions every commit uniquely, sidestepping some caching problems.
• MANIFEST.in checked with check-manifest
• setup.cfg checked by setup-cfg-fmt

For developers:

You can test locally with nox:

# See all commands
nox -l

# Run all tests and checks (takes several minutes)
nox

# Run a specific check
nox -s "lint(setuptools)"

# Run a noxfile command on the project noxfile
nox -s "nox(whey)" -- docs

If you don't have nox locally, you can use pipx, such as pipx run nox instead.

Other similar projects

Hypermodern-Python is another project worth checking out with many similarities, like great documentation for each feature and many of the same tools used. It has a slighly differnet set of features, and has a stronger focus on GitHub Actions - most of Scikit-HEP cookie could be adapted to a different CI system fairly easily if you don't want to use GHA. It also forces the use of Poetry (instead of having a backend selection), and doesn't support compiled projects.