Skip to content

docs(conventions): settle the member-order page wording and align the protocol registry with the other maps (#2772, #2773) - #2779

Merged
JarryShaw merged 2 commits into
mainfrom
docs/2772-member-order-registry
Nov 4, 2026
Merged

docs(conventions): settle the member-order page wording and align the protocol registry with the other maps (#2772, #2773)#2779
JarryShaw merged 2 commits into
mainfrom
docs/2772-member-order-registry

Conversation

@JarryShaw

@JarryShaw JarryShaw commented Nov 4, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

What is the purpose of your pull request?

  • refactor — restructures code without changing behaviour

Description of your pull request and other information

This applies the owner's rulings on #2772 and on items 2–4 of #2773. They come as one change because both edit protocol-member-order.rst and the member-order guard.

  • The page: with several registries, all readers come before all makers. PCAPNG.__option__ is ordered by namespace (in OptionType order), then by value. Int keys with no enum are ordered by key value, and string keys alphabetically. SCTP broke the readers-before-makers rule, so its members are reordered; only the order changes.
  • Option.__enum__: Option.register's clash warning now names namespaces sorted rather than in map order, and the map is alphabetical. A clash in a single namespace reads exactly as before.
  • .rst member lists: realigned to class source order on the protocol pages. A check confirmed no line was added or lost.
  • __registry__: entries are grouped under # Link Layer … # Miscellaneous, alphabetical within each group, and the page records this.
  • Name restore: _release_name now goes through register_protocol, as the code wrappers do. So a restore over a custom class now warns "overwriting", just as a code restore already does on main.
  • Guard: it gains a cross-registry check, string-key and PCAP-NG option-key ordering, and a layer rule. It fails 4 times on main and passes here. Docs build with 0 warnings.

Closes #2772
Part of #2773

@JarryShaw
docs(conventions): settle the member-order page wording and align the…
2dc03c4 
… protocol registry with the other maps (#2772, #2773)

- protocol-member-order.rst: every registry's readers precede any registry's
  makers; an int key with no enum orders by value, a str key alphabetically;
  PCAPNG.__option__ by namespace then value; __registry__ grouped by layer.
- SCTP: move the chunk, parameter and cause readers ahead of their makers.
- PCAP-NG Option.register names clashing namespaces sorted, and
  Option.__enum__ lists its namespaces alphabetically.
- ProtocolBase.__registry__: built-ins under layer comments, sorted in each.
- _release_name restores a displaced name through register_protocol.
- Protocol API pages list members in class source order.
- Member-order guard: cross-registry readers, str keys per comment group,
  PCAP-NG option keys and the __registry__ layer groups.
@JarryShaw JarryShaw added docs Pull requests that change documentation only (docs: subject prefix) refactor Restructuring for its own sake — neither a fix nor a new capability (refactor: prefix) review: running A cross-review is in flight against the current head - no verdict yet labels Nov 4, 2026
@JarryShaw

JarryShaw commented Nov 4, 2026

Copy link
Copy Markdown
Owner Author

Decision needed: four small choices this PR made on its own. Each follows my recommendation, so a ruling would only adjust the PR.

  1. Namespace order for PCAPNG.__option__ ("namespace then value"):

    • (a) OptionType's declared order. This is the map as it already is, with opt first.
    • (b) Alphabetical, matching __enum__. This moves the map and its reader and maker methods.

    Rec: (a). Nothing churns.

  2. SCTP's member move, which the readers-before-makers rule forced:

    • (a) Keep it in this PR.
    • (b) Split it into its own PR.

    Rec: (a).

  3. The Protocol docs page documents members that ProtocolBase defines, so this PR left its order alone:

    • (a) Leave it.
    • (b) Realign it to ProtocolBase's source order.

    Rec: (a).

  4. A guard for .rst member order. Nothing yet checks that the pages stay in source order:

    • (a) Add one in a follow-up.
    • (b) Leave it.

    Rec: (a).

@github-actions github-actions Bot added this to the PyPCAPKit v1.6 milestone Nov 4, 2026
@JarryShaw JarryShaw mentioned this pull request Nov 4, 2026
Closed
@JarryShaw JarryShaw moved this to In review in PyPCAPKit Nov 4, 2026
@JarryShaw JarryShaw mentioned this pull request Nov 4, 2026
Closed
@JarryShaw JarryShaw mentioned this pull request Nov 4, 2026
Merged
1 of 5 tasks
@JarryShaw

JarryShaw commented Nov 4, 2026

Copy link
Copy Markdown
Owner Author

GOOD TO GO at 7cc8cfd97 (Sonnet cross-review, my own guard run, and the nit round)

  • Purity: the SCTP reorder leaves its class-body AST and its non-blank lines unchanged. __registry__ keeps the same entries (sorted (key, module, name) hash matches main) and adds only the five layer comments. No directive was lost or added across the 46 .rst pages, and the IPv4, TCP, SCTP and PCAPNG pages now follow source order.
  • Warnings: a clash in a single namespace reads byte-identical to main. The ns='opt' fan-out now names its namespaces sorted, and a new test pins that.
  • Name restore: it now goes through register_protocol. A restore over a custom class warns "overwriting", exactly as main's __proto__ code restore already does, and a new test pins the match. The _release_name docstring is rewritten.
  • Guard: fails on main (4) and passes here. The docs build has 0 warnings. Project tests, Lint and deploy-pages pass.
  • docs(conventions): settle the member-order page wording #2765 left open #2772 rulings: all four recommendations hold, so nothing changed for them.

@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 Nov 4, 2026
@github-actions

github-actions Bot commented Nov 4, 2026

Copy link
Copy Markdown
Contributor

Coverage: 94.45% (unit tier, Python 3.15, 7cc8cfd97, Unit Tests run success)

Package Statements Missed Branches Partial Cover
pcapkit (top level) 106 4 20 2 95.24%
pcapkit/const 20918 175 2908 156 98.57%
pcapkit/corekit 2914 77 940 38 96.81%
pcapkit/dumpkit 286 3 102 3 98.45%
pcapkit/foundation 3508 27 1218 32 98.75%
pcapkit/interface 138 4 52 3 96.32%
pcapkit/protocols 22825 157 5950 127 99.00%
pcapkit/toolkit 961 26 342 8 96.62%
pcapkit/utilities 559 7 150 5 98.31%
pcapkit/vendor 5590 2286 1280 214 55.75%

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

@JarryShaw
JarryShaw merged commit c5b9c54 into main Nov 4, 2026
66 checks passed
@github-project-automation github-project-automation Bot moved this from In review to Done in PyPCAPKit Nov 4, 2026
@JarryShaw
JarryShaw deleted the docs/2772-member-order-registry branch November 4, 2026 21:15
@JarryShaw JarryShaw removed the review: good-to-go Cross-review at the current head says ready; CI state is separate label Nov 4, 2026
@JarryShaw JarryShaw mentioned this pull request Nov 4, 2026
Closed
JarryShaw added a commit that referenced this pull request Nov 4, 2026
@JarryShaw
docs(changelog): fold #2777, #2778, #2779 and #2781 (#2449)
26a0389 
- #2777: the cut-header sentence reads the length back too, the rebuild read
  at the width its parse was given (__short_width__); the ruling into the
  conventions entry.
- #2778: a PCAP-NG block with octets after opt_endofopt rebuilds an info
  holding its options and padding_opts, where 1.5.1 rebuilt none, into the
  whole-header rebuild entry; 1.5.0's frozen entry is left as written.
- #2779: SCTP's reorder, the source-ordered member lists and the sorted
  Option.register clash warning ('opt', 'if', 'epb', ... in 1.5.1), into the
  member-order entry; the layer-grouped registry and the warning name restore
  ('put back silently' in 1.5.1), into the #2770 entry; the page wording into
  the conventions entry.
- #2781: import_lock serialising first resolutions, into the lazy-import
  entry; the removed registry lock never shipped and stays unnamed.
- CHANGELOG.md regenerated; util/changelog_md.py --check passes.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

docs Pull requests that change documentation only (docs: subject prefix) refactor Restructuring for its own sake — neither a fix nor a new capability (refactor: prefix)

Projects

PyPCAPKit
Status: Done

Milestone

PyPCAPKit v1.6

Development

Successfully merging this pull request may close these issues.

docs(conventions): settle the member-order page wording #2765 left open

1 participant

@JarryShaw