The xcookie Module

The xcookie module. A helper for templating python projects.

The goal is to be able to setup and update Python project structures with consistent boilerplate for things like CI, setup.py, and requirements.

It handles:

• Multiple version control remotes:

  • Github

  • Gitlab

• pure python packages

• python packages with scikit-build binary extensions

• rotating secrets

• CI scripts for github or gitlab where the general pattern is:

  • Lint the project

  • Build the pure python or binary wheels

  • Test the wheels in the supported environments (i.e. different operating systems / versions of Python)

  • Optionally sign the wheels with online GPG keys

  • Upload the wheels to test pypi or live pypi.

This is primarily driven by the needs of my projects and thus has some logic that is specific to things I’m doing. However, these are all generally behind checks for the “erotemic” tag. I am working on slowly making this into a proper CLI that is externally usable.

The top level CLI is command-oriented:

usage: xcookie [-h] [--version] {generate,bump,refresh-docs,rotate-secrets} ...

commands:
  {generate,bump,refresh-docs,rotate-secrets}
    generate            generate or update project boilerplate
    bump                bump the package version and changelog
    refresh-docs        regenerate Sphinx API documentation
    rotate-secrets      rotate CI secrets for an existing repository

Run xcookie generate --help for the project-generation options.

Version bumps are a separate maintenance command. They update the authoritative package version and roll CHANGELOG.md from the current release into the next Unreleased section:

xcookie bump              # patch, by default
xcookie bump patch
xcookie bump minor
xcookie bump major
xcookie bump 2.0.0        # explicit target version

Invocations to create a new github repo:

# Create a new python repo
xcookie generate --repo_name=cookiecutter_purepy --repodir=$HOME/code/cookiecutter_purepy --tags="github,purepy"

# Create a new binary repo
xcookie generate --repo_name=cookiecutter_binpy --repodir=$HOME/code/cookiecutter_binpy --tags="github,binpy,gdal"

Given an initialized repository the general usage pattern is to edit the generated pyproject.toml and modify values in the [tool.xcookie] section and then rerun xcookie generate in that directory. It will then present you with a diff of the proposed changes that you can reject, accept entirely, or accept selectively.

For some files where the user is likely to do custom work, xcookie won’t try to overwrite the file unless you tell it to regenerate it. The setup.py is the main example of this, so if you want xcookie to update your setup.py you would run xcookie generate --regen setup.py

Documentation refresh is also a separate maintenance command:

xcookie refresh-docs

Secret rotation is a separate maintenance command rather than a generation option:

xcookie rotate-secrets

The command loads the repository’s xcookie configuration, prints the commands it plans to run, and asks for confirmation before executing them.