Base Fields

Removed in version 1.3.0: pcapkit.corekit.fields.field._Field, renamed FieldBase with no alias left behind.

Removed in version 1.5.0: pcapkit.corekit.fields.field.NoValueType, now pcapkit.corekit.sentinels.NoValueType (#911, #1744), and pcapkit.corekit.fields.field.NoValue, now pcapkit.corekit.sentinels.NO_VALUE (#937).

class pcapkit.corekit.fields.field.Field[_T](length, default=NO_VALUE, callback=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 (_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[_T](*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 = NO_VALUE

_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.

Changed in version 1.5.0: Raises ProtocolError where struct.calcsize() raised a bare struct.error (#805, #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 makes the generic copy.copy() path – via object.__reduce_ex__() and copy._reconstruct() – one of the costlier things an extraction would do. This does what that path would do, and only that: a new instance of the same class, its __dict__ shallow-updated from this one.

Note

Every __call__ in pcapkit.corekit.fields copies through self.__copy__() – directly, or by way of super().__call__ – 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 a field is copied at the same points and to the same contents either way – only the redundant dispatch is skipped. 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 (_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 (_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:

_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:

_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.

Changed in version 1.5.0: A short read is zero-filled on the tail, where its missing octets are, rather than on the head (#604).

Internal Definitions

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

Bases: ABCMeta, Generic[_T]

Meta class to add dynamic support to FieldBase.

It defines nothing of its own, so a field class is built exactly as by abc.ABCMeta.

pcapkit.corekit.fields.field._RE_NEGATIVE_LENGTH_TEMPLATE

Matches a leading, optionally byte-order-prefixed negative count in a FieldBase.template, e.g. the -1 in '-1s' or in '>-1s'.

Every template this package builds from a resolved field length is f'{length}s' (see pcapkit.corekit.fields.strings, misc, collections and, before it gets byte-order-prefixed, numbers – NumberField.build_template’s else arm), so a negative resolved length always leaves that literal - immediately before the digits. What NumberField adds is a byte-order prefix – one of '@=<>!' – in front of that whole template (f'{endian}{struct_fmt}'), which is what a plain ^-\d+ misses: the prefix, not the minus sign, is what starts the string. The optional character class here accounts for exactly that one prefix position, so a negative count is recognised whether or not it was byte-order-prefixed, while still refusing anything else – a bare byte-order character with no minus sign after it ('>Xs'), or any other malformed template – which is what makes checking for it a reliable way to tell those cases apart from each other before struct.calcsize() is asked to size either one. See #825.

Type:

Pattern[str]

Type Variables

pcapkit.corekit.fields.field._T: Any