# Dependency notes for Python

`pyproject.toml` and `requirements.txt` accept comments, but a `#` line beside a version specifier has room for a few words. The parts that matter do not fit: why this package over the alternatives, why the upper bound, which tests show an upgrade is safe, and what happened the last time someone tried.

Pacmon keeps a note for each distribution in `.pacmon/python/DEPENDENCY-NOTES.md`, beside the manifest, and shows it on the dependency's line in the editor.

## What Pacmon reads

- **Manifest:** `pyproject.toml`, `requirements*.txt`, `requirements/*.txt`
- **Notes file:** `.pacmon/python/DEPENDENCY-NOTES.md`
- **Section heading:** the normalized distribution name: `## requests`, `## importlib-metadata`

Pacmon reads named dependencies in standard project metadata, optional dependencies, dependency groups and build requirements; Poetry dependency tables and groups; uv legacy development dependencies; and named pip requirements. Includes, constraints, tool options, unnamed paths and lock files are not dependencies. Package names are matched case-insensitively with `.`, `_` and `-` treated alike.

Pacmon never runs Python, pip, Poetry or uv.

## Example

```toml
[project]
name = "billing"
requires-python = ">=3.12"
dependencies = [
    "SQLAlchemy>=2.0,<2.1",
    "httpx>=0.28",
]

[dependency-groups]
dev = ["pytest>=8.3"]
```

`.pacmon/python/DEPENDENCY-NOTES.md`:

```md
## sqlalchemy

ORM and the base of the Alembic migrations. Models live in billing/db/models.py.

### Agent notes

- purpose: ORM for the billing database; the Alembic migrations build on its metadata
- constraint: stay below 2.1 until the migration tests pass on it (BILL-310)
- verify: `pytest tests/db` and `alembic upgrade head` on an empty database
- verified: 2.0.36
```

The heading is the normalized distribution name: `SQLAlchemy` is `## sqlalchemy`, and `Flask_SQLAlchemy` would be `## flask-sqlalchemy`. A package listed in both `pyproject.toml` and a requirements file of the same project shares one section.

## For AI coding agents

An agent reads a package's section before it adds, upgrades or removes the package: `constraint:` before it moves a version, `verify:` to check the result. It logs the attempt under `### Agent notes`, even when it reverts it. See [the rules agents follow](https://pacmon.dev/agents/).