Registry Management¶

pcapkit.foundation.registry holds the registration functions for pcapkit’s engines, dumpers, callbacks and protocols.

A code the shipped enumerations do not define can still be registered: most constant enumerations return a member-like object for an in-range unknown value rather than rejecting it (see Unrecognised Values), so a newly assigned number needs no regeneration.

Foundation Registries¶

Changed in version 1.5.0: NULL, the default of every class_ argument here, is now the pcapkit.corekit.sentinels.NULL sentinel; in 1.4.x it was the string '(null)' (#833).

Engine Registries¶

pcapkit.foundation.registry.foundation.register_extractor_engine(name, module, class_=<NULL>)[source]¶

Overloads:

name (str), module (ModuleDescriptor[Engine] | Type[Engine]) → None
name (str), module (str), class_ (str) → None

Notes

The full qualified class name of the new engine class should be as {module}.{class_}.

The function will register the given engine class to the pcapkit.foundation.extraction.Extractor.__engine__ registry.

Parameters:

name (str) – engine name
module (ModuleDescriptor[Engine] | Type[Engine] | str) – module name or module descriptor or an Engine subclass (a class deriving only from EngineBase is refused: that is the base for pcapkit’s own engines, unless it is the engine name shipped with, which restores it)
class_ (str | NullType) – class name

Changed in version 1.3.0: The engine name, which was engine, is name, with no alias.

Dumper Registries¶

pcapkit.foundation.registry.foundation.register_dumper(format, module, class_=<NULL>, *, ext)[source]¶

Overloads:

format (str), module (ModuleDescriptor[Dumper] | Type[Dumper]), ext (str) → None
format (str), module (str), class_ (str), ext (str) → None

Notes

The full qualified class name of the new dumper class should be as {module}.{class_}.

The function will register the given dumper class to the pcapkit.foundation.traceflow.traceflow.TraceFlow.__output__ and pcapkit.foundation.extraction.Extractor.__output__ registry.

Parameters:

format (str) – format name
module (ModuleDescriptor[Dumper] | Type[Dumper] | str) – module name or module descriptor or a Dumper subclass
class_ (str | NullType) – class name
ext (str) – file extension

Callback Registries¶

pcapkit.foundation.registry.foundation.register_reassembly_ipv4_callback(callback)[source]¶

The function will register the given callback function to the IPv4.__callback_fn__ registry.

Parameters:: callback (Callable[[list[TypeVar(_DT, bound= Info)]], None]) – callback function

pcapkit.foundation.registry.foundation.register_reassembly_ipv6_callback(callback)[source]¶

The function will register the given callback function to the IPv6.__callback_fn__ registry.

Parameters:: callback (Callable[[list[TypeVar(_DT, bound= Info)]], None]) – callback function

pcapkit.foundation.registry.foundation.register_reassembly_tcp_callback(callback)[source]¶

The function will register the given callback function to the TCP.__callback_fn__ registry.

Parameters:: callback (Callable[[list[TypeVar(_DT, bound= Info)]], None]) – callback function

pcapkit.foundation.registry.foundation.register_traceflow_tcp_callback(callback)[source]¶

The function will register the given callback function to the TCP.__callback_fn__ registry.

Parameters:: callback (Callable[[TypeVar(_IT, bound= Info)], None]) – callback function

Extractor Registries¶

pcapkit.foundation.registry.foundation.register_extractor_reassembly(protocol, module, class_=<NULL>)[source]¶

Overloads:

protocol (str), module (ModuleDescriptor[Reassembly] | Type[Reassembly]) → None
protocol (str), module (str), class_ (str) → None

Notes

The full qualified class name of the new reassembly class should be as {module}.{class_}.

The function will register the given reassembly class to the pcapkit.foundation.extraction.Extractor.__reassembly__ registry.

Parameters:

protocol (str) – protocol name
module (str | ModuleDescriptor[Reassembly] | Type[Reassembly]) – module name or module descriptor or a Reassembly subclass (a class deriving only from ReassemblyBase is refused: that is the base for pcapkit’s own classes, unless it is the class protocol shipped with, which restores it)
class_ (str | NullType) – class name

pcapkit.foundation.registry.foundation.register_extractor_traceflow(protocol, module, class_=<NULL>)[source]¶

Overloads:

protocol (str), module (ModuleDescriptor[TraceFlow] | Type[TraceFlow]) → None
protocol (str), module (str), class_ (str) → None

Notes

The full qualified class name of the new flow tracing class should be as {module}.{class_}.

The function will register the given flow tracing class to the pcapkit.foundation.extraction.Extractor.__traceflow__ registry.

Parameters:

protocol (str) – protocol name
module (str | ModuleDescriptor[TraceFlow] | Type[TraceFlow]) – module name or module descriptor or a TraceFlow subclass (a class deriving only from TraceFlowBase is refused: that is the base for pcapkit’s own classes, unless it is the class protocol shipped with, which restores it)
class_ (str | NullType) – class name

Protocol Registries¶

Changed in version 1.5.0: NULL, the default of every class_ argument here, is now the pcapkit.corekit.sentinels.NULL sentinel; in 1.4.x it was the string '(null)' (#833).

pcapkit.foundation.registry.protocols.register_protocol(protocol)[source]¶

The protocol class must be a subclass of ProtocolBase, and will be registered to the pcapkit.protocols.__proto__ registry.

The registry is keyed on protocol.__name__.upper(), which is not unique across this package: three dispatchable protocol classes are all named HTTP – the generic base pcapkit.protocols.application.http.HTTP and the two version implementations pcapkit.protocols.application.httpv1.HTTP and pcapkit.protocols.application.httpv2.HTTP – so all three compete for the single key 'HTTP'. Registering one of them replaces whichever was there, and the replacement is observable through every reader of the registry, e.g. ProtocolBase.expand_comp, which resolves a bare protocol name through it. Per #675 the overwrite is reported, matching ProtocolBase.register and the other overwrite-warning registries.

The guard reads “key present and incumbent is a different class” – presence alone is not enough. This registry’s key is derived from the class rather than supplied by a caller, and this function is the funnel every wrapper registrar calls – register_tcp(), register_udp(), register_apptype(), register_linktype() and the rest all end by calling it with their class, and registering their code back undoes that call’s write (#1505). So registering one class under two codes, a supported and documented thing to do, reaches this function twice with the same class and nothing at stake; a presence-only guard would warn about an overwrite that overwrote nothing. Warning on the harmless case is not free: it teaches a caller to filter RegistryWarning wholesale, and that filter would then hide the HTTP collision this warning exists to surface. The sibling register methods across the package, each keyed on a caller-supplied code, apply the same identity criterion (#718).

Making the key itself unique would resolve the collision rather than merely reporting it, but it is a registry-format change that the bare-name readers outside this module cannot absorb on their own – the registry is a documented public attribute, and its readers look a bare name up and then degrade silently on a miss rather than raising, so a re-keying would not announce itself either. ProtocolBase.expand_comp falls back to the name as a plain string, and the protocol properties on ReassemblyMeta and TraceFlowMeta fall back to Raw. The registry redesign of #514 left this key unchanged and recorded the shared namespace as a risk it did not fix, so the collision is reported here rather than resolved.

Parameters:: protocol (Type[ProtocolBase]) – Protocol class.
Raises:: pcapkit.utilities.exceptions.RegistryError – If protocol is not a ProtocolBase subclass.
Warns:: pcapkit.utilities.warnings.RegistryWarning – If the registry already holds a different class under this protocol’s name, i.e. the registration displaced another protocol class. Re-registering the same class under the same name is silent.

pcapkit.foundation.registry.protocols.register_protocol_code(protocol, code)[source]¶

This is what backs the code class keyword of ProtocolBase subclasses; it can also be called directly to register a class that declined at class-definition time.

code is normalised into a flat sequence of targets, where each item is either:

an enum member, whose type is looked up in a small table mapping enum type to the class(es) owning the matching __proto__ – EtherType to Link, TransType to Internet, PayloadProtocolIdentifier to SCTP, and LinkType to both Frame and PCAPNG; or
a dict mapping an explicit destination class to a key – the only form accepted for a bare int, since e.g. a port number does not say by itself whether it means TCP or UDP;

or an iterable of either, to register protocol into several registries from one call – e.g. a L2TP subclass reachable both by its IP protocol number and by a UDP port:

register_protocol_code(L2TPv3, [TransType.L2TP, {UDP: 1701}])

The explicit mapping form is accepted for any key, even one whose type could be inferred – being more explicit than required is never an error.

Note

That example names L2TPv3, which this package does not implement, rather than L2TPv2. It is v3 that is genuinely reachable both ways: RFC 3931 §4.1.1 puts it directly over IP on protocol 115 and §4.1.2 puts it over UDP on port 1701. L2TPv2 answers on port 1701 only, and registering it at TransType.L2TP would point the RFC 2661 parser at a v3-over-IP header – see L2TP and GitHub issue #548 for what that produced when measured.

Parameters:

protocol (Type[ProtocolBase]) – Protocol class to register.
code (Any) – Registration key(s); see above.

Raises:

RegistryError – If a bare int (or any other non-enum, non- mapping value) is given without an explicit destination, or if an enum member’s type names no known destination registry – inference refuses rather than guesses.

Top-Level Registries¶

pcapkit.foundation.registry.protocols.register_linktype(code, module, class_=<NULL>)[source]¶

Overloads:

code (LinkType), module (ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]) → None
code (LinkType), module (str), class_ (str) → None

Notes

The full qualified class name of the new protocol class should be as {module}.{class_}.

The function will register the given protocol class to the following registries:

Parameters:

code (LinkType) – protocol code as in LinkType
module (str | ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]) – module name or module descriptor or a ProtocolBase subclass
class_ (str | NullType) – class name

Link Layer Registries¶

pcapkit.foundation.registry.protocols.register_ethertype(code, module, class_=<NULL>)[source]¶

Overloads:

code (EtherType), module (ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]) → None
code (EtherType), module (str), class_ (str) → None

Notes

The full qualified class name of the new protocol class should be as {module}.{class_}.

The function will register the given protocol class to the pcapkit.protocols.link.link.Link.__proto__ registry.

Parameters:

code (EtherType) – protocol code as in EtherType
module (str | ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]) – module name or module descriptor or a ProtocolBase subclass
class_ (str | NullType) – class name

Internet Layer Registries¶

pcapkit.foundation.registry.protocols.register_transtype(code, module, class_=<NULL>)[source]¶

Overloads:

code (TransType), module (ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]) → None
code (TransType), module (str), class_ (str) → None

Notes

The full qualified class name of the new protocol class should be as {module}.{class_}.

The function will register the given protocol class to the pcapkit.protocols.internet.internet.Internet.__proto__ registry.

Parameters:

code (TransType) – protocol code as in TransType
module (str | ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]) – module name or module descriptor or a ProtocolBase subclass
class_ (str | NullType) – class name

pcapkit.foundation.registry.protocols.register_ipv4_option(code, meth, *, schema=None)[source]¶

The function will register the given option parser to the pcapkit.protocols.internet.ipv4.IPv4.__option__ registry.

Parameters:

code (OptionNumber) – IPv4 option code as in OptionNumber.
meth (str | tuple[Callable[[Option, OrderedMultiDict[OptionNumber, Option]], Option], Callable[[OptionNumber, Option | None, Any], Option]]) – Method name or callable to parse and/or construct the option.
schema (Type[Option] | None) – Schema class for the option. It should be a subclass of pcapkit.protocols.schema.internet.ipv4.Option.

pcapkit.foundation.registry.protocols.register_hip_parameter(code, meth, *, schema=None)[source]¶

The function will register the given parameter parser to the pcapkit.protocols.internet.hip.HIP.__parameter__ registry.

Parameters:

code (Parameter) – HIP parameter code as in Parameter.
meth (str | tuple[Callable[[Parameter, int, OrderedMultiDict[Parameter, Parameter]], Parameter], Callable[[Parameter, Parameter | None, int, Any], Parameter]]) – Method name or callable to parse and/or construct the parameter.
schema (Type[Parameter] | None) – Schema class for the parameter. It should be a subclass of pcapkit.protocols.schema.internet.hip.Parameter.

pcapkit.foundation.registry.protocols.register_hopopt_option(code, meth, *, schema=None)[source]¶

The function will register the given option parser to the pcapkit.protocols.internet.hopopt.HOPOPT.__option__ registry.

Parameters:

code (Option) – HOPOPT option code as in Option.
meth (str | tuple[Callable[[Option, OrderedMultiDict[Option, Option]], Option], Callable[[Option, Option | None, Any], Option]]) – Method name or callable to parse and/or construct the option.
schema (Type[Option] | None) – Schema class for the option. It should be a subclass of pcapkit.protocols.schema.internet.hopopt.Option.

pcapkit.foundation.registry.protocols.register_ipv6_opts_option(code, meth, *, schema=None)[source]¶

The function will register the given option parser to the pcapkit.protocols.internet.ipv6_opts.IPv6_Opts.__option__ registry.

Parameters:

code (Option) – IPv6-Opts option code as in Option.
meth (str | tuple[Callable[[Option, OrderedMultiDict[Option, Option]], Option], Callable[[Option, Option | None, Any], Option]]) – Method name or callable to parse and/or construct the option.
schema (Type[Option] | None) – Schema class for the option. It should be a subclass of pcapkit.protocols.schema.internet.ipv6_opts.Option.

pcapkit.foundation.registry.protocols.register_ipv6_route_routing(code, meth, *, schema=None)[source]¶

The function will register the given routing data parser to the pcapkit.protocols.internet.ipv6_route.IPv6_Route.__routing__ registry.

Parameters:

code (Routing) – IPv6-Route data type code as in Routing.
meth (str | tuple[Callable[[RoutingType, IPv6_Route], IPv6_Route], Callable[[Routing, IPv6_Route | None, IPv6Address | None, Any], RoutingType]]) – Method name or callable to parse and/or construct the data.
schema (Type[RoutingType] | None) – Schema class for the routing data. It should be a subclass of pcapkit.protocols.schema.internet.ipv6_route.RoutingType.

pcapkit.foundation.registry.protocols.register_mh_message(code, meth, *, schema=None)[source]¶

The function will register the given message type parser to the pcapkit.protocols.internet.mh.MH.__message__ registry.

Parameters:

code (Packet) – MH data type code as in Packet.
meth (str | tuple[Callable[[Packet, MH], MH], Callable[[MH | None, Any], Packet]]) – Method name or callable to parse and/or construct the data.
schema (Type[Packet] | None) – Schema class for the message type. It should be a subclass of pcapkit.protocols.schema.internet.mh.Packet.

pcapkit.foundation.registry.protocols.register_mh_option(code, meth, *, schema=None)[source]¶

The function will register the given option parser to the pcapkit.protocols.internet.mh.MH.__option__ registry.

Parameters:

code (Option) – MH data type code as in Option.
meth (str | tuple[Callable[[Option, OrderedMultiDict[Option, Option]], Option], Callable[[Option, Option | None, Any], Option]]) – Method name or callable to parse and/or construct the data.
schema (Type[Option] | None) – Schema class for the message type. It should be a subclass of pcapkit.protocols.schema.internet.mh.Option.

pcapkit.foundation.registry.protocols.register_mh_extension(code, meth, *, schema=None)[source]¶

The function will register the given CGA extension to the pcapkit.protocols.internet.mh.MH.__extension__ registry.

Parameters:

code (CGAExtension) – MH data type code as in CGAExtension.
meth (str | tuple[Callable[[CGAExtension, OrderedMultiDict[CGAExtension, CGAExtension]], CGAExtension], Callable[[CGAExtension, CGAExtension | None, Any], CGAExtension]]) – Method name or callable to parse and/or construct the data.
schema (Type[CGAExtension] | None) – Schema class for the message type. It should be a subclass of pcapkit.protocols.schema.internet.mh.CGAExtension.

Changed in version 1.5.0: schema is keyword-only, as in the other register_* functions that take one (#516).

Transport Layer Registries¶

pcapkit.foundation.registry.protocols.register_apptype(code, module, class_=<NULL>, *transport)[source]¶

Overloads:

code (int), module (ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]), transport (TransportProtocol | str) → None
code (Enum_AppType), module (ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]), transport (TransportProtocol | str) → None
code (int), module (str), class_ (str), transport (TransportProtocol | str) → None
code (Enum_AppType), module (str), class_ (str), transport (TransportProtocol | str) → None

Notes

The full qualified class name of the new protocol class should be as {module}.{class_}.

The function will register the given protocol class to the pcapkit.protocols.transport.tcp.TCP.__proto__ and/or pcapkit.protocols.transport.udp.UDP.__proto__ registry.

Parameters:

code (int | AppType) – port number
module (str | ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]) – module name or module descriptor or a ProtocolBase subclass
class_ (str | TransportProtocol | NullType) – class name, meaningful only when module is a str. Positional, at the same position as the sibling register_* functions – but unlike them, a third positional argument here is not always class_: which parameter it binds to is decided by type(module) alone, never by what the value looks like. When module is not a str, whatever is given here is treated as the first *transport element instead – prepended, so argument order is preserved – and class_ itself stays unset; register_apptype(80, Unit, TransportProtocol.udp) therefore reaches transport rather than being silently swallowed. This is not a heuristic on the value: with a str module, a str third argument is always a class name – register_apptype(80, 'a.b', 'tcp') registers a class literally named 'tcp' – and naming a transport alongside a str module takes the fourth position onward instead.
*transport (TransportProtocol | str) – transport protocols to register code under, named one at a time, each as a TransportProtocol member or as that member’s name (case-insensitively, e.g. 'tcp', 'TCP' or 'Tcp' alike); the two forms are coerced to the same member and behave identically, including which error they raise. Where none is given and code is an AppType member, the member’s own proto is used, which names exactly the registry the member lives in. A bare int carries no such default and so requires at least one.

Raises:

pcapkit.utilities.exceptions.RegistryError – If no transport protocol is given for a bare int; if one of those given (member or name) names no port-keyed registry; or if a str matches no TransportProtocol member’s name. A composite such as tcp | udp, or its string form 'tcp|udp', names two and is refused for the same reason: one call registers under one transport protocol.
pcapkit.utilities.exceptions.ProtocolError – Raised lazily, from ModuleDescriptor.klass, when module is a str and either class_ names no attribute of it, or class_ was never given at all – the latter distinguished from the former rather than reported as a missing attribute named '(null)'. See GitHub issues #832 and #833.

Important

SCTP is deliberately not one of the registries this writes to, so naming sctp here is an error rather than a no-op. Its __proto__ registry is keyed by the DATA chunk’s payload protocol identifier rather than by port number, so writing a port number into it would dispatch on a number from the wrong registry. Use pcapkit.foundation.registry.register_sctp() instead.

Application Layer Registries¶

pcapkit.foundation.registry.protocols.register_http_frame(code, meth, *, schema=None)[source]¶

The function will register the given frame parser to the pcapkit.protocols.application.httpv2.HTTP.__frame__ registry.

Parameters:

code (Frame) – HTTP/2 frame type code as in Frame.
meth (str | tuple[Callable[[FrameType, HTTP], HTTP], Callable[[HTTP | None, Any], Tuple[FrameType, Flags]]]) – Method name or callable to parse and/or construct the frame.
schema (Type[FrameType] | None) – Schema class for the frame. It should be a subclass of pcapkit.protocols.schema.application.httpv2.FrameType.

Miscellaneous Protocol Registries¶

pcapkit.foundation.registry.protocols.register_pcapng_block(code, meth, *, schema=None)[source]¶

The function will register the given block parser to the pcapkit.protocols.misc.pcapng.PCAPNG.__block__ registry.

Parameters:

code (BlockType) – PCAPNG block type code as in BlockType.
meth (str | tuple[Callable[[BlockType, PCAPNG], PCAPNG], Callable[[PCAPNG | None, Any], BlockType]]) – Method name or callable to parse and/or construct the block.
schema (Type[BlockType] | None) – Schema class for the block. It should be a subclass of pcapkit.protocols.schema.misc.pcapng.BlockType.

pcapkit.foundation.registry.protocols.register_pcapng_option(code, meth, *, schema=None)[source]¶

The function will register the given option parser to the pcapkit.protocols.misc.pcapng.PCAPNG.__option__ registry.

Parameters:

code (OptionType) – PCAPNG option type code as in OptionType.
meth (str | tuple[Callable[[Option, OrderedMultiDict[OptionType, Option]], Option], Callable[[OptionType, Option | None, Any], Option]]) – Method name or callable to parse and/or construct the option.
schema (Type[Option] | None) – Schema class for the option. It should be a subclass of pcapkit.protocols.schema.misc.pcapng.Option.

pcapkit.foundation.registry.protocols.register_pcapng_record(code, meth, *, schema=None)[source]¶

The function will register the given name resolution record parser to the pcapkit.protocols.misc.pcapng.PCAPNG.__record__ registry.

Parameters:

code (RecordType) – PCAPNG name resolution record type code as in RecordType.
meth (str | tuple[Callable[[NameResolutionRecord, OrderedMultiDict[RecordType, NameResolutionRecord]], NameResolutionRecord], Callable[[RecordType, NameResolutionRecord | None, Any], NameResolutionRecord]]) – Method name or callable to parse and/or construct the name resolution record.
schema (Type[NameResolutionRecord] | None) – Schema class for the name resolution record. It should be a subclass of pcapkit.protocols.schema.misc.pcapng.NameResolutionRecord.

pcapkit.foundation.registry.protocols.register_pcapng_secrets(code, meth, *, schema=None)[source]¶

The function will register the given decryption secrets parser to the pcapkit.protocols.misc.pcapng.PCAPNG.__secrets__ registry.

Parameters:

code (SecretsType) – PCAPNG decryption secrets type code as in SecretsType.
meth (str | tuple[Callable[[DSBSecrets, DecryptionSecretsBlock], DSBSecrets], Callable[[SecretsType, DSBSecrets | None, Any], DSBSecrets]]) – Method name or callable to parse and/or construct the decryption secrets.
schema (Type[DSBSecrets] | None) – Schema class for the decryption secrets. It should be a subclass of pcapkit.protocols.schema.misc.pcapng.DSBSecrets.