Skip to content

Contributing

Contributions are very welcome. Please file issues or submit pull requests in our GitHub repository. All contributors will be acknowledged, but must abide by our Code of Conduct.

Please

Setup

  1. Fork or clone the repository.
  2. `uv sync --extra dev" to install an editable version of this package along with all its dependencies (including developer dependencies).
  3. Use uv run COMMAND to run commands in the virtual environments. In particular, use uv run doit list to see available commands and uv run doit COMMAND to run a command.

Alternatively:

  1. Create a fresh Python environment: uv venv
  2. Activate that environment: source .venv/bin/activate
  3. Install dependencies and editable version of package: uv pip install -e '.[dev]'

Actions

uv run doit list prints a list of available commands.

Command Action
all Regenerate all data using example parameters.
assays Generate sample assays file.
build Build the Python package in the current directory.
coverage Run tests with coverage.
docs Generate documentation using MkDocs.
format Reformat code.
grid Generate sample grid file.
init Regenerate default parameters.
lint Check the code format.
mangle Mangle generated assay files.
people Generate sample people file.
specimens Generate sample specimens file.
test Run tests.
tidy Clean all build artifacts.
typing Check types with pyright.

Publishing

Use twine upload --verbose -u __token__ -p pypi-your-access-token dist/*.

Tooling

  • The command-line interface to Claude. I'm disgusted by the amorality of the AI industry, but am now convinced that the coding tools are here to stay: writing tests and refactoring code with Claude's help was much faster than doing it by hand.

  • uv for managing the packages and virtual environment and for running commands. It's the first time I've used it as itself rather than running uv pip whatever; never going back.

  • ruff and pyright for checking the code. ruff is a joy, but checking type annotations with pyright cost me a couple of hours. It's not the tool's fault, though: figuring out how to annotate the last 5% of the code led to me writing my first protocol and then throwing up my hands and replacing it with Any.

  • pydantic for storing and validating records, including the data that snailz generates and the parameters used in generation. I started with dataclasses, but switched as soon as I found myself1 adding methods that pydantic already had.

  • doit to run commands instead of Make. I'm more comfortable with the latter, but I recognize that writing Makefiles is a dying art.

  • mkdocs for documentation instead of Sphinx or pdoc2. I find mkdocs easier to work with than Sphinx, and pdoc doesn't support "extra" Markdown pages as well as mkdocs. (If the folks at Astral are looking for new product ideas, a better documentation generator would have at least one paying customer the day it launched…)

  • pytest, pyfakefs, and faker for testing and click for building the command-line interface instead of argparse.


  1. Well, myself and Claude… 

  2. Please don't ever use pdoc3: someone who picks a swastika as a project logo and then argues that it's just a cultural symbol doesn't deserve your downloads.