Decorator Functions

pcapkit.corekit.decorators contains several useful decorators, including seekset(), beholder() and prepare().

Added in version 1.5.0.

Removed in version 1.5.0: pcapkit.utilities.decorators, now pcapkit.corekit.decorators (#1735). pcapkit.utilities does not export the three decorators either.

@pcapkit.corekit.decorators.seekset(func)[source]

Read file from start then set back to original.

Important

This decorator function is designed for decorating class methods.

The decorator will keep the current offset of self._file, then call the decorated function. Afterwards, it will rewind the offset of self._file to the original and returns the return value from the decorated function.

Note

The decorated function should have following signature:

func(self: 'pcapkit.protocols.protocol.ProtocolBase',
     *args: 'typing.Any', **kwargs: 'typing.Any') -> 'typing.Any'

See also

pcapkit.protocols.protocol.Protocol._read_packet()

Parameters:

func (Callable[[Concatenate[ProtocolBase, ParamSpec(P)]], TypeVar(R_seekset)]) – decorated function

Return type:

Callable[[ParamSpec(P)], TypeVar(R_seekset)]

@pcapkit.corekit.decorators.beholder(func)[source]

Behold extraction procedure.

Important

This decorator function is designed for decorating class methods.

This decorator calls the decorated function. Should any exception be raised, it logs the error and re-parses the current layer’s payload as Raw – or as NoPayload, if the error is an end-of-file StructError.

Note

The decorated function should have following signature:

func(self: 'pcapkit.protocols.protocol.ProtocolBase',
     proto: 'int', length: 'typing.Optional[int]',
     *args: 'typing.Any', **kwargs: 'typing.Any') -> 'pcapkit.protocols.protocol.ProtocolBase'

See also

pcapkit.protocols.protocol.Protocol._decode_next_layer()

Changed in version 1.3.0: Logs the exception it absorbs, and prints its traceback in verbose mode.

Parameters:

func (Callable[[Concatenate[ProtocolBase, int, int | None, ParamSpec(P)]], TypeVar(R_beholder, bound= ProtocolBase)]) – decorated function

Return type:

Callable[[ParamSpec(P)], TypeVar(R_beholder, bound= ProtocolBase)]

@pcapkit.corekit.decorators.prepare(func)[source]

Prepare schema packet data before unpacking.

Important

This decorator function is designed for decorating the Schema.unpack class method.

This decorator will revise the parameter list provided to the original Schema.unpack method and extract necessary information based on the given parameters, then provide the revised version of parameter list to the original method.

Note

The decorated function should have following signature:

func(cls: 'typing.Type[pcapkit.protocols.schema.schema.Schema]',
     data: 'bytes | typing.IO[bytes]',
     length: 'Optional[int]',
     packet: 'Optional[dict[str, Any]]') -> 'pcapkit.protocols.schema.schema.Schema'

No further positional or keyword arguments are read from – or forwarded to – the decorated function. prepare() is applied to exactly one function in this tree, Schema.unpack, whose real signature has exactly these four parameters, and nothing calls it with more. Rather than discard extras silently (#454), the wrapper raises TypeError for a fifth positional argument or an unconsumed keyword, the same as an ordinary call with too many arguments would.

See also

pcapkit.protocols.schema.schema.Schema.unpack()

Parameters:

func (Callable[[Concatenate[Type[TypeVar(R_prepare, bound= Schema)], bytes | IO[bytes], int | None, dict[str, Any] | None, ParamSpec(P)]], TypeVar(R_prepare, bound= Schema)]) – decorated function

Return type:

Callable[[ParamSpec(P)], TypeVar(R_prepare, bound= Schema)]

Important

All three decorators above are designed for decorating class methods. For more information, please refer to the documentation of each decorator function.

Type Variables

pcapkit.corekit.decorators.R_seekset: Any
pcapkit.corekit.decorators.R_beholder: pcapkit.protocols.protocol.ProtocolBase
pcapkit.corekit.decorators.R_prepare: pcapkit.protocols.schema.schema.Schema