Tutorial#

Install cookiecutter#

You can install cookiecutter in any of the following ways. It is recommended to use [pipx] or [condax], so cookiecutter is centrally installed.

# using conda or mamba
conda/mamba install [-n ENVIRONMENT] cookiecutter
# using pip or pipx or condax
pip/pipx/condax install cookiecutter

Generate you package#

Generate with cookiecutter:

cookiecutter [--checkout BRANCH-NAME] https://github.com/usnistgov/cookiecutter-nist-python.git

Generate with [cruft]:

cruft create [--checkout BRANCH-NAME] https://github.com/usnistgov/cookiecutter-nist-python.git

Generate with [copier]:

copier copy --trust [-r BRANCH-NAME] https://github.com/usnistgov/cookiecutter-nist-python.git destination/path

As the template uses jinja2, you’ll need the --trust flag using copier.

Create a git repo#

cd {my-project}
# init the project
git init
# add all files (should be used with care)
git add .
git commit -m 'a meaningful message'

Using just as task runner#

The project includes a justfile to be invoked using just to simplify common tasks. Run just with no options to see available commands. Just can be installed using:

uv tool install rust-just

Using nox#

This project makes extensive use of nox to automate testing, type checking, documentation creation, etc. To see all nox session, run:

nox --list

To simplify passing options to underlying commands, the options to a particular nox session use + instead of - for options. For example, pass options to pytest, use:

nox -s test -- ++test-opts -x -v

Using + for the session option ++test-opts means we don’t have to escape -x or -v. To see all options:

nox -- ++help/+h

Note that these options should be passed after --. For example, to build and open the documentation, run:

nox -s docs -- +d build open

Update/lock/sync requirements#

The project is setup to create environment.yaml and requirement.txt files from pyproject.toml. This can be done using:

just lock/sync

This runs uv lock and update requirements files. Pass -upgrade/-U to upgrade requirements.

ipykernel#

The environments created by nox dev, or running just install-kernel, will try to add meaningful display names for ipykernel. These are installed at the user level. To cleanup the kernels (meaning, removing installed kernels that point to a removed environment), You can use the script tools/clean_kernelspec.py:

python tools/clean_kernelspec.py

Development tools#

The only required tool is uv, but it highly recommended to also install just.

Package version#

Versioning is handled by the project.version variable in pyproject.toml. Use uv version --bump to update the package version.

Using setuptools instead of hatchling#

The repo by default uses hatchling for building the package. I’ve found that setuptools is overkill for python only projects. However, if you’d like to use setuptools (if, for example, your package includes non-python code), you can use something like the following:

# pyproject.toml
[build-system]
build-backend = "setuptools.build_meta"
requires = [
    "setuptools>=61.2",
    "setuptools_scm[toml]>=8.0",
]

...

[tool.setuptools]
zip-safe = true # if using mypy, must be False
include-package-data = true
license-files = ["LICENSE"]

[tool.setuptools.packages.find]
namespaces = true
where = ["src"]

[tool.setuptools.dynamic]
readme = { file = [
    "README.md",
    "CHANGELOG.md",
    "LICENSE"
], content-type = "text/markdown" }

[tool.setuptools_scm]
fallback_version = "999"

Also remove the sections tool.hatch.version and tool.hatch.metadata.hooks.fancy-pypi-readme. You may have to add the file MANIFEST.in to include/exclude files if needed.

Tutorial

Contents