Base Fields

class pcapkit.corekit.fields.field.Field(length, default=<pcapkit.corekit.fields.field.NoValueType object>, callback=<function Field.<lambda>>)

Bases: FieldBase[_T], Generic[_T]

Base class 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.

• default (TypeVar(_T) | NoValueType) – Field default value, if any.

• callback (Callable[[Self, dict[str, Any]], None]) – Callback function to be called upon self.__call__.

_length

_length_callback

property template: str

Field template.

__call__(packet)

Update field attributes.

Parameters:

packet (dict[str, Any]) – Packet data.

Return type:

Self

Returns:

New instance of Field.

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

class pcapkit.corekit.fields.field.FieldBase(*args, **kwargs)

Bases: Generic[_T]

Internal base class for protocol fields.

Important

A negative value of length indicates that the field is variable-length (i.e., length unspecified) and thus pack() should be considerate of the template format and the actual value provided for packing.

Parameters:

• *args (Any) – Arbitrary positional arguments.

• **kwargs (Any) – Arbitrary keyword arguments.

_name: str

_template: str

_default: _T | NoValueType = <pcapkit.corekit.fields.field.NoValueType object>

_callback: Callable[[Self, dict[str, Any]], None]

property name: str

Field name.

property default: _T | NoValueType

Field default value.

property template: str

Field template.

property length: int

Field size.

Raises:

• ProtocolError – If template resolves to a negative count (e.g. '-5s', from a length callback such as lambda pkt: pkt['__length__'] resolving below zero once the buffer ran short of what the schema declared). struct.calcsize() cannot size such a template and raises a bare struct.error, uncatchable as a pcapkit-specific error; this re-raises it as the negative-length message below. See #805.

• ProtocolError – If template is otherwise malformed – anything else struct.calcsize() cannot size, such as a typo’d format character – rather than the negative-length message above, which would misreport the actual cause. struct.calcsize() raises the identical bare struct.error for both cases (measured: calcsize('-1s') and calcsize('Xs') both raise bad     char in struct format), so the two are told apart by _RE_NEGATIVE_LENGTH_TEMPLATE against template itself – which is known already, without needing anything struct.calcsize()’s own error says – rather than by the error message. See #825.

property optional: bool

Field is optional.

__call__(packet)

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 FieldBase instead of updating the current instance.

__copy__()

Return a shallow copy of the field.

Every field of every protocol is copied once per packet by __call__(), which made the generic copy.copy() path – via object.__reduce_ex__() and copy._reconstruct() – one of the costlier things an extraction did. This does what that path would have done, and only that: a new instance of the same class, its __dict__ shallow-updated from this one.

Note

Every __call__ override in this module calls self.__copy__() directly rather than copy.copy(self). copy.copy() still has to find this method before it can call it – getattr(cls, '__copy__', None) – and that lookup alone was profiled at 55,846 calls (~1.7% of an extract() run) on examples/captures/http.pcap, one per field per packet, all from this exact path. Calling __copy__ directly is exactly what copy.copy() would have done once it found it, so this changes nothing about when a field is copied or what the copy contains – only the redundant dispatch is removed. See GitHub issue #730.

Return type:

Self

Returns:

A new field instance sharing this one’s attribute values.

__set_name__(owner, name)

Set field name and update field list (if applicable).

This method is to be called by the metaclass during class creation. It is used to set the field name and update the field list, i.e., Schema.__fields__ mapping dictionary.

pre_process(value, packet)

Process field value before construction (packing).

Parameters:

• value (TypeVar(_T)) – Field value.

• packet (dict[str, Any]) – Packet data.

Return type:

Any

Returns:

Processed field value.

pack(value, packet)

Pack field value into bytes.

Parameters:

• value (TypeVar(_T) | None) – Field value.

• packet (dict[str, Any]) – Packet data.

Return type:

bytes

Returns:

Packed field value.

post_process(value, packet)

Process field value after parsing (unpacking).

Parameters:

• value (Any) – Field value.

• packet (dict[str, Any]) – Packet data.

Return type:

TypeVar(_T)

Returns:

Processed field value.

unpack(buffer, packet)

Unpack field value from bytes.

Parameters:

• buffer (bytes | IO[bytes]) – Field buffer.

• packet (dict[str, Any]) – Packet data.

Return type:

TypeVar(_T)

Returns:

Unpacked field value.

Raises:

FieldValueError – If buffer holds fewer octets than length declares, and either length is past _MAX_ZERO_PAD_LENGTH, or the shortfall is past _MAX_ZERO_PAD_SHORTFALL and takes this parse’s total of such shortfalls past what _ZERO_PAD_BUDGET_RATIO allows for the octets it has actually been given. A shortfall within _MAX_ZERO_PAD_SHORTFALL is always padded and never raises.

Auxiliaries

class pcapkit.corekit.fields.field.NoValueType

Bases: object

Default value for fields.

pcapkit.corekit.fields.field.NoValue

Default value for FieldBase.default.

Type:

NoValueType

Internal Definitions

class pcapkit.corekit.fields.field.FieldMeta(name, bases, namespace, /, **kwargs)

Bases: ABCMeta, Generic[_T]

Meta class to add dynamic support to FieldBase.

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

Type Variables

pcapkit.corekit.fields.field._T: Any