Flow Tracing Base Class

pcapkit.foundation.traceflow.traceflow contains TraceFlow, the abstract base class of a custom flow tracing class, and TraceFlowBase, which it and the built-in TCP flow tracing class derive from.

class pcapkit.foundation.traceflow.traceflow.TraceFlow[_DT, _BT: Info, _IT: Info, _PT: Info](fout, format, byteorder=sys.byteorder, nanosecond=False, bidirectional=True, analyse=False)[source]

Bases: TraceFlowBase[_DT, _BT, _IT, _PT], Generic[_DT, _BT, _IT, _PT]

Base flow tracing class.

Example

Registration is opt-in. Pass keyword argument protocol at class definition to register the flow tracing class under that protocol name:

class MyProtocol(TraceFlow, protocol='my_protocol'):
    ...

Omit it and the subclass is not registered, which is how a class that is not meant to be selectable by name declines:

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

Such a class can still be registered later, on demand:

Extractor.register_traceflow('my_mixin', MyMixin)
Parameters:

  • fout (str | None) – output path

  • format (str | None) – output format

  • byteorder (Literal['little', 'big']) – output file byte order

  • nanosecond (bool) – output nanosecond-resolution file flag

  • bidirectional (bool) – trace both halves of a conversation as one flow

  • analyse (bool) – reassemble each flow’s application layer

Changed in version 1.3.0: name and protocol are read from __protocol_name__ and __protocol_type__, where they were abstract properties each flow tracing class implemented, and the built-in name is short: 'TCP' rather than 'Transmission Control Protocol'. A subclass registers itself with Extractor at class definition.

Changed in version 1.5.0: Registration is opt-in, under the protocol class keyword; 1.4.x registered every subclass, under its name when the keyword was omitted (#514). The bidirectional and analyse arguments are added, and a flow covers both directions of a conversation unless bidirectional=False is passed.

See also

For customisation and extension, see Customisation & Extensions.

property name: str

Protocol name of current class.

Note

Also a class variable, set by __protocol_name__.

property protocol: Type[pcapkit.protocols.protocol.ProtocolBase]

Protocol of current class.

Note

Also a class variable, set by __protocol_type__.

property registry: dict[str, ModuleDescriptor[TraceFlowBase] | Type[TraceFlowBase]]

Mapping of protocol names to flow tracing classes.

Note

A class variable only, defined on TraceFlowMeta. It is not per-class: it reads __traceflow__, the one table every flow tracing registration lands in. It is not __output__, the separate output-dumper table this class owns.

property index: tuple[_IT, ...]

Index table for traced flows.

classmethod register_dumper(format, dumper, ext)

Register a new dumper class.

Notes

The fully qualified class name of the new dumper class should be {dumper.module}.{dumper.name}.

The overwrite guard fires only when the incumbent dumper differs from the replacement, so re-registering the exact same object is a silent no-op rather than a warning about nothing displaced – the identity guard of the code-keyed registrars (#718, #739). __output__ maps each format to a (dumper, ext) pair, so the identity check compares the incumbent dumper (index 0), not the pair – a re-registration that only changes ext is still identity-equal on the dumper and stays silent, since the dumper is what “the same object” means here, not the pair as a whole. __output__ is also a collections.defaultdict, unlike the Extractor engine, reassembly and flow tracing registries; dict.get() does not invoke the default factory the way cls.__output__[format] would, so it stays non-inserting here as well.

The dumper format shipped with, as its descriptor or as the class it names, restores the shipped entry rather than storing the class, so an override can be undone and the deferred import is kept (#1363, #1364).

Parameters:
Raises:

RegistryError – If dumper is not a class, or not a dictdumper.dumper.Dumper subclass, such as Dumper.

Warns:

RegistryWarning – If a different dumper is already registered for format; it is overwritten.

Removed in version 1.1.1.post2: register, which this replaces with no alias.

Changed in version 1.3.0: dumper, a module descriptor or a class, replaces the module and class_ name pair, with no alias.

classmethod register_callback(callback, *, index=None)

Register callback function.

Parameters:

  • callback (Callable[[_IT], None]) – callback function, which will be called when a traced flow is finalised, with the flow’s index entry (trace.tcp.index) as its only argument

  • index (int | None) – index to be inserted in the callback list; by default, the callback will be appended to the end of the list

Return type:

None

classmethod make_fout(fout='./tmp', fmt='pcap')

Make root path for output.

Parameters:

  • fout (str) – root path for output

  • fmt (str) – output format

Return type:

tuple[Type[dictdumper.dumper.Dumper], str | None]

Returns:

Dumper of specified format and file extension of output file.

Warns:

  • FormatWarning – If fmt is not supported.

  • FileWarning – If fout exists but is not a directory, and fmt is not supported.

Raises:

FileExists – If fout exists but is not a directory, and fmt is supported.

abstractmethod dump(packet)

Dump frame to output files.

Parameters:

packet (_PT) – a flow packet (trace.tcp.packet)

abstractmethod trace(packet, *, output=False)

Trace packets.

Overloads:
Parameters:
Returns:

If output is True, returns the initiated Dumper object, which will dump data to the output file named after the flow label; otherwise, returns the flow label itself.

finish()

Finalise every flow still being traced.

Called by Extractor._cleanup once the capture has been read to its end, which is the point at which a flow that was never superseded can be said to be over.

The base implementation does nothing, so a tracer that has no such notion need not override it. submit() must remain able to report a flow that was never finalised, since nothing guarantees this is called: a tracer driven directly rather than through an Extractor never sees an end of capture.

Implementations must be idempotent: Extractor._cleanup can run more than once for one extraction.

abstractmethod submit()

Submit traced TCP flows.

Return type:

tuple[_IT, ...]

Returns:

Traced TCP flow (trace.tcp.index).

__output__: DefaultDict[str, tuple[ModuleDescriptor[dictdumper.dumper.Dumper] | Type[dictdumper.dumper.Dumper], str | None]]

Format dumper mapping for writing output files. Each value pairs the dumper, as a module descriptor or a dictdumper.dumper.Dumper subclass, with the file extension of its format.

__callback_fn__: list[Callable[[_IT], None]]

List of callback functions upon a finalised flow.

_buffer: dict[_DT, _BT]

Buffer field (trace.tcp.buffer).

Type:

dict[_DT, _BT]

_stream: list[_IT]

Stream index (trace.tcp.index).

Type:

list[_IT]

_bidir

Bidirectional tracing flag. If set to True, both halves of a conversation share one buffer entry, one label and one output file; otherwise each direction is a flow of its own.

Type:

bool

_fproot

Output root path.

Type:

str

_foutio

Dumper class.

Type:

Type[Dumper]

_fdpext

Output file extension.

Type:

Optional[str]

_endian

Output file byte order.

Type:

Literal[‘little’, ‘big’]

_nnsecd

Output nanosecond-resolution file flag.

Type:

bool

_analyse

Application-layer analysis flag. If set to True, each flow reassembles the payload it carries so that its packet can be read; otherwise no payload is buffered and packet is None.

Type:

bool

__call__(packet)

Dump frame to output files.

Parameters:

packet (_PT) – a flow packet (trace.tcp.packet)

classmethod __init_subclass__(protocol=None, *args, **kwargs)[source]

Initialise subclass.

This method is to be used for registering the flow tracing class to Extractor class.

Parameters:

  • protocol (str | None) – Protocol name to register the subclass under, lowercased. None (the default) skips registration entirely.

  • *args (Any) – Arbitrary positional arguments.

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

Raises:

UnsupportedCall – If any unrecognised class keyword is given.

Return type:

None

Registration is opt-in: the subclass is registered if and only if protocol is given. This is what lets a subclass decline registration rather than having to inherit TraceFlowBase to avoid it, and it matches EnumSchema.__init_subclass__, which guards on its own code keyword the same way.

Note

__protocol_name__ is not an opt-in. It supplies the name the class reports, which it does whether or not the class is registered; only the keyword decides registration.

See also

For more details, please refer to pcapkit.foundation.extraction.Extractor.register_traceflow().

__protocol_name__: str

Protocol name of current flow tracing object.

__protocol_type__: Type[ProtocolBase]

Protocol of current flow tracing object.

Internal Definitions

class pcapkit.foundation.traceflow.traceflow.TraceFlowBase[_DT, _BT: Info, _IT: Info, _PT: Info](fout, format, byteorder=sys.byteorder, nanosecond=False, bidirectional=True, analyse=False)[source]

Bases: Generic[_DT, _BT, _IT, _PT]

Base flow tracing class.

Parameters:

  • fout (str | None) – output path

  • format (str | None) – output format

  • byteorder (Literal['little', 'big']) – output file byte order

  • nanosecond (bool) – output nanosecond-resolution file flag

  • bidirectional (bool) – trace both halves of a conversation as one flow

  • analyse (bool) – reassemble each flow’s application layer

Note

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

class pcapkit.foundation.traceflow.traceflow.TraceFlowMeta(name, bases, namespace, /, **kwargs)[source]

Bases: ABCMeta

Meta class to add dynamic support to TraceFlow.

It provides TraceFlow.name, TraceFlow.protocol and TraceFlow.registry as class properties, the first two read from __protocol_name__ and __protocol_type__ where a subclass sets them.

Type Variables

pcapkit.foundation.traceflow.traceflow._DT: Any

Buffer ID data structure.

pcapkit.foundation.traceflow.traceflow._BT: pcapkit.corekit.infoclass.Info

Buffer data structure.

pcapkit.foundation.traceflow.traceflow._IT: pcapkit.corekit.infoclass.Info

Index data structure.

pcapkit.foundation.traceflow.traceflow._PT: pcapkit.corekit.infoclass.Info

Packet data structure.