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

[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:

## 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.