feat(engines): type the third-party engine packages with local stubs (#1878)

[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. Narrow runs only, listed below.

• Added a changelog entry under docs/source/changelog/ and regenerated CHANGELOG.md, if the change is user-visible: N/A — 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
• release — bumps the version or rolls up a distribution
• chore — anything else

---

Stacked on #1870. It contains #1870's commit until that merges, so merge #1870 first. This PR's own commit is efdbffa95.

• Local stubs under typings/ type the dpkt, pyshark, pcap (pypcap and pcap-ct) and pypcapfile packages, declaring only what pcapkit uses. mypy.ini registers them through mypy_path, and they are not in the sdist or wheel.
• Each engine's _expkg is annotated with its own Protocol in the module-level TYPE_CHECKING block. Scapy's uses scapy's own types. At runtime nothing changes: importing an engine module loads none of the engine packages.
• The fixes the stubs prompted are annotation gaps, not runtime bugs. DPKT's PCAP reader yields a Decimal timestamp for nanosecond files, and its PCAP-NG option reads were missing casts.
• mypy reports no new errors. make mypy's whole-package count drops by two.
• stubtest is clean for dpkt, pyshark and pypcapfile. For pcap-ct the only report is its extra datalink argument, which the stub leaves out on purpose so it matches both pcap distributions.
• tests/project/test_engine_stubs_1878_unit.py fails on docs: let autodoc resolve the HTTP/2 frame and engine class annotations (#1857) #1870's head and passes here. A merge with docs(foundation): restore Extractor._vfunc's annotation (#1839) #1867's branch is clean and adds no mypy errors.

Closes #1878

[JarryShaw]

Verdict: GOOD TO GO at efdbffa95. A Sonnet cross-review found no runtime change and no new mypy error.

• Runtime is unchanged. Every executable change under pcapkit/ is a cast, an annotation, a type comment or a name inside TYPE_CHECKING. In a fresh process, importing each engine module loads none of dpkt, scapy, pyshark, pcap or pcapfile.
• mypy. Diffing the error lists themselves, not their counts, shows no new error under the Makefile flags, under mypy.ini alone, or with --python-version 3.10. The two errors that disappear are DPKT's yield error and its unused type: ignore.
• The stubs are in use and accurate.
  • mypy now resolves calls through _expkg to the stub types, and mypy typings is clean.
  • stubtest passes for dpkt and pyshark, and it does catch a deliberately broken stub.
  • The pcap and pcapfile stubs match pypcap 1.3.0, pcap-ct 1.3.0b3 and pypcapfile 0.12.0 source when read by hand.
• The test is real. On docs: let autodoc resolve the HTTP/2 frame and engine class annotations (#1857) #1870's head it gives 56 failed, and each of six single mutations fails it for the matching reason. From the sdist, which has no mypy.ini or typings/, the stub checks skip.
• Packaging. Neither the sdist nor the wheel contains typings/, with or without prune typings, as the MANIFEST.in comment says.
• Not run: pylint, a Sphinx build, and stubtest for pcap and pcapfile, which are not installed here.
• Note, not a blocker: typings/pcap/__init__.pyi:3 opens with "Two distributions install this module". It names both right after, but "More than one distribution" would avoid the count.

Merge #1870 first: this PR is stacked on it.

[JarryShaw]

resolve conflicts

[JarryShaw]

On it. #1870 merged as a squash, so this branch is being rebased onto main with only its own commit replayed. The review label resets when the new head is pushed.

[JarryShaw]

Verdict: GOOD TO GO at 053c4f0d6. This is the rebase onto main (0de96b457) after #1870 merged.

• git range-diff shows only the pcap stub docstring changed, reworded so it states no count. The stub's code diff is otherwise identical.
• test_engine_stubs_1878_unit.py, docs: let autodoc resolve the HTTP/2 frame and engine class annotations (#1857) #1870's annotation test and test_tier_guard.py pass.
• mypy over pcapkit/ adds no errors compared with main. The same two dpkt errors as before disappear.

[github-actions]

Coverage: 90.05% (unit tier, Python 3.15, 053c4f0d6, Unit Tests run success)

Package	Statements	Missed	Branches	Partial	Cover
pcapkit (top level)	104	2	20	2	96.77%
pcapkit/const	19595	881	2618	867	92.11%
pcapkit/corekit	2462	69	780	35	96.55%
pcapkit/dumpkit	276	3	100	3	98.40%
pcapkit/foundation	2914	164	1016	34	93.59%
pcapkit/interface	138	7	52	5	93.68%
pcapkit/protocols	17406	224	4580	189	98.10%
pcapkit/toolkit	872	177	298	8	77.18%
pcapkit/utilities	512	2	158	4	99.10%
pcapkit/vendor	4407	2342	1010	157	43.27%

Per-file detail: the coverage-html artifact of this run.