refactor(protocols)!: group each protocol's protocol, schema and data into one package #2534

Activity

1. JarryShaw

   added

   breakingBreaks public-facing behaviour or API (apply alongside the type label)Breaks public-facing behaviour or API (apply alongside the type label)

   refactorRestructuring for its own sake — neither a fix nor a new capability (refactor: prefix)Restructuring for its own sake — neither a fix nor a new capability (refactor: prefix)

   blockedDeferred pending another issue or decision; see the last comment for what unblocks itDeferred pending another issue or decision; see the last comment for what unblocks it

   on Nov 1, 2026
2. JarryShaw commented on Nov 1, 2026

   

   JarryShaw

   on Nov 1, 2026

   OwnerAuthor

   More actions

   Pilot done on the VLAN family (local f52b9808d, not for push). After the codemod and four kinds of hand edit, all 588 modules import cleanly, 36 test modules pass, and a nitpicky docs build adds no warnings. A dry run over the whole tree touches 56 packages, makes 142 file moves, rewrites 699 files and about 10k dotted references. The codemod is kept, ready for the real run. Decisions needed first:

   1. Framework import cycle: protocol.py imports Raw's and NoPayload's schema/data at the top, and in the new layout those cycle back through misc into protocol.py. Options: (a) defer those imports; (b) keep Raw/NoPayload at the top level as framework; (c) make the layer __init__ files lazy. Recommendation: (a), measured in the full run.
   2. The schema=/data= fallback in __init_subclass__ reads the aggregators that are going away. Only L2TP relies on it. Options: look in the class's own package for sibling schema/data modules, or make the keywords mandatory. Recommendation: sibling lookup.
   3. Does a package __init__ export its class, so that protocols.link.vlan.VLAN still resolves? refactor!: remove every surviving re-export of a moved name or module #1744's D3 allows a package __init__ to aggregate its own submodules. Recommendation: yes, which also makes most imports non-breaking.
   4. The shared ipv6_option schema/data, used by HOPOPT and IPv6_Opts, goes into the family base's package: ipv6_ext's schema/data, per your ruling 1. Recommendation: that.
   5. Framework paths: schema/schema.py → protocols/schema.py, data/data.py and data/protocol.py → protocols/data.py, and the layer bases stay at <layer>/<layer>.py. Recommendation: as listed.
   6. Released changelogs: rewrite only ~ cross-reference targets, which leaves the rendered text unchanged and keeps the links resolving. Recommendation: yes.
   7. Docs: keep one page per protocol at its current URL and add the package's .. module::, rather than a directory per package. Recommendation: keep the URLs.
3. JarryShaw

   added

   needs: decisionWaiting on the maintainer to decide — not blocked by other workWaiting on the maintainer to decide — not blocked by other work

   on Nov 1, 2026
4. JarryShaw

   added this to PyPCAPKiton Nov 1, 2026
5. JarryShaw

   moved this to Needs decision in PyPCAPKiton Nov 1, 2026
6. JarryShaw commented on Nov 1, 2026

   

   JarryShaw

   on Nov 1, 2026

   OwnerAuthor

   More actions

   1. A
   2. Sibling lookup but still takes the class constructor arguments
   3. Yes
   4. Yes, that
   5. As listed
   6. Yes
   7. Keep the URLs/docs layout, each protocol page contains first the protocol class then schema and data.
7. JarryShaw commented on Nov 1, 2026

   

   JarryShaw

   on Nov 1, 2026

   OwnerAuthor

   More actions

   Owner rulings on the pilot, paraphrased:

   1. (a): protocol.py defers its Raw/NoPayload schema and data imports.
   2. Sibling lookup: __init_subclass__ finds schema/data in the class's own package, and an explicit schema=/data= class keyword still overrides it.
   3. Yes: a package __init__ exports its class, so protocols.link.vlan.VLAN still resolves.
   4. Yes: the shared ipv6_option schema and data go into ipv6_ext's package.
   5. As listed: protocols/schema.py and protocols/data.py; layer bases stay at <layer>/<layer>.py.
   6. Yes: released changelogs get only their ~ targets rewritten.
   7. Keep the URLs: one page per protocol, with the protocol class first, then its schema, then its data.
      Back to blocked: the codemod runs once no open PR or in-flight stream touches pcapkit/protocols.
8. JarryShaw

   removed

   needs: decisionWaiting on the maintainer to decide — not blocked by other workWaiting on the maintainer to decide — not blocked by other work

   on Nov 1, 2026
9. JarryShaw

   moved this from Needs decision to Blocked in PyPCAPKiton Nov 1, 2026