# Plumbum Agent Notes

Single-package library (`plumbum/`). Build: hatchling + hatch-vcs. Python 3.9+.
Always run `prek -a --quiet` (prek is a pre-commit rewrite in Rust) to make
sure linting/formatting/type check passes.

## Developer commands (use `uv run`)

- `uv run pytest` — run tests
- `uv run pytest --cov` — with coverage
- `uv run pytest --run-optional-tests=ssh,sudo` — include optional suites (see below)
- `uv run nox -s lint` — pre-commit via prek (ruff + mypy + codespell + etc.)
- `uv run nox -s pylint` — pylint only
- `uv run nox -s tests` — run tests via nox across Python versions
- `uv run nox -s docs` — build docs; auto-serves by default, add `--non-interactive` to build only
- `uv run nox -s docs -- -b linkcheck` — check doc links
- `uv run nox -s build` — build sdist/wheel
- `uv run pytest tests/test_something.py::test_name` — run a single test

## Testing gotchas

- **Optional test markers** (`ssh`, `sudo`) are skipped unless you pass `--run-optional-tests=ssh,sudo`.
  - `ssh` tests need passwordless SSH to `localhost` configured.
  - `sudo` tests need passwordless sudo.
- Tests force `LANG=C` in `conftest.py` for consistent locale behavior.
- `PYTHONTRACEMALLOC=5` is set when tests run via nox (matching CI).
- pytest timeout is 300s.

## Code quality

- Pre-commit runs: ruff (check + format), mypy, codespell, validate-pyproject, RST hooks.
- pylint is run separately via nox, not in pre-commit.
- mypy is strict and targets Python 3.9 syntax.
- Ruff uses `plumbum._compat.typing` as the typing module.

## Generated files

- `plumbum/version.py` is auto-generated by hatch-vcs from git tags. **Do not edit manually.**
- Run `./translations.py` to regenerate gettext `.pot`/`.po`/`.mo` files for CLI i18n (requires `xgettext`, `msgmerge`, `msgfmt`).

## Docs

- Sphinx with Furo theme. Source in `docs/`.
- `docs/conf.py` imports `plumbum.version`, so an editable install must be importable when building.
