Decorator Functions¶

pcapkit.corekit.decorators contains the decorators 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 these 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 instance 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 return the return value from the decorated function.

Note

The decorated function should have the following signature:

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

Parameters:: func (Callable[Concatenate[ProtocolBase, P], R_seekset]) – decorated function
Return type:: Callable[P, R_seekset]

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

Behold extraction procedure.

Important

This decorator function is designed for decorating instance methods.

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

The decorated call runs inside a CaughtByCaller block naming ProtocolError (#2588). The block spans the whole call, so every such error built while it runs is quiet, at any depth and whether or not the code that built it catches it, unless an inner CaughtByCaller says otherwise: the next layer refusing its octets, a parser’s own trial, a registry entry whose class its module has since lost. One that reaches here is recorded on error and is not logged here either. Any other exception is logged here at logging.WARNING, and is as loud as it was constructed.

Inside a payload Protocol._make_payload rebuilds, the block names every Exception, which is what the except below catches, and nothing is logged here: the layer the payload is rebuilt for parses the same octets again, outside the rebuild, and its own beholder() reports the error there (#2711).

The recovery runs after the block has ended. Under the outermost beholder() of a parse, a ProtocolError it raises therefore reaches the caller loud; under any other, the block of the beholder() around it is still active, so that error is quiet, and becomes the enclosing replacement’s error.

When Protocol._parse_next_layer held the warnings of the layer that raised, they are dropped with it: they describe a layer the result does not have, and the replacement’s error reports the failure (#2308).

Note

The decorated function should have the following signature:

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

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

Changed in version 1.6.0: A ProtocolError the decorated function builds is quiet, and one this decorator absorbs is not logged here either (#2588). Inside a payload being rebuilt, so is every other error (#2711).

Parameters:: func (Callable[Concatenate[ProtocolBase, int, int | None, P], R_beholder]) – decorated function
Return type:: Callable[P, R_beholder]

@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 the following signature:

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

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

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¶