tschm / pytest-alembic / 33150414344

100%

main: 100%

push

github

test: gate undefined names inside doctest examples, `>>> def` bodies included.

The example fixed in #236 bound the fixture to `alembic` and then called `alembic_runner`
in the body -- an undefined name that raised `NameError` for anyone who copied it. It got
past a 100%-coverage suite, `--doctest-modules`, and a docs build, because a `>>> def ...`
body is only *compiled*: doctest sees a function definition and never resolves the names
inside it. 26 of the 60 examples under `src` are that shape, since they need a live fixture
and a database and so cannot carry doctest output. The instance was fixed; nothing stopped
the next one.

ruff does not lint code inside docstrings -- checked against exactly that shape with
`--select F821`, which reports "All checks passed" -- so this reads the examples out with
`doctest.DocTestFinder` and runs pyflakes over them, one case per documented object.

The seeding is the part that matters. Examples may reference the object being documented
and, for a method, its class; anything else they must import, because an example is
something a reader copies into their own file. The wider and more obvious choice -- seed
`vars(module)` -- makes this gate a no-op: `alembic_runner` is itself a module-level name in
`plugin.fixtures`, so seeding the module namespace finds zero problems in this package and
would have let #236's bug through unchanged. `test_the_check_sees_inside_a_def_body` pins
that down, so a later "simplification" of the seeding fails rather than silently disarming
the check.

Two real defects surfaced immediately, both in `alembic_config`'s docstring: its examples
used `@pytest.fixture` and `alembic.config.Config()` with no import line, so neither could
be copied and run. Fixed by importing what they use, which also documents what to import.

Gates: `make lint` clean; `make test` 179 passed with coverage unchanged at 100%; `make deps`
and `make docs` clean; and the floors job simulated locally
(`uv run --all-groups... (continued)

196 of 196 branches covered (100.0%)

Branch coverage included in aggregate %.

885 of 885 relevant lines covered (100.0%)

7.95 hits per line