Base Engine

pcapkit.foundation.engines.engine defines the abstract base class of every extraction engine.

class pcapkit.foundation.engines.engine.Engine[_T](extractor)

Bases: EngineBase[_T], Generic[_T]

Base class for engine support.

Example

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

class MyEngine(Engine, engine='my_engine'):
    ...

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(Engine):  # not registered
    ...

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

Extractor.register_engine('my_mixin', MyMixin)

Parameters:

extractor (Extractor) – Extractor instance.

Changed in version 1.3.0: name and module are properties, read from __engine_name__ and __engine_module__ or else from the class, where they were abstract class methods each engine implemented. A subclass registers itself with Extractor at class definition.

Changed in version 1.5.0: Registration is opt-in, under the engine class keyword, which replaces 1.4.x’s name with no alias; 1.4.x registered every subclass, under its name (its __engine_name__, else its class name) when name was omitted (#514).

See also

For customisation and extension, see Customisation & Extensions.

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

Initialise subclass.

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

Parameters:

• engine (str | None) – Engine 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 engine is given. This is what lets a subclass decline registration rather than having to inherit EngineBase to avoid it, and it matches EnumSchema.__init_subclass__, which guards on its own code keyword the same way.

Note

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

Note

The keyword is engine rather than name because, below Python 3.11, abc.ABCMeta.__new__ takes mcls, name, bases and namespace as positional-or-keyword parameters, so a class keyword by any of those names makes the class statement raise TypeError before this method is reached. metaclass is unusable on every version, since the class statement consumes it.

See also

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

class pcapkit.foundation.engines.engine.EngineBase[_T](extractor)

Bases: Generic[_T]

Base class for engine support.

Parameters:

extractor (Extractor) – Extractor instance.

Note

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

property name: str

Engine name.

Note

Also a class variable, set by __engine_name__.

property module: str

Engine module name.

Note

Also a class variable, set by __engine_module__.

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

Mapping of engine names to engine classes.

Note

A class variable only, defined on EngineMeta. It is not per-class: it reads __engine__, the one table every engine registration lands in.

property extractor: Extractor

Extractor instance.

_extractor

Extractor instance this engine reads for.

classmethod unsupported_reason()

Why this engine cannot run in this environment, if it cannot.

Engines are normally gated by whether their third-party module imports, which pcapkit.foundation.extraction.Extractor.import_test() decides. This hook is for the cases that question cannot answer – most often a dependency that installs cleanly and only fails when it is used, so the import test passes and the error escapes from the engine’s constructor as a hard failure instead of degrading to the default engine.

The default is None, i.e. always available; override it only where there is a real limitation, and return a short phrase naming the cause rather than merely refusing, since the string is shown to the user.

Return type:

str | None

Returns:

A phrase describing the limitation, or None when the engine is usable here.

See also

pcapkit.foundation.engines.pypcapfile.PyPCAPFile overrides this, because pypcapfile installs on Python 3.12 and newer and then raises ModuleNotFoundError on first use.

abstractmethod run()

Start extraction.

This method is the entry point for file extraction. It is to be used for preparing the extraction process, such as parsing the file header and setting up the extraction engines.

abstractmethod read_frame()

Read frame.

This method is to be used for reading a frame from the file. It is to read a frame from the file using the prepared engine instance and return the parsed frame.

Return type:

_T

close()

Close engine.

This method is to be used for closing the engine instance. It is to close the engine instance after the extraction process is finished.

__call__()

Start extraction.

This method will directly call run() to start the extraction process.

__engine_name__: str

Engine name.

__engine_module__: str

Engine module name.

Internal Definitions

class pcapkit.foundation.engines.engine.EngineMeta[_T](name, bases, namespace, /, **kwargs)

Bases: ABCMeta, Generic[_T]

Meta class to add dynamic support to EngineBase.

It provides EngineBase.name, EngineBase.module and EngineBase.registry as class properties, the first two read from __engine_name__ and __engine_module__ where a subclass sets them.

Type Variables

pcapkit.foundation.engines.engine._T: Any

Frame type the engine reads.