[JarryShaw]

• Searched for similar pull requests
• Followed the coding style
• make test passes, and a test case covers the change (prose only; narrow selections below)
• Changelog entry: 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?

• docs — documentation only

---

Description

Part of #1103, round 5. This is the foundation, toolkit, dumpkit, interface and utilities slice, on main at 4c3d30163. It changes prose only: with docstrings stripped, the AST is identical on all 25 changed .py files.

• Engines:
  • The name= class-keyword collision affects every Python below 3.11, not only 3.10. Measured on 3.8.20, 3.9.25, 3.10.21 and 3.11.15.
  • _pcap_backend does import pcapkit.corekit.infoclass.
  • PyShark 3.13 support was never measured. Its line anchors are now names.
  • unsupported_reason() also runs at construction.
  • PCAP_CT.close keys on _handle.
  • PyPCAP checks the pcap module since fix(foundation): the pypcap engine raises a pcap loader's OSError instead of falling back as pcap_ct does #2132.
• Reassembly:
  • tcp.rst pseudo-code is updated for fix(reassembly): TCP completion from per-buffer gaps, mod-2**32 sequence numbers, FIN waits for reordered data #1375: FIN cuts the hole list, the hole below a missed handshake is shown, and the hole update continues across holes.
  • IP reassembly: added the fixed 60 s capture-clock timeout.
  • The "submitted for every frame" wording is fixed for IPv4 and IPv6.
  • Completion.PARTIAL no longer counts a FIN as a teardown.
  • The examples' imports are fixed.
• Registry: the meth wording in all 15 register_* wrappers in registry/protocols.py. It is a method name or a (parser, constructor) pair, as in docs(protocols): fifth whole-repo pass over link and transport protocols (#1103) #2152, docs(protocols): fifth whole-repo pass over application, misc and the protocol base (#1103) #2154 and docs(protocols): fifth whole-repo pass over internet (#1103) #2155.
• Traceflow, dumpkit and utilities:
  • Traceflow labels come from the opening packet.
  • PCAP-NG link types come from the interface.
  • register_dumper checks dictdumper.dumper.Dumper.
  • The __del__ example is corrected.
  • The utilities docstring now covers config and timestamp conversion.
• Tests:
  • tests/project/test_docs_* and the conventions test: 94 passed.
  • tests/foundation/{engines,registry}, tests/utilities and the contracts: 393 passed.
  • Reassembly, traceflow, dumpkit, toolkit and interface: 490 passed.
  • Project text and extraction tests: 99 passed.

[JarryShaw]

GOOD TO GO at b6e3ab336 (Sonnet review of 3cd45ca98, plus one precision amend that I verified).

• Engines:
  • The name= collision was reproduced on 3.7 (TypeError) and passes on 3.14. Before 3.11, ABCMeta.__new__ takes name as positional-or-keyword; 3.11 made it positional-only.
  • _pcap_backend imports only corekit.infoclass.
  • PyShark: PYTHON_CEILING, and Capture._setup_eventloop exists.
  • The unsupported_reason, PCAP_CT.close and fix(foundation): the pypcap engine raises a pcap loader's OSError instead of falling back as pcap_ct does #2132 claims match the code.
• TCP reassembly was checked against reassembly() and the hole helpers:
  • a FIN cuts holes back;
  • a sentinel hole marks a missed handshake;
  • the update continues across holes;
  • step 6 has no FIN or RST condition.
• IP reassembly:
  • DF-set and unfragmented IPv6 packets return None in every toolkit;
  • the __timeout__ = 60.0 window runs on the capture clock;
  • PARTIAL is set only when the gap is non-empty.
• Registry: all 15 wrappers were parsed with ast. Each one's guard prefix matches its doc, and the str | tuple branch indexes [1].
• Traceflow and dumpkit:
  • the opening packet labels the flow;
  • PCAP-NG link types come from the interface;
  • register_dumper checks dictdumper.dumper.Dumper;
  • the pinned Dumper text stays.
• Checks: the AST guard is OK on all 25 files. Tests: docs and conventions 94, reassembly 136, engines plus registry 221.
• b6e3ab336: the Extractor.__del__ example now names the condition under which a negative reasm_timeout fails. I confirmed it against the constructor: reassemblers are built only inside if reassembly:, per protocol flag.

[github-actions]

Coverage: 91.55% (unit tier, Python 3.15, b6e3ab336, Unit Tests run success)

Package	Statements	Missed	Branches	Partial	Cover
pcapkit (top level)	104	4	20	2	95.16%
pcapkit/const	19599	880	2618	866	92.12%
pcapkit/corekit	2589	75	816	37	96.48%
pcapkit/dumpkit	282	3	102	3	98.44%
pcapkit/foundation	2971	23	1036	25	98.80%
pcapkit/interface	138	4	52	3	96.32%
pcapkit/protocols	17418	219	4574	185	98.14%
pcapkit/toolkit	869	36	298	10	95.20%
pcapkit/utilities	504	7	146	5	98.15%
pcapkit/vendor	4432	1988	1018	167	51.87%

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

[JarryShaw]

Ready to merge at b6e3ab336.

• Review: Sonnet GOOD TO GO on 3cd45ca98. The amend rewords Extractor.__del__ precisely; I checked it against the constructor.
• CI: 58 CheckRuns passed, 0 failed, 0 pending. Required checks passed is SUCCESS. The KTLO legs raise no warnings.
• Ordering: I merged this PR into main and ran tests/project plus the root modules under the plain unittest ordering leg: 2288 tests, 0 failures, 0 errors.
• Merge order: this PR conflicts with docs(docs): fifth whole-repo pass over the non-API docs, with issue/PR roles (#1103) #2161 in pcapkit/foundation/engines/pcapng.py, a test merge showed. Whichever merges second needs a rebase, which I'll do as soon as one lands.