Common Utilities

pcapkit.dumpkit.common holds the utilities shared by pcapkit.dumpkit, chiefly customised hooks for dictdumper.dumper.Dumper classes.

pcapkit.dumpkit.common.make_dumper(output)

Create a customised Dumper class.

Parameters:

output (Type[dictdumper.dumper.Dumper]) – Output class to customise.

Return type:

Type[dictdumper.dumper.Dumper]

Returns:

Customised Dumper subclass of output.

Changed in version 1.5.0: Several dumped shapes change. A nameless flag value renders its value as the name, Flags::0 [0] rather than Flags::None [0] (#648). An OrderedMultiDict dumps as a list of one-key mappings in wire order, not grouped by key (#1263). An IPv4Network or IPv6Network dumps as its string, a timezone as its offset in seconds, and NULL and NO_VALUE as '<NULL>' and '<NO_VALUE>' (#1258). In plist output, None is kept (#1257), and a string carrying a character XML forbids is written as <data> (#1262).

Changed in version 1.6.0: A field an Info renamed for clashing with a builtin name, such as a reassembled datagram’s packet, is written under its own name rather than left out, and reading it resolves a deferred packet as indexing does. A protocol object, such as that packet, is written as its info, as a frame is, rather than by its attributes (#2733).

class pcapkit.dumpkit.common.Dumper(fname, **kwargs)

Bases: DumperBase

Base Dumper object.

A Dumper that registers itself, on request, in the Extractor and TraceFlow output dumper registries.

Example

Registration is opt-in. Pass keyword argument fmt at class definition to register the dumper under that output format:

class MyDumper(Dumper, fmt='my_format', ext='.mine'):
    ...

Omit it and the subclass is not registered:

class MyMixin(Dumper):  # not registered
    ...

Such a class can be registered later. The hook writes every output registry, so the manual equivalent is the module-level registrar, not one class’ own method:

from pcapkit.foundation.registry.foundation import register_dumper

register_dumper('my_mixin', MyMixin, ext='.mine')

Changed in version 1.5.0: Registration is opt-in, under the fmt class keyword; 1.4.x registered every subclass, under its kind when the keyword was omitted (#514).

classmethod __init_subclass__(fmt=None, ext=None, *args, **kwargs)

Initialise subclass.

Registers the subclass in the Extractor and TraceFlow output dumper registries.

Parameters:

• fmt (str | None) – Output format to register the subclass under, lowercased. None (the default) skips registration entirely.

• ext (str | None) – Output file extension; None infers it from fmt. Only meaningful alongside fmt.

• *args (Any) – Arbitrary positional arguments.

• **kwargs (Any) – Arbitrary keyword arguments.

Raises:

UnsupportedCall – If ext is given without fmt, or if any unrecognised class keyword is given.

Return type:

None

Registration is opt-in: the subclass is registered if and only if fmt is given, so a subclass can decline it without inheriting DumperBase, as EnumSchema.__init_subclass__ guards on its code keyword.

Note

fmt is not inferred from kind, which needs an instance, hence a file created while the class statement runs.

See also

• pcapkit.foundation.registry.foundation.register_dumper()

• pcapkit.foundation.registry.foundation.register_extractor_dumper()

• pcapkit.foundation.registry.foundation.register_traceflow_dumper()

• pcapkit.foundation.extraction.Extractor.register_dumper()

• pcapkit.foundation.traceflow.traceflow.TraceFlow.register_dumper()

Internal Definitions

pcapkit.dumpkit.common.render_enum(o)

Render an enumeration member as Type::name [value].

This is the spelling of every dumped enumeration in the json, tree, text, txt, plist and xml output of both Extractor and TraceFlow.

Parameters:

o (Enum | aenum.Enum) – Enumeration member to render.

Return type:

str

Returns:

The member’s Type::name [value] rendering.

Note

A Flag value made entirely of undeclared bits, at zero or not, has name None, which would render Flags (0) as 'Flags::None [0]', indistinguishable from a member named None (#648). Its decimal value is used instead, as the enumeration libraries spell an undeclared residue (BindingUpdateFlag (32777).name is 'A|9'), and no identifier begins with a digit: BindingUpdateFlag(9) renders as 'BindingUpdateFlag::9 [9]' and Flags(0) as 'Flags::0 [0]'. A stdlib enum.IntFlag answers name is None identically on CPython 3.14.7, so this is not an aenum quirk.

class pcapkit.dumpkit.common.DumperBase(fname, **kwargs)

Bases: dictdumper.dumper.Dumper

Base Dumper object.

Note

This class is for internal use only. For customisation, please use Dumper instead.