python-environment

# Python Environment Set up and run commands inside the CausalPy dev environment. **uv is the default; a conda-compatible tool is the fallback** when `uv` is not available. ## Decide whether the env is required Use the project environment when the command: - imports project code (for example `import causalpy` or project modules) - runs tests - builds docs - invokes repo tooling such as `make`, `prek`, or notebook execution For simple inspection helpers that only read local text/JSON or use the Python standard library, any Python on `PATH` is acceptable. ## Default: uv ### Reuse before creating Do the least work that will get the task done: 1. Reuse an existing `.venv` (created by `uv sync`) if the checkout already has one. 2. Only run `uv sync` again when dependencies changed, the editable install is stale, or the current checkout has not been synced yet. ### Set up the environment ```bash uv sync --locked --extra dev --extra docs --extra test --extra lint uv run prek install -f ``` `--locked` fails fast if `uv.lock` has drifted from `pyproject.toml` instead of silently re-resolving. ### Run commands There is no environment to activate — prefix every command with `uv run`: ```bash uv run pytest uv run make test uv run prek run --all-files ``` ### Update the environment Re-run `uv sync --locked ...` with the same extras after pulling changes that touch `pyproject.toml` or `uv.lock`. ### Git worktrees and remote machines uv does not require a fresh `.venv` per agent session, but because this repo uses editable installs, one shared `.venv` points at whichever checkout most recently ran `uv sync`. - For ordinary local work on one checkout, reuse the existing `.venv`. - For long-lived parallel worktrees, one `.venv` per worktree is the safest option (`uv sync` inside each), but do not create one unless needed. - On a fresh remote machine or ephemeral container, run `uv sync` once. On a persistent remote machine with an existing `.venv`, reuse it. ## Fallback: conda-compatible tool Use this path only when `uv` is not available, or when the task specifically requires the conda/micromamba alternative (e.g. validating `environment.yml`). ### Detect the conda tool Use whichever of `mamba`, `micromamba`, or `conda` is available (checked in that order): ```bash # Check for mamba, micromamba, or conda (in preference order) on $PATH CONDA_EXE=$(for c in mamba micromamba conda; do command -v "$c" &>/dev/null && echo "$c" && break; done) ``` If `CONDA_EXE` is empty, no conda-compatible tool was found. Propose installing micromamba to the user: ```bash "${SHELL}" <(curl -L micro.mamba.pm/install.sh) ``` After installation, set `CONDA_EXE=micromamba`. ### Create the environment only if needed If no suitable existing env can be reused, create it: ```bash $CONDA_EXE env create -f environment.yml ``` ### Install the package only when needed Run `make setup-conda` after creating or updating the env, from inside an active/running conda env. Also rerun it when using a different git worktree if that env has not been installed against the current checkout yet. ```bash $CONDA_EXE run -n CausalPy make setup-conda ``` ### Run commands Never use `$CONDA_EXE activate`, instead use `$CONDA_EXE run -n CausalPy <command>`. ```bash $CONDA_EXE run -n CausalPy <command> ``` For example: `$CONDA_EXE run -n CausalPy pytest`, `$CONDA_EXE run -n CausalPy prek run --all-files`. ### Update an existing environment ```bash $CONDA_EXE env update --file environment.yml --prune ``` ### Troubleshooting #### Named env cannot be resolved If `$CONDA_EXE run -n CausalPy ...` fails with errors such as `The given prefix does not exist`: ```bash $CONDA_EXE env list $CONDA_EXE run -p "/full/path/to/CausalPy" <command> ``` Keep using `run -p` with that full prefix for the rest of the session. #### Updating an outdated conda tool If you hit issues with an outdated tool, update it: - **mamba / micromamba**: `$CONDA_EXE self-update` - **conda**: `conda update -n base conda` As of 2026-02-13, current versions are conda 26.1.0, mamba/micromamba 2.5.0.