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:
- setuptools: The classic build system. Most powerful, but high learning curve and lots of configuration required.
- pybind11: This is setuptools but with an C++ extension written in pybind11 and wheels generated by cibuildwheel.
- 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.
- flit: A modern, lightweight PEP 621 build system for pure Python projects. Replaces setuptools, no MANIFEST.in, setup.py, or setup.cfg. Low learning curve.
- pdm: A modern, less opinionated all-in-one solution to pure Python projects supporting standards. Replaces setuptools, venv/pipenv, pip, wheel, and twine. Supports PEP 621, and also the unaccepted PEP 582.
- trampolim: A modern PEP 621 builder with support for tasks, allowing arbitrary Python to run during the build process if needed.
- whey: A modern PEP 621 builder with some automation options for Trove classifiers. Development seems to be stalled, possibly.
- maturin: A PEP 621 builder for Rust binary extensions.
- hatch: A package manager similar to Poetry/PDM.
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.7, feel free to change it to whatever you actually need/want.
- 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
- An pylint nox target can be used to run pylint, which integrated GHA annotations
- 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 nominalsetup.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-manifestsetup.cfg
checked by setup-cfg-fmt
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.
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 slightly different 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.