Skip to content

docs(protocols): Protocol docstring claims it is the base of all protocol families - #1106

Merged
JarryShaw merged 1 commit into
mainfrom
docs/1101-protocol-docstring
Oct 6, 2026
Merged

JarryShaw merged 1 commit into
mainfrom
docs/1101-protocol-docstring

Conversation

@JarryShaw

@JarryShaw JarryShaw commented Oct 6, 2026 •

Copy link
Copy Markdown
Owner
  • Searched for similar pull requests
  • Followed the coding style (make pylint, make mypy, make isort) — not run; docstrings only
  • make test passes, and a test case covers the change — ran tests/test_docstring_contract.py and tests/project only; no new test, a docstring change has no failing-without-fix test
  • Added a changelog entry under docs/source/changelog/ and regenerated CHANGELOG.md, if the change is user-visible — N/A, added centrally after the wave

What is the purpose of your pull request?

  • 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 #1101.

Before: Protocol said "Abstract base class for all protocol family", but Protocol.__subclasses__() is []; ProtocolMeta said it supports Protocol and generates attributes for it, but its body is empty and it is ProtocolBase's metaclass.
After: Protocol is the user-facing base for third-party protocols and new protocol stacks; ProtocolBase names the families that derive from it directly (Link, Internet, Transport, Application, pcapkit.protocols.misc) and its metaclass; ProtocolMeta says it adds nothing over abc.ABCMeta. Wording follows docs/source/ext.rst and docs/source/pcapkit/protocols/protocol.rst.

Evidence

  • AST guard (bare-string Expr stripped, ast.dump(include_attributes=False)) vs origin/main b10e7951b: identical.
  • tests/test_docstring_contract.py: 7 passed, 12 subtests passed
  • tests/project: 379 passed, 1 skipped, 1285 subtests passed

…ocol families

- Protocol: describe it as the user-facing base for third-party protocols
  and new protocol stacks; built-in families derive from ProtocolBase.
- ProtocolBase: name the families that derive from it and its metaclass.
- ProtocolMeta: it is ProtocolBase's metaclass and adds nothing over
  abc.ABCMeta; drop the claim that it generates attributes for Protocol.

Docstrings only; AST identical to origin/main once bare-string Exprs
are stripped.

Closes #1101
@JarryShaw JarryShaw added docs Pull requests that change documentation only (docs: subject prefix) review: running A cross-review is in flight against the current head - no verdict yet labels Oct 6, 2026
@JarryShaw JarryShaw moved this to In review in PyPCAPKit Oct 6, 2026
@JarryShaw

Copy link
Copy Markdown
Owner Author

Cross-review verdict on 8c278abf8: GOOD TO GO (ran on Sonnet; author Opus)

  • AST guard: protocol.py is identical to main once docstrings are stripped.
  • Probed:
    • Protocol.__subclasses__() is [].
    • ProtocolBase's direct subclasses are Protocol, the four layer classes, and the five misc classes (Frame, Header, PCAPNG, NoPayload, Raw).
    • ProtocolMeta adds nothing over ABCMeta and is type(ProtocolBase).
  • Guidance: what the docstrings say about which class to subclass matches ext.rst and protocol.rst.
  • Tests: test_docstring_contract (7) and tests/project (379) pass.

UNVERIFIED: no Sphinx build was run, so the :class: references to abc.ABCMeta were not checked.

@JarryShaw JarryShaw added review: good-to-go Cross-review at the current head says ready; CI state is separate and removed review: running A cross-review is in flight against the current head - no verdict yet labels Oct 6, 2026
@github-actions

github-actions Bot commented Oct 6, 2026

Copy link
Copy Markdown
Contributor

Coverage: 88.74% (unit tier, Python 3.14, 8c278abf8, Unit Tests run success)

Package Statements Missed Branches Partial Cover
pcapkit (top level) 104 4 20 4 93.55%
pcapkit/const 18757 1035 2342 846 90.23%
pcapkit/corekit 1874 91 578 22 94.33%
pcapkit/dumpkit 136 0 40 0 100.00%
pcapkit/foundation 2422 143 842 34 92.62%
pcapkit/interface 112 7 40 5 92.11%
pcapkit/protocols 15653 187 3942 162 98.19%
pcapkit/toolkit 487 71 144 3 84.15%
pcapkit/utilities 429 4 122 4 98.55%
pcapkit/vendor 4409 2359 1006 158 42.84%

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

@JarryShaw
JarryShaw merged commit 94f5049 into main Oct 6, 2026
41 checks passed
@JarryShaw JarryShaw removed the review: good-to-go Cross-review at the current head says ready; CI state is separate label Oct 6, 2026
@JarryShaw
JarryShaw deleted the docs/1101-protocol-docstring branch October 6, 2026 20:10
JarryShaw added a commit that referenced this pull request Oct 6, 2026
- 22 new 1.5.0 entries for the 30 PRs merged since b10e795
  (#1106-#1158), with related fixes grouped per the #918 ruling;
  three marked breaking to match their labels (#1116, #1138, #1145)
- regenerate CHANGELOG.md with util/changelog_md.py
- process.rst: entry-count pin re-measured, 167 -> 189
- pep.rst: note the plist round-trip test skipped on the upstream
  dictdumper fractional-second <date> defect (DictDumper#122)

tests/project: conventions_doc_claims, changelog_md and
documentation_claims pass; changelog_md.py --check is in step.
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.

docs(protocols): Protocol docstring claims it is the base of all protocol families

1 participant