Skip to content

docs(toolkit): drop agreement claims from adapter docstrings (#1708) - #1741

Merged
JarryShaw merged 1 commit into
mainfrom
docs/1708-agreement-docstrings
Oct 14, 2026
Merged

JarryShaw merged 1 commit into
mainfrom
docs/1708-agreement-docstrings

Conversation

@JarryShaw

Copy link
Copy Markdown
Owner

Please follow the guide below

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

Refs #1708 (phase 3b). This PR removes the agreement claims from the adapter docstrings, following the best-effort ruling on #1687. The docs pages were fixed in d06701064.

  • It rewrites or drops 14 agreement clauses across foundation/engines/{dpkt,pypcapfile,pyshark}.py, foundation/extraction.py, toolkit/{dpkt,pyshark}.py and foundation/reassembly/ip.py. Every replacement claim was checked against the code, for example the Loopback families {2, 24, 28, 30} and localcontext(prec=64).
  • The change is docstring- and comment-only: with docstrings stripped, the AST of all seven modules is identical to main. Four paragraphs are reflowed (whitespace only).
  • Guard: tests/project/test_no_engine_agreement_prose_1708_unit.py scans pcapkit/**/*.py and docs/**, with reST markup stripped first. It fails on main with 19 hits and passes here. Legitimate uses such as pypcap-parity and the pcap-ct comparisons stay clean. Two hits sit in files the open feat(utilities): one config module for the tunable limits (PCAPKIT_* environment variables), and one home per duplicated protocol constant #1726 work owns and are allowlisted with that reason.
  • Sphinx warnings are the same set before and after.

Third-party engines are best effort (#1687), so the docstrings and
comments stop saying an adapter does what another engine does:

- toolkit/dpkt: six clauses ("as the default engine hands over", "as
  every engine's adapters do", "in every other engine", ...)
- toolkit/pyshark: the epoch, tunnel, fixed-header and SPB notes
- engines/dpkt: the SPB, Loopback, packet-block and raw-fallback notes
  now say what the engine does
- engines/pyshark: packet records are counted by the engine itself
- engines/pypcapfile: a zero-length record no longer cites the default
  engine
- extraction: record_header no longer compares to the built-in engines
- reassembly/ip: a Total Length of 0 no longer claims every adapter

tests/project/test_no_engine_agreement_prose_1708_unit.py scans
pcapkit/ and docs/source/ (changelog excluded) for those shapes, with
whitespace, comment markers and reST markup normalised. It fails on
d067010 with 19 hits and passes here; two hits in files #1726 owns
are listed as pending.

Docstring- and comment-only: the AST with docstrings stripped is
identical for all seven modules.

Refs #1708
@JarryShaw JarryShaw added the docs Pull requests that change documentation only (docs: subject prefix) label Oct 14, 2026
@JarryShaw JarryShaw moved this to In review in PyPCAPKit Oct 14, 2026
@JarryShaw

Copy link
Copy Markdown
Owner Author

Verdict: GOOD TO GO at c69265ad3. A Sonnet cross-review checked it (author: Opus).

@JarryShaw JarryShaw added the review: good-to-go Cross-review at the current head says ready; CI state is separate label Oct 14, 2026
@JarryShaw
JarryShaw merged commit 87d9645 into main Oct 14, 2026
52 checks passed
@github-project-automation github-project-automation Bot moved this from In review to Done in PyPCAPKit Oct 14, 2026
@JarryShaw
JarryShaw deleted the docs/1708-agreement-docstrings branch October 14, 2026 19:20
@JarryShaw JarryShaw removed the review: good-to-go Cross-review at the current head says ready; CI state is separate label Oct 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Pull requests that change documentation only (docs: subject prefix)

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

1 participant