Auxiliary Functions#

Decorators#

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

@pcapkit.utilities.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.utilities.decorators.beholder(func)[source]#

Behold extraction procedure.

Important

This decorator function is designed for decorating class methods.

This decorator first keep the current offset of self._file, then try to call the decorated function. Should any exception raised, it will re-parse the self._file as Raw protocol.

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()

Parameters:

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

Return type:

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

@pcapkit.utilities.decorators.prepare(func)[source]#

Prepare schema packet data before unpacking.

Important

This decorate 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]',
     *args: 'typing.Any', **kwargs: 'Any') -> 'pcapkit.protocols.schema.schema.Schema'

See also

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

Parameters:

func (Callable[[Concatenate[Type[TypeVar(R_prepare, bound= Schema)], Union[bytes, IO[bytes]], Optional[int], Optional[dict[str, Any]], 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.utilities.decorators.R_seekset: Any#
pcapkit.utilities.decorators.R_beholder: pcapkit.protocols.protocol.ProtocolBase#
pcapkit.utilities.decorators.R_prepare: pcapkit.protocols.schema.schmea.Schema#

Error Handling Utilities#

pcapkit.utilities.exceptions.stacklevel()[source]#

Fetch current stack level.

The function will walk through the straceback stack (traceback.extract_stack()), and fetch the stack level where the path contains /pcapkit/. So that it won’t display any disturbing internal traceback information when raising errors.

Return type:

int

Returns:

Stack level until internal stacks, i.e. contains /pcapkit/.

pcapkit.utilities.warnings.warn(message, category, stacklevel=None)[source]#

Wrapper function of warnings.warn().

Parameters:
Return type:

None