Base Class

pcapkit.foundation.traceflow.traceflow contains TraceFlow only, which is an abstract base class for all flow tracing classes.

class pcapkit.foundation.traceflow.traceflow.TraceFlow(fout, format, byteorder='little', nanosecond=False)

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

Base flow tracing class.

Example

Use keyword argument protocol to specify the protocol name at class definition:

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

Parameters:

• fout (Optional[str]) – output path

• format (Optional[str]) – output format

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

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

See also

For more information on customisation and extension, please refer to Customisation & Extensions.

property name: str

Protocol name of current class.

Note

This property is also available as a class variable. Its value can be set by __protocol_name__ class attribute.

property protocol: Type[Protocol]

Protocol of current class.

Note

This property is also available as a class variable. Its value can be set by __protocol_type__ class attribute.

property index: tuple[_IT, ...]

_IT table for traced flow.

classmethod register_dumper(format, dumper, ext)

Register a new dumper class.

Notes

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

Parameters:

• format (str) – format name

• dumper (Union[ModuleDescriptor[Dumper], Type[Dumper]]) – module descriptor or a dictdumper.dumper.Dumper subclass

• ext (str) – file extension

Return type:

None

classmethod register_callback(callback, *, index=None)

Register callback function.

Parameters:

• callback (Callable[[TypeVar(_IT, bound= Info)], None]) – callback function, which will be called when reassembled datagram is obtained, with the list of reassembled datagrams as its only argument

• index (Optional[int]) – index of datagram to be called

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[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 and fmt is None.

Raises:

FileExists – If fout exists and fmt is NOT None.

abstract dump(packet)

Dump frame to output files.

Parameters:

packet (TypeVar(_PT, bound= Info)) – a flow packet (trace.tcp.packet)

Return type:

None

abstract trace(packet, *, output=False)

Trace packets.

Parameters:

• packet (TypeVar(_PT, bound= Info)) – a flow packet (trace.tcp.packet)

• output (bool) – flag if has formatted dumper

Return type:

Dumper | str

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.

abstract submit()

Submit traced TCP flows.

Return type:

tuple[TypeVar(_IT, bound= Info), ...]

Returns:

Traced TCP flow (trace.tcp.index).

__output__: DefaultDict[str, tuple[Union[ModuleDescriptor[Dumper], Type[Dumper]], str | None]]

DefaultDict[str, tuple[ModuleDescriptor[Dumper] | Type[Dumper], str | None]]: Format dumper mapping for writing output files. The values should be a tuple representing the module name and class name, or a dictdumper.dumper.Dumper subclass, and corresponding file extension.

__callback_fn__: list[Callable[[TypeVar(_IT, bound= Info)], None]]

List of callback functions upon reassembled datagram.

_buffer: dict[TypeVar(_DT), TypeVar(_BT, bound= Info)]

Buffer field (trace.tcp.buffer).

Type:

dict[_DT, _BT]

_stream: list[TypeVar(_IT, bound= Info)]

Stream index (trace.tcp.index).

Type:

list[_IT]

__call__(packet)

Dump frame to output files.

Parameters:

packet (TypeVar(_PT, bound= Info)) – a flow packet (trace.tcp.packet)

Return type:

None

classmethod __init_subclass__(protocol=None, *args, **kwargs)

Initialise subclass.

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

Parameters:

• name – Protocol name, default to class name.

• *args (Any) – Arbitrary positional arguments.

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

Return type:

None

See also

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

__protocol_name__: str

Protocol name of current reassembly object.

__protocol_type__: Type[ProtocolBase]

Protocol of current reassembly object.

Internal Definitions

class pcapkit.foundation.traceflow.traceflow.TraceFlowBase(fout, format, byteorder='little', nanosecond=False)

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

Base flow tracing class.

Parameters:

• fout (Optional[str]) – output path

• format (Optional[str]) – output format

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

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

Note

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

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

Bases: ABCMeta

Meta class to add dynamic support to TraceFlow.

This meta class is used to generate necessary attributes for the TraceFlow class. It can be useful to reduce unnecessary registry calls and simplify the customisation process.

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.