Container Fields¶

Generic List Fields¶

class pcapkit.corekit.fields.collections.ListField(length=<function ListField.<lambda>>, item_type=None, callback=<function ListField.<lambda>>)[source]¶

Bases: FieldBase[list[_TL]], Generic[_TL]

Field list for protocol fields.

Parameters:

length (int | Callable[[dict[str, Any]], int]) – Field size (in bytes); if a callable is given, it should return an integer value and accept the current packet as its only argument.
item_type (FieldBase | None) – Field type of the contained items.
callback (Callable[[Self, dict[str, Any]], None]) – Callback function to be called upon self.__call__.

This field is used to represent a list of fields, as in the case of lists of constrant-length-field items in a protocol.

property length: int¶: Field size.

property optional: bool¶: Field is optional.

__call__(packet)[source]¶

Update field attributes.

Parameters:: packet (dict[str, Any]) – Packet data.
Return type:: Self
Returns:: Updated field instance.

This method will return a new instance of ListField instead of updating the current instance.

pack(value, packet)[source]¶

Pack field value into bytes.

Parameters:

value (list[TypeVar(_TL, Schema, FieldBase, bytes)] | None) – Field value.
packet (dict[str, Any]) – Packet data.

Return type:

bytes

Returns:

Packed field value.

unpack(buffer, packet)[source]¶

Unpack field value from bytes.

Parameters:

buffer (bytes | IO[bytes]) – Field buffer.
packet (dict[str, Any]) – Packet data.

Return type:

bytes | list[TypeVar(_TL, Schema, FieldBase, bytes)]

Returns:

Unpacked field value.

Raises:

FieldValueError – If the items overrun the field, or if a schema item consumes nothing from buffer – see the note below.

Option List Fields¶

class pcapkit.corekit.fields.collections.OptionField(length=<function OptionField.<lambda>>, base_schema=None, type_name='type', registry=None, eool=None, callback=<function OptionField.<lambda>>)[source]¶

Bases: ListField, Generic[_TS]

Field list for protocol options.

Parameters:

length (int | Callable[[dict[str, Any]], int]) – Field size (in bytes); if a callable is given, it should return an integer value and accept the current packet as its only argument.
base_schema (Type[TypeVar(_TS, bound= Schema)] | None) – Base schema for option fields.
type_name (str) – Name of the option type field.
registry (defaultdict[int | IntEnum | IntEnum, Type[TypeVar(_TS, bound= Schema)]] | None) – Option registry, as in a mapping from option types (enumeration values) to option schemas, with the default value being the unknown option schema.
eool (int | IntEnum | IntEnum | None) – Enumeration of the EOOL (end-of-option-list, or equivalent) option
callback (Callable[[Self, dict[str, Any]], None]) – Callback function to be called upon self.__call__.

This field is used to represent a list of fields, as in the case of lists of options and/or parameters in a protocol.

Note

self.unpack selects an option’s schema by reading the type_name field of base_schema alone off the front of the option, instead of unpacking the whole base schema and keeping only that one value. That is only the same read when three things hold of the type field:

it is the base schema’s first field, so that it is what sits at the front of the option;
it is a NumberField, so that Schema.unpack reads it through its ordinary per-field branch;
its length is a fixed integer rather than a callable, so that its width does not depend on packet data the shortcut has not read.

All of that is true of every OptionField declared in this package. A base schema registered from outside it – c.f. pcapkit.foundation.registry – need not satisfy it, and is not rejected: such a base schema is unpacked in full, exactly as it was before the shortcut existed. It parses correctly and pays the cost of the second parse. Only the shortcut is withheld, so a base schema whose type field comes second cannot be silently misread.

property base_schema: Type[_TS]¶: Base schema.

property type_name: str¶: Type name.

property registry: defaultdict[int | IntEnum | IntEnum, Type[_TS]]¶: Option registry.

property eool: int | IntEnum | IntEnum¶: EOOL option.

property option_padding: int¶: Length option padding data.

unpack(buffer, packet)[source]¶

Unpack field value from bytes.

Parameters:

buffer (bytes | IO[bytes]) – Field buffer.
packet (dict[str, Any]) – Packet data.

Return type:

list[TypeVar(_TS, bound= Schema)]

Returns:

Unpacked field value.

Important

If the option list ended before the specified size limit, set self.option_padding as the remaining length to the packet argument such that the next fields can be aware of such informations.

Raises:: FieldValueError – If an option consumes nothing from buffer, since the loop below has then no way to get past it.

Type Variables¶

pcapkit.corekit.fields.collections._TL: pcapkit.protocols.schema.schema.Schema | pcapkit.corekit.fields.field.FieldBase | bytes¶

pcapkit.corekit.fields.collections._TS: pcapkit.protocols.schema.schema.Schema¶