Registry Management¶

This module (pcapkit.foundation.registry) provides the registry management for pcapkit, as the module contains various registry points.

Every registration below takes a code that is already an enumeration member. For how a code the shipped registries do not define becomes one in the first place, see Unrecognised Values – the constant enumerations mint an in-range unknown value rather than rejecting it, which is what makes registering against a newly assigned number possible without regenerating them.

Foundation Registries¶

Engine Registries¶

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

Registered a new engine class.

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
class_ (str | NullType) – class name

Dumper Registries¶

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

Registered a new dumper class.

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]¶

Registered a new callback function.

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]¶

Registered a new callback function.

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]¶

Registered a new callback function.

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]¶

Registered a new callback function.

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]¶

Registered a new reassembly class.

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
class_ (str | NullType) – class name

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

Registered a new flow tracing class.

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
class_ (str | NullType) – class name

Protocol Registries¶

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

Registered protocol class.

The protocol class must be a subclass of Protocol, 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 now reported rather than silent, matching ProtocolBase.register and the other overwrite-warning registries.

The guard here 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 in register_protocol(module). 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 is what teaches a caller to filter RegistryWarning wholesale, and that filter is what 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 rather than a name derived from the class – apply the same identity criterion as of GitHub issue #718; before that they warned on presence alone, and none of them does now.

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. Re-keying is therefore part of the registry redesign in #514, and reporting the collision here is the step that redesign is sequenced behind.

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.

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 Protocol 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 Protocol 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 Protocol 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.

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 Protocol 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]¶

Registered a frame parser.

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]¶

Registered a block parser.

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

Parameters:

code (BlockType) – HTTP/2 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]¶

Registered a option parser.

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]¶

Registered a name resolution record parser.

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]¶

Registered a decryption secrets parser.

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.