Base Engine

This is the abstract base class implementation for all engine support functionality.

class pcapkit.foundation.engines.engine.Engine(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.

See also

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

property name: str

Engine name.

Note

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

property module: str

Engine module name.

Note

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

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

Mapping of engine names to engine classes.

Note

This property is only available as a class variable, since it is defined on EngineMeta. It reads __engine__, the single table every engine registration lands in, so it is not a per-class mapping.

property extractor: Extractor

Extractor instance.

_extractor

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:

TypeVar(_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.

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.

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 has guarded on its own code keyword all along.

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

This keyword was name when opt-in registration landed, and was renamed because name cannot be passed as a class keyword at all on Python 3.10: abc.ABCMeta.__new__() takes mcls, name, bases and namespace as positional-or-keyword parameters before 3.11, so a class keyword by any of those four names collides with one of them and the class statement raises TypeError from the metaclass before this method is reached. engine is outside that set, so the documented registration path now works on every supported version. Measured on 3.10.21, 3.11.15 and 3.14.7; those four are the whole of the abc.ABCMeta.__new__() collision surface. Separately, and for an unrelated reason that holds on every version, metaclass is not usable as a class keyword either: a class statement consumes it to choose the metaclass, so it never reaches this method at all.

See also

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

__engine_name__: str

Engine name.

__engine_module__: str

Engine module name.

Internal Definitions

class pcapkit.foundation.engines.engine.EngineBase(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.

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

Bases: ABCMeta, Generic[_T]

Meta class to add dynamic support to EngineBase.

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

Type Variables

pcapkit.foundation.engines.engine._T: Any