test: map mypy in MODULE_PROVIDERS and name the module an unmapped lookup wanted

[JarryShaw]

Please follow the guide below

• You will be asked some questions, please read them carefully and answer honestly

• Put an x into all the boxes [ ] relevant to your pull request (like that [x])

• Use Preview tab to see how your pull request will actually look like

• Searched for similar pull requests

• Followed the coding style (make pylint, make mypy, make isort)

• make test passes, and a test case covers the change

• Added a changelog entry under docs/source/changelog/ and regenerated CHANGELOG.md, if the change is user-visible — N/A — changelog centralised in docs(changelog): shared 1.5.0 changelog — long-lived, merges last (#610, #616, #617, #618, #620) #657

What is the purpose of your pull request?

Tick the commit type your subject line carries.

• fix — corrects a defect
• feat — adds a feature
• perf — changes performance, not behaviour
• refactor — changes neither behaviour nor performance
• test — tests only
• docs — documentation only
• ci — workflows or build tooling
• chore — anything else

---

Description of your pull request and other information

Closes #779. Tests only; no pcapkit/ file is touched.

Re-derived first. Adding HAS_MYPY + skipUnless to tests/vendor/test_vendor_reg_apptype_generator_unit.py alone gives Ran 10 tests ... FAILED (failures=2, errors=5), all 5 errors a bare KeyError: 'mypy' from extras_providing. #779 says 9 tests / 4 errors because it was written against 110381b63, before #774 added test_the_vendor_extra_closes_engine_tests_but_not_test_or_gate — which is both the tenth test and the fifth error. Two numbers, one cause.

Change. MODULE_PROVIDERS['mypy'] = ('mypy',); a new DEPENDENCY_GATE_EXCLUSIONS['HAS_MYPY'] dark on test, engine-tests and gate; all three bare MODULE_PROVIDERS[...] subscripts routed through _top_level_providers(), which raises an AssertionError naming the module, the top-level key looked up, and the table to add it to (the shape _disqualified_providers already used). Mapped modules return the same tuple as before. The gate itself moves from an inline try/except ImportError: self.skipTest(...) — invisible because _gates_of() walks a decorator list, never a body, the #745 hazard #766 also carries — to the visible form, and the module docstring is rewritten, since it argued for the form being replaced.

Exclusion rationale. No pyproject.toml extra carries mypy (verified: the only such entry in the table); it is a Pipfile [dev-packages] entry that lint.yml installs directly. The fix this guard would otherwise propose — put mypy on a pytest install line — is wrong: it duplicates a whole-package check lint.yml already runs, and lint.yml runs no pytest, so pytest_jobs() never sees the job that does install it. So the gap is explained, not closed.

Gap report. 15 → 18 (flag, job) pairs; the three new rows are HAS_MYPY on test, engine-tests and gate. Not identical, and that is the point — the skip already happened on those legs, the guard just could not count it. integration and pypcap-parity select by fixture tier and never collect the module, so they are absent, exactly as for HAS_VENDOR_DEPS.

Counts. tests/test_tier_guard.py 97 → 100 tests, 512 → 524 subtests, measured under plain unittest with a subTest counter rather than trusting pytest-subtests; pytest agrees (100 passed / 524 subtests). The +12 is 5+3+0 from the three new tests, +1 each for one more gate, one more exclusion ×2, and one more gate-bearing module. Each new test was shown failing against its own mutation: entry deleted, helper reverted to the bare subscript, gate hidden from the scan. Coverage of tests/_dependency_gates.py holds at 99% with all 6 added statements executed, and the vendor module rises 88% → 91% as the now-dead except ImportError arm goes.

[JarryShaw]

Cross-review at 27d91a5a6 (sonnet, a different model from the author): GOOD TO GO, no required changes. Every load-bearing number reproduced exactly, and the tree was left clean after every probe.

The gap report is right, and for the right reason. dependency_gate_gaps() re-derived on both trees: 15 → 18 (flag, job) pairs, the three new rows all HAS_MYPY with missing=('mypy',) gates=1 on test/engine-tests/gate. The design question I asked — whether "gap classified, not closed" is the right shape for a lint-tier tool — is answered by precedent rather than opinion: HAS_SCAPY, HAS_PYSHARK and HAS_RUNTIME all use the identical Gap + Exclusion(dark=...) pattern for a deliberately-unclosed gap. Both halves of the exclusion's rationale check out too: .github/workflows/lint.yml:187 really is pip install -U vermin pylint mypy bandit, and grep -in pytest on that file returns nothing, so pytest_jobs() genuinely never sees the job that installs mypy. Pipfile:48 is mypy = "*", and pyproject.toml's only mypy hit is the substring inside mypy-extensions.

The visible-gate conversion is real, not cosmetic — which was the risk. gated_scopes() now reports exactly one new Gate(flag='HAS_MYPY', module='tests/vendor/…', lineno=222, func_name='test_undefined_member_infers_as_transport_protocol_under_mypy'), so _gates_of's decorator_list walk does see it.

The +12 subtest accounting was attributed line by line, not spot-checked: +5 / +3 / +0 from the three new tests, then test_every_gated_flag_is_classified 249→250, both exclusion tests 7→8, and test_the_suite_scan_only_looks_at_modules_pytest_collects 114→115. Sums to 12. 97→100 tests, 512→524 subtests under plain unittest with a counting TestResult, and pytest agrees at 100 passed / 524 subtests.

It settled the thing you could not. Monkeypatching importlib.util.find_spec to return None for 'mypy' in a throwaway subprocess, before importing the vendor module: HAS_MYPY reads False and the gated test gives OK (skipped=1) with reason 'mypy is not installed'. The venv was never touched.

And it corrected my own brief. I asked whether AssertionError mattered under python -O. It does not: -O strips bare assert statements, not an explicit raise AssertionError(...). I verified that myself — under -O, the explicit raise is caught normally while a bare assert False vanishes. My concern did not apply.

_top_level_providers survived edge-case attack: dotted-unmapped, empty string, and the one genuinely dotted key (pcap._pcap) all behave correctly, truncation matches the old bare-subscript behaviour at those three call sites exactly, and mapped modules return identical tuples either side. Mutations reproduced: deleting MODULE_PROVIDERS['mypy'] breaks 8 tests in the class; reverting extras_providing to a bare subscript gives KeyError: 'nosuchlinter'. Coverage confirmed at 418→424 statements, misses unchanged at 2, vendor module 88% → 91% as the dead except ImportError arm goes.

Four CI legs still outstanding (23 success, 3 expected skips, 0 failures), so this is a review verdict rather than a merge signal.