IP Address Fields¶

Changed in version 1.5.0: Every field here rejects a bool with FieldValueError, where an IPv4 field packed True and False as 0.0.0.1 and 0.0.0.0 (#491).

Removed in version 1.6.0: pcapkit.corekit.fields.ipaddress.parse_ip_address and pcapkit.corekit.fields.ipaddress._reject_bool, now pcapkit.corekit.schema.ipaddress.parse_ip_address() and pcapkit.corekit.schema.ipaddress._reject_bool() (#2674).

IP Addresses¶

class pcapkit.corekit.fields.ipaddress.IPv4AddressField(default=NO_VALUE, callback=lambda *_: ...)[source]¶

Bases: _IPAddressField[IPv4Address]

IPv4 address value for protocol fields.

Parameters:

default (IPv4Address | NoValueType) – Field default value, if any.
callback (Callable[[Self, dict[str, Any]], None]) – Callback function to be called upon self.__call__.

property version: Literal[4]¶: IP version number.

class pcapkit.corekit.fields.ipaddress.IPv6AddressField(default=NO_VALUE, callback=lambda *_: ...)[source]¶

Bases: _IPAddressField[IPv6Address]

IPv6 address value for protocol fields.

Parameters:

default (IPv6Address | NoValueType) – Field default value, if any.
callback (Callable[[Self, dict[str, Any]], None]) – Callback function to be called upon self.__call__.

property version: Literal[6]¶: IP version number.

IP Interface¶

class pcapkit.corekit.fields.ipaddress.IPv4InterfaceField(default=NO_VALUE, callback=lambda *_: ...)[source]¶

Bases: _IPInterfaceField[IPv4Interface]

IPv4 interface value for protocol fields.

Parameters:

default (IPv4Interface | NoValueType) – Field default value, if any.
callback (Callable[[Self, dict[str, Any]], None]) – Callback function to be called upon self.__call__.

Changed in version 1.5.0: A mask that is not a contiguous netmask unpacks to an IPv4Interface subclass that keeps its four octets, where a hostmask-shaped one was read as a prefix length and any other raised (#1294).

property version: Literal[4]¶: IP version number.

pre_process(value, packet)[source]¶

Process field value before packing.

Parameters:

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

Return type:

bytes

Returns:

Processed field value.

Raises:

FieldValueError – If value is a bool (cf. _reject_bool()), is not a valid IP interface, or is the wrong IP version for this field.

Notes

A string means what ipaddress.ip_interface() says it means, so '10.0.0.1/0.0.0.255' is the hostmask spelling of /24. Only a string the stdlib rejects is read with its mask taken literally: a dotted mask that is neither a netmask nor a hostmask, such as '10.0.0.1/255.0.255.0', or eight hex digits, such as '10.0.0.1/0x000000ff'. Those are the forms str gives a _RawMaskIPv4Interface.

post_process(value, packet)[source]¶

Process field value after parsing (unpacking).

Parameters:

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

Return type:

IPv4Interface

Returns:

Processed field value.

Raises:

FieldValueError – If the resulting interface is the wrong IP version for this field. The eight octets cannot actually fail to convert here – they are always exactly 8 octets, fixed by this field’s length, any four octets are a valid address, and a mask that is not a netmask is kept as given – but the conversion is still wrapped for consistency with the rest of this module.

Notes

The trailing four octets are a dotted netmask, as written by pre_process() – not a prefix length as in IPv6InterfaceField.post_process(). When they are not a contiguous netmask, the value is a _RawMaskIPv4Interface that keeps them as given, rather than an interface the stdlib would reinterpret (0.0.0.255 as the hostmask of /24).

class pcapkit.corekit.fields.ipaddress.IPv6InterfaceField(default=NO_VALUE, callback=lambda *_: ...)[source]¶

Bases: _IPInterfaceField[IPv6Interface]

IPv6 interface value for protocol fields.

Parameters:

default (IPv6Interface | NoValueType) – Field default value, if any.
callback (Callable[[Self, dict[str, Any]], None]) – Callback function to be called upon self.__call__.

property version: Literal[6]¶: IP version number.

pre_process(value, packet)[source]¶

Process field value before packing.

Parameters:

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

Return type:

bytes

Returns:

Processed field value.

Raises:

FieldValueError – If value is a bool (cf. _reject_bool()), is not a valid IP interface, or is the wrong IP version for this field.

post_process(value, packet)[source]¶

Process field value after parsing (unpacking).

Parameters:

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

Return type:

IPv6Interface

Returns:

Processed field value.

Raises:

FieldValueError – If the trailing octet is not a valid IPv6 prefix length, i.e. greater than 128, or if the resulting interface is the wrong IP version for this field. Neither the leading sixteen octets nor the final ipaddress.ip_interface() call can actually fail here – the former is always exactly 16 octets, fixed by this field’s length, and any such octet string is a valid address; the latter is only ever reached once the prefix length has already been checked above, and any prefix length in 0..128 is valid. Both conversions are still wrapped for consistency with the rest of this module.

Notes

The trailing octet is the prefix length as a binary integer, as written by pre_process() – not a dotted netmask as in IPv4InterfaceField.post_process().

Internal Definitions¶

class pcapkit.corekit.fields.ipaddress._IPField[_T: (IPv4Address, IPv6Address, IPv4Interface, IPv6Interface)](length, default=NO_VALUE, callback=lambda *_: ...)[source]¶

Bases: Field[_T], Generic[_T]

Internal IP related value for protocol fields.

Parameters:

length (int | Callable[[dict[str, Any]], int]) – Field size (in bytes).
callback (Callable[[Self, dict[str, Any]], None]) – Callback function to be called upon self.__call__.

abstract property version: int¶: IP version number.

class pcapkit.corekit.fields.ipaddress._IPAddressField[_AT: (IPv4Address, IPv6Address)](length, default=NO_VALUE, callback=lambda *_: ...)[source]¶

Bases: _IPField[_AT]

Internal IP address value for protocol fields.

Parameters:

length (int | Callable[[dict[str, Any]], int]) – Field size (in bytes).
callback (Callable[[Self, dict[str, Any]], None]) – Callback function to be called upon self.__call__.

pre_process(value, packet)[source]¶

Process field value before packing.

Parameters:

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

Return type:

bytes

Returns:

Processed field value.

Raises:

FieldValueError – If value is a bool (cf. _reject_bool()), is not a valid IP address, or is the wrong IP version for this field.

post_process(value, packet)[source]¶

Process field value after parsing (unpacking).

Parameters:

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

Return type:

_AT

Returns:

Processed field value.

Raises:

FieldValueError – If value is the wrong IP version for this field. value cannot actually fail the underlying ipaddress.ip_address() conversion here – it is always exactly 4 or 16 octets, fixed by this field’s length, and any such octet string is a valid address – but the conversion is still wrapped for consistency with the rest of this module.

class pcapkit.corekit.fields.ipaddress._IPInterfaceField[_IT: (IPv4Interface, IPv6Interface)](length, default=NO_VALUE, callback=lambda *_: ...)[source]¶

Bases: _IPField[_IT]

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

class pcapkit.corekit.fields.ipaddress._RawMaskIPv4Interface(address)[source]¶

Bases: IPv4Interface

IPv4 interface whose mask is not a contiguous netmask.

Parameters:: address (str) – Dotted address and mask, as 'a.b.c.d/m.m.m.m' or 'a.b.c.d/0xXXXXXXXX'; either way the mask is read literally.

ipaddress.IPv4Interface can only hold a prefix length, so it reads a hostmask-shaped mask such as 0.0.0.255 as /24 and rejects a mask such as 255.0.255.0. This class keeps the mask octets as given in netmask, so IPv4InterfaceField.pre_process() writes them back unchanged.

str, repr() and pickle use the address/mask form, which IPv4InterfaceField.pre_process() packs back to the same octets. The mask is dotted, except when it is hostmask-shaped (ones, then zeros, read from the low bit): ipaddress.ip_interface() would read such a dotted mask as a hostmask, so it is written as eight hex digits instead, e.g. 10.0.0.1/0x000000ff. The stdlib rejects that hex form, so it never means anything else there.

Equality and ordering use the mask too. An instance sorts as the stdlib sorts address/32, then by mask, so the order stays total when mixed with ipaddress.IPv4Interface values.

Such a mask has no prefix length, so network, with_prefixlen and the prefix length all describe the address alone (/32); only netmask, hostmask, with_netmask and with_hostmask carry the mask. with_netmask is always dotted, so it is not the round-trip form; str is.

netmask¶: Mask octets as given, which need not form a contiguous netmask.

property hostmask: IPv4Address¶: Bitwise inverse of netmask.

Type Variables¶

pcapkit.corekit.fields.ipaddress._T: ipaddress.IPv4Address | ipaddress.IPv6Address | ipaddress.IPv4Interface | ipaddress.IPv6Interface¶

pcapkit.corekit.fields.ipaddress._AT: ipaddress.IPv4Address | ipaddress.IPv6Address¶

pcapkit.corekit.fields.ipaddress._IT: ipaddress.IPv4Interface | ipaddress.IPv6Interface¶