Text Fields¶

Bytes-based Fields¶

class pcapkit.corekit.fields.strings.BytesField(length, default=<pcapkit.corekit.sentinels.NoValueType object>, callback=<function _TextField.<lambda>>)[source]¶

Bases: _TextField[bytes]

Bytes value 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, str, bytes, dict[str, Any]) | NoValueType) – Field default value, if any.
callback (Callable[[Self, dict[str, Any]], None]) – Callback function to be called upon self.__call__.

pre_process(value, packet)[source]¶

Process field value before construction (packing).

Parameters:

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

Return type:

bytes

Returns:

Processed field value.

class pcapkit.corekit.fields.strings.PaddingField(length, default=<pcapkit.corekit.sentinels.NoValueType object>, callback=<function _TextField.<lambda>>)[source]¶

Bases: BytesField

Bytes value 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, str, bytes, dict[str, Any]) | NoValueType) – Field default value, if any.
callback (Callable[[Self, dict[str, Any]], None]) – Callback function to be called upon self.__call__.

Padding packs back as the octets it was given, so a schema unpacked from non-zero padding rebuilds byte for byte. An absent or empty value packs as zeros – the default for a freshly built packet – and a value of another width is truncated or zero-filled to the field’s, as struct’s s format does.

pack(value, packet)[source]¶

Pack field value into bytes.

Parameters:

value (bytes | None) – Field value, i.e. the padding octets as captured.
packet (dict[str, Any]) – Packet data.

Returns:

value truncated or zero-filled to the field’s width, or that many zero octets if value is absent or empty.

Return type:

bytes

String-based Fields¶

class pcapkit.corekit.fields.strings.StringField(length, default=<pcapkit.corekit.sentinels.NoValueType object>, encoding=None, errors='strict', unquote=False, callback=<function StringField.<lambda>>)[source]¶

Bases: _TextField[str]

String value 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 (str | NoValueType) – Field default value, if any.
encoding (str | None) – The encoding with which to decode the bytes, and with which a str is encoded when packing. If not provided, pcapkit will first try detecting its encoding using chardet. The fallback encoding is UTF-8.
errors (Literal['strict', 'ignore', 'replace']) – The error handling scheme to use for the handling of decoding errors. The default is 'strict'. Should decoding fail under it, the field retries with 'replace' rather than raising, so an octet the charset cannot decode reads as U+FFFD – the octets themselves are not lost, see below. A codec that raises under 'replace' as well, such as idna, which supports 'strict' alone, decodes as UTF-8 with 'replace' instead, and its octets are not lost either. Other possible values are 'ignore' and 'replace' as well as any other name registered with codecs.register_error() that can handle UnicodeDecodeError.
unquote (bool) – Whether to unquote the decoded string as a URL. Should decoding fail, the method will try again replacing '%' with '\x' then decoding the url as 'utf-8' with 'replace' for error handling.
callback (Callable[[Self, dict[str, Any]], None]) – Callback function to be called upon self.__call__.

Unpacking is lossless. Where re-encoding the decoded str would not reproduce the octets it came from – a detected charset other than UTF-8, an octet the charset cannot decode, a lossy errors scheme, or a URL quoting that differs from the original – the field returns a DecodedString, which remembers those octets and packs back as exactly them. The decoded text is whatever it has always been, U+FFFD and all: a consumer that only reads the text, such as a dumper writing it back out as UTF-8, sees no change. A length of -1 is resolved to the number of encoded octets.

_encode(value)[source]¶

Encode a str value the way pre_process() packs it.

Parameters:: value (str) – Field value.
Return type:: bytes
Returns:: Encoded field value.

pre_process(value, packet)[source]¶

Process field value before construction (packing).

Parameters:

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

Return type:

bytes

Returns:

Processed field value.

post_process(value, packet)[source]¶

Process field value after parsing (unpacked).

Parameters:

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

Return type:

str

Returns:

Processed field value; a DecodedString carrying value where pre_process() would not otherwise reproduce it.

class pcapkit.corekit.fields.strings.BitField(length, default=<pcapkit.corekit.sentinels.NoValueType object>, namespace=None, callback=<function BitField.<lambda>>)[source]¶

Bases: _TextField[dict[str, Any]]

Bit value for protocol fields.

Parameters:

length (int) – Field size (in bytes).
default (dict[str, Any] | NoValueType) – Field default value, if any.
namespace (dict[str, Tuple[int, int]] | None) – Field namespace (a dict mapping field name to a tuple of start index, and length of the subfield).
callback (Callable[[Self, dict[str, Any]], None]) – Callback function to be called upon self.__call__.

Bits that no subfield names are kept as captured: where any of them is set, the unpacked value carries them under an __unnamed__ key, as an integer over the whole field with every named bit cleared, and packing writes them back (#1487). The key is absent when they are all zero, so a value built without it packs them as zeros.

UNNAMED = '__unnamed__'¶: Key of the unpacked value that carries the unnamed bits.

pre_process(value, packet)[source]¶

Process field value before construction (packing).

Parameters:

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

Return type:

bytes

Returns:

Processed field value.

Raises:

FieldValueError – If a subfield value does not fit the bits it was declared to occupy, or the __unnamed__ value is not an integer.

post_process(value, packet)[source]¶

Process field value after parsing (unpacked).

Parameters:

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

Return type:

dict[str, Any]

Returns:

Processed field value.

Internal Definitions¶

class pcapkit.corekit.fields.strings._TextField(length, default=<pcapkit.corekit.sentinels.NoValueType object>, callback=<function _TextField.<lambda>>)[source]¶

Bases: Field[_T], Generic[_T]

Internal text value 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, str, bytes, dict[str, Any]) | NoValueType) – Field default value, if any.
callback (Callable[[Self, dict[str, Any]], None]) – Callback function to be called upon self.__call__.

__call__(packet)[source]¶

Update field attributes.

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

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

Type Variables¶

pcapkit.corekit.fields.strings._T: str | bytes | python:dict[str, typing.Any]¶