tschm / pytest-alembic / 32861373584

95%

main: 100%

push

github

docs: document every symbol, taking docstring coverage to 100%

The interrogate ratchet stood at 70% against a measured 71.7%, with 34 of 120
symbols undocumented. This documents all 34 and moves `fail-under` to 100, so the
floor is now the measured number and cannot silently erode.

Eight module docstrings say what each module is *for* and how it relates to its
neighbours — the two executors, the flattened history, the revision data, the
configuration surface, the fixtures, the default tests, and the two experimental
ones. The rest are the functions that carry real behaviour worth explaining:

- `CommandExecutor.run_command` — why stderr is discarded, and why the buffer
  position is recorded before the command rather than read from the start.
- `ConnectionExecutor.table` / `table_insert` — the per-revision reflection cache,
  and the `__tablename__` key that overrides the `tablename` argument.
- `AlembicHistory.validate_revision` and the four walk methods — `head` coercing
  to `heads`, and what `None` means at each end of the range.
- `check_revision_cycle` — why the comparison is between two rendered DDL diffs
  rather than two reflected `MetaData` objects, and why every step rolls back even
  on success.
- `WrappingConnection` — that alembic's `env.py` calls `connect()`, which would
  otherwise open a second connection outside the test's open transaction.
- `Config.make_alembic_config`, `duplicate_alembic_config`, `parse_collection_output`,
  `url_to_string`, `create_connectable` and the remaining constructors.

Two doctests come with them, on `revision_window` and `set_revision`; `pytest`
runs docstrings under `--doctest-modules`, so both are executed rather than
decorative. Test count goes 122 to 124.

No behaviour changes: `make lint` and `make test` pass, `make docs-coverage`
reports 120/120.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

197 of 222 branches covered (88.74%)

Branch coverage included in aggregate %.

861 of 896 relevant lines covered (96.09%)

14.41 hits per line