Environment (Python)

This guide provides Python-specific environment setup guidance for projects using the Python template toolchain. For shared baseline setup, see the environment guide.

Tooling

1. Ensure that you have installed either pipx or uv for managing Python tools.

   Note: If installing Pipx via pip, use your system Python rather than a mutable global version managed by Asdf, Mise, or Pyenv. This reduces the risk that subsequent global version changes break pipx.

2. Ensure that you have installed Copier and Hatch.

   If using Pipx:

   pipx install copier hatch
   

   If using uv:

   uv tool install copier
   uv tool install hatch
   

Git Hooks

Install Git pre-commit and pre-push hooks with a per-user pre-commit installation outside any Hatch development environment, so hooks keep working even when Hatch environments are pruned or rebuilt:

uv tool install pre-commit

pipx install pre-commit remains functionally compatible, but uv is the single documented path to match the tooling section above.

Then install the hooks in the repository:

pre-commit install --config .auxiliary/configuration/pre-commit.yaml

The hooks themselves delegate to Hatch environments, which are resolved guest-locally at hook time and never shared across the sandbox boundary. If a hook fails because its environment went stale, rebuild the project environments with hatch env prune from the project root (all environments are removed and recreated on next use) and re-run the hook.

Refreshing Environments

Remove and rebuild Hatch virtual environments after dependency or interpreter changes:

hatch env prune

Interpreter

Run Python inside the development environment:

hatch --env develop run python

Shell

Open a shell inside the development environment:

hatch --env develop shell