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)[source]#

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:
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:
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)[source]#

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)[source]#

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)[source]#

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.