Cheshire: a Python Template Repository for Catalyst

This template repository helps make new Python projects easier to set up and more uniform. It contains a lot of infrastructure surrounding a minimal Python package named cheshire (the cat who isn't entirely there...).

Create a new repository from this template

• Choose a name for the new package that you are creating.
• The name of the repository should be the same as the name of the new Python package you are going to create. E.g. a repository at catalyst-cooperative/cheshire should be used to define a package named cheshire.
• Fork this template repository to create a new Python project repo. See these instructions.
• Clone the new repository to your development machine.
• Install pixi if you don't already have it.
• Run pixi run prek install in the newly cloned repository to install the pre-commit hooks defined in .pre-commit-config.yaml, using prek as the runner.
• Run git config merge.ours.driver true so the merge=ours rule in .gitattributes (which keeps your side of pixi.lock on conflict, rather than trying to line-merge a huge generated file) actually takes effect. Git ignores that attribute silently if this isn't set -- there's no way to configure it from within the repository itself, since a tracked file specifying an arbitrary merge driver to run would be a remote code execution risk, so every clone has to opt in locally.
• Run pixi run test from the top level of the repository to verify that everything is working correctly.

Rename the package and distribution

Once you know that your forked version of the cheshire package is working as expected, you should update the package and distribution names in your new repo to reflect the name of your new package. The package name is determined by the name of the directory under src/ which contains the source code, and is the name you'll use to import the package for use in a program, script, or notebook. E.g.:

import cheshire

The distribution name is the name that is used to install the software using a program like uv, conda, or pixi. It is often identical to the package name, but can also contain a prefix namespace that indicates the individual or organization responsible for maintaining the package. See PEP 423 for more on Python package naming conventions. We are using the catalystcoop namespace for the packages that we publish, so our pudl package becomes catalystcoop.pudl in the Python Package Index (PyPI) or on conda-forge. Similarly the cheshire package becomes the catalystcoop.cheshire distribution. The distribution name is determined by the project.name defined in pyproject.toml.

uv pip install catalystcoop.cheshire

The package and distribution names are referenced in many of the files in the template repository, and they all need to be replaced with the name of your new package. You can use grep -r to search recursively through all of the files for the word cheshire at the command line, or use the search-and-replace functionality of your IDE / text editor. The name of the package directory under src/ will also need to be changed.

• Supply any required tokens, e.g. for CodeCov.
• Rename the src/cheshire directory to reflect the new package name.
• Search for cheshire and replace it as appropriate everywhere. Sometimes this will be with a distribution name like catalystcoop.cheshire (the package as it appears for uv or PyPI) and sometimes this will be the importable package name (the name of the directory under src e.g. cheshire).
• Enable GitHub Pages for the new repository (Settings -> Pages -> Source: GitHub Actions) so the docs workflow can publish the documentation.

What this template provides

See the Tooling docs for details on all of the tooling this template sets up:

• Python Package Skeleton
• Environment & Task Management with Pixi
• Devcontainer
• Pytest Testing Framework
• Git Pre-commit Hooks
• Git Attributes
• Code Formatting & Linting
• Type Checking
• Code & Documentation Linters
• Test Coverage
• Documentation Builds
• Documentation Publishing
• Dependabot
• GitHub Actions

About Catalyst Cooperative

Catalyst Cooperative is a small group of data wranglers and policy wonks organized as a worker-owned cooperative consultancy. Our goal is a more just, livable, and sustainable world. We integrate public data and perform custom analyses to inform public policy (Hire us!). Our focus is primarily on mitigating climate change and improving electric utility regulation in the United States.

Contact Us

• For general support, questions, or other conversations around the project that might be of interest to others, check out the GitHub Discussions.
• If you'd like to get occasional updates about our projects sign up for our email list.
• Want to schedule a time to chat with us one-on-one? Join us for Office Hours.
• More info on our website: https://catalyst.coop
• For private communication about the project or to hire us to provide customized data extraction and analysis, you can email the maintainers: pudl@catalyst.coop.