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

• Use Conventional Commits.
• Open an issue before creating a pull request.

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 myself¹ 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 pdoc². 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. ↩