Repository navigation
refactor(protocols)!: replace the pcapkit.protocols.__proto__ dict with an auto-registering Registry class #2763
Description
What
Replace the module-level dict pcapkit.protocols.__proto__ with a Registry class in pcapkit.protocols.registry that distributes protocol classes, and have ProtocolBase register new protocol classes into it automatically (owner, in session, 2026-11-04). pcapkit.protocols.__proto__ shipped and was autodoc'd in 1.5.1, so this is breaking: the old name keeps no alias and gets a versionremoved note.
Proposed shape: see the decision comment below for the open details.
Registryholds a class-level map with class methods to register a protocol and to look one up by name, following the class-registry convention (feat(link): decode radiotap's optional fields (#2576) #2657).ProtocolBase.__init_subclass__registers each concrete subclass under its upper-cased class name.- The first read still imports every shipped protocol package, so the registry is complete under the lazy imports of perf(protocols): import the packages above a protocol's on first use (#2730) #2757.
pcapkit.foundation.registry.register_protocoland the existing callers (ProtocolBaselookups,corekit.fields.misc, the sentinels) go throughRegistry.- It is reachable as
pcapkit.protocols.registry.Registry, and lazily aspcapkit.protocols.Registry, not in__all__. - Class-level
__proto__dispatch maps on protocol classes are unchanged.
Activity
JarryShaw commentedon Nov 4, 2026
Decision needed: three details of the
Registrydesign. A worker starts now on the recommendations, so a ruling here only adjusts that work.Which subclasses auto-register?
Link,Internetand family bases.Recommend (a). Abstract bases are not parseable layers, and the 1.5.1 registry never held them.
An auto-registered name that clashes with an existing entry (e.g. a test or user
class IPv4(...)):register_protocoldoes today; replacing stays explicit throughRegistry.register/register_protocol.Recommend (a). Defining a subclass should never silently re-point
IPv4lookups.Lookup surface:
register,get,names, membership).Registryitself a read-onlyMapping, soRegistry['IPV4']works.Recommend (a). It is plainer, and matches the class-registry convention; (b) adds a metaclass for subscript syntax.
JarryShaw commentedon Nov 4, 2026
Take all recommendations
JarryShaw commentedon Nov 4, 2026
And for built-in protocols, we still do the opt-in method through ModuleDescriptor to hardcode directly in the registry mapping so that things are populated upfront and loaded lazily.
JarryShaw commentedon Nov 4, 2026
Reconciled. This combines your in-session revision with the two comments here. It replaces the
Registryclass proposal above.ProtocolBase.__registry__(name → protocol). Thepcapkit.protocols.registrymodule is removed, along with theRegistryclass and thepcapkit.protocols.Registryexport.__registry__asModuleDescriptorentries, the same opt-in way the class__proto__maps name their targets. The map is complete from the start, and each class loads only when its entry is resolved. That replaces my "getter imports the shipped packages first" idea.ProtocolBase.__init_subclass__(rec. 1). A clash with an existing name keeps the existing entry and logs (rec. 2). A built-in replacing its own descriptor is not a clash.registry-protocol.rst(rec. 3). There is an owningregister_protocoland a getter that resolves descriptors. Thepcapkit.foundation.registry.protocols.register_protocolwrapper stays, retagged# NOTE: __registry__.pcapkit.protocols.__proto__is removed with no alias and aversionremovednote, so this isbreaking.Nothing is left open;
needs: decisionis off. A worker starts now. The first one stopped before writing any code.JarryShaw commentedon Nov 4, 2026
Actually the auto registry goes on Protocol (the public facing base class) not ProtocolBase (the internal one), following the convention of other Base classes in the library.
JarryShaw commentedon Nov 4, 2026
Reconciled: the registry moves to
Protocol, the public-facing base class, instead ofProtocolBase, the internal one, to match the library's other Base classes.Protocol.__registry__, theregister_protocolclassmethod, the getters, and auto-registration fromProtocol.__init_subclass__.ModuleDescriptorbuilt-ins, concrete-only registration, keep-and-log on a clash, and removingpcapkit.protocols.__proto__with no alias.ProtocolBaseright now. Moving the members is a small change, so it goes in as soon as the worker reports, before the PR opens.JarryShaw commentedon Nov 4, 2026
I think the dunder registry mapping stays on ProtocolBase with its classmethod and property? Only the init_subclass hook for auto registering goes to Protocol class.
JarryShaw commentedon Nov 4, 2026
Yes, reconciled. This supersedes my previous comment.
ProtocolBase: the__registry__map, its owningregister_protocolclassmethod, and the getters.Protocol: only the auto-registration hook, inProtocol.__init_subclass__. So a class gets auto-registered only when it subclasses the public base.AnyProtocol.registrythroughProtocolMeta, say so and it goes in the same PR.ProtocolBase. The follow-up is to move only the hook intoProtocol.__init_subclass__.JarryShaw commentedon Nov 4, 2026
Yes so a property or class property returns the entire entry mapping plus a get_protocol or similar (name not settles classmethod does the lookup and returns the class.
JarryShaw commentedon Nov 4, 2026
Reconciled. The read surface becomes two accessors.
AnyProtocol.registry. It would be a property onProtocolMeta, because aclassmethodwrapping apropertywas deprecated in 3.11 and removed in 3.13, and our KTLO floor runs from 3.8 to 3.15. It returns a read-only view of__registry__. Built-ins show there as theirModuleDescriptorentries, so reading the map imports nothing.get_protocol(name, default=...). It resolves a descriptor on first use.The names aren't settled. I'll go with
registryandget_protocolunless you rule otherwise; renaming them is a one-line change before merge. Everything else stands: the map and API live onProtocolBase, and the auto-registration hook is inProtocol.__init_subclass__.refactor(protocols)!: replace the pcapkit.protocols.__proto__ dict wi…