Text Fields

Bytes-Based Fields

class pcapkit.corekit.fields.strings.BytesField(length, default=NO_VALUE, callback=lambda *_: ...)[source]

Bases: _TextField[bytes]

Bytes value for protocol fields.

Parameters:
pre_process(value, packet)[source]

Process field value before construction (packing).

Parameters:
Return type:

bytes

Returns:

Processed field value.

class pcapkit.corekit.fields.strings.PaddingField(length=None, default=NO_VALUE, callback=lambda *_: ..., *, align=None, after=None)[source]

Bases: BytesField

Bytes value for protocol fields.

Parameters:

  • length (int | Callable[[dict[str, Any]], int] | None) – Field size (in bytes); if a callable is given, it should return an integer value and accept the current packet as its only argument. Left out when align sizes the field.

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

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

  • align (int | None) – Boundary, in octets, that the padding reaches, given with after in place of length. The field is then pad_length() octets long.

  • after (str | Callable[[dict[str, Any]], int] | None) – What the padding follows: the name of an earlier field whose value is its length in octets, or a callable that accepts the current packet and returns that length.

Raises:

  • FieldValueError – If length and align are both given or both left out, if only one of align and after is given, if after is neither a str nor a callable, or if align is not positive.

  • IntError – If align is not an int.

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.

Changed in version 1.6.0: Takes align and after as an alternative to length (#2614).

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=NO_VALUE, encoding=None, errors='strict', unquote=False, callback=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 the plain decoding, U+FFFD and all: a consumer that only reads the text, such as a dumper writing it back out as UTF-8, sees an ordinary str. 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:
Return type:

str

Returns:

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

class pcapkit.corekit.fields.strings.DecodedString(value, raw)[source]

Bases: str

Decoded StringField value that remembers its octets.

StringField returns one where encoding the decoded text would not reproduce the octets it was decoded from, so that the field packs it back as exactly those octets. It is otherwise an ordinary str, and deliberately so: it compares and hashes as its text, since the text is the value and raw is provenance. Two of them with the same text and different octets therefore compare equal – the alternative, mixing raw into __eq__(), would make info.comment == 'café' false against a plain str literal, which is the comparison callers actually write.

Any string operation on one returns a plain str, which a field then packs with its own encoding; that is intended, as an edited value is no longer the text those octets held.

Parameters:

  • value (str) – Decoded text.

  • raw (bytes) – Octets value was decoded from.

raw: bytes

Octets the string was decoded from.

class pcapkit.corekit.fields.strings.BitField(length, default=NO_VALUE, namespace=None, callback=lambda *_: ...)[source]

Bases: _TextField[dict[str, Any]]

Bit value for protocol fields.

Parameters:

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:
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:
Return type:

dict[str, Any]

Returns:

Processed field value.

Internal Definitions

class pcapkit.corekit.fields.strings._TextField[_T: (str, bytes, dict[str, Any])](length, default=NO_VALUE, callback=lambda *_: ...)[source]

Bases: Field[_T], Generic[_T]

Internal text value for protocol fields.

Parameters:
__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 | dict[str, Any]