`latest.ipv8.messaging.serialization`

Module Contents

Classes

`Packer`	A class that can pack and unpack objects to and from bytes.
`NestedPayload`	This is a special type of format. Allowing for nested packing.
`Bits`	A packer for bits into a byte.
`Raw`	Paste/unpack the remaining input without (un)packing.
`VarLen`	Pack/unpack from an encoded length + data string.
`VarLenUtf8`	Pack/unpack from an unencoded utf8 length + data string.
`IPv4`	Pack/unpack an IPv4 address.
`Address`	Any address format: IPv4, IPv6 or host format.
`ListOf`	A list of a given packer.
`DefaultArray`	A format known to the `array` module (like 'I', 'B', etc.).
`DefaultStruct`	A format known to the `struct` module (like 'I', '20s', etc.).
`Serializer`	The class performing serialization of Serializable objects.
`Serializable`	Interface for serializable objects.
`Payload`	A serializable that has extra printing functionality.

Attributes

`ADDRESS_TYPE_IPV4`
`ADDRESS_TYPE_DOMAIN_NAME`
`ADDRESS_TYPE_IPV6`
`FormatListType`
`T`
`A`
`SelfS`
`S`
`default_serializer`

latest.ipv8.messaging.serialization.ADDRESS_TYPE_IPV4 = 1

latest.ipv8.messaging.serialization.ADDRESS_TYPE_DOMAIN_NAME = 2

latest.ipv8.messaging.serialization.ADDRESS_TYPE_IPV6 = 3

latest.ipv8.messaging.serialization.FormatListType

exception latest.ipv8.messaging.serialization.PackError

Bases: RuntimeError

A given message format could not be packed to bytes or unpacked from bytes.

latest.ipv8.messaging.serialization.T

latest.ipv8.messaging.serialization.A

class latest.ipv8.messaging.serialization.Packer

Bases: Generic[T, A]

A class that can pack and unpack objects to and from bytes.

abstract pack(data: T) → bytes: Pack the given data.

abstract unpack(data: bytes, offset: int, unpack_list: list, *args: A) → int: Unpack an object from the given data buffer and return the new offset in the data buffer.

class latest.ipv8.messaging.serialization.NestedPayload(serializer: Serializer)

Bases: Packer

This is a special type of format. Allowing for nested packing.

You can specify which serializable to use by specifying its class in the format_list of the parent Serializable.

For example, nesting a Serializable of class B in class A:

class A(Serializable):
    format_list = [B]

def __init__(self, b_instance):
    pass

def to_pack_list(self):
    return [("payload", B())]

@classmethod
def from_unpack_list(cls, *args):
    return A(*args)

pack(serializable: Serializable) → bytes

Pack some serializable.

Parameters:: serializable – the Serializable instance which we should serialize.
Returns:: the serialized data

unpack(data: bytes, offset: int, unpack_list: list, *args: type[Serializable]) → int

Unpack a Serializable using a class definition for some given data and offset. This is a special unpack_from which also takes a payload class.

Parameters:

data – the data to unpack from
offset – the offset in the list of data to unpack from
unpack_list – the list to which to append the Serializable
args – a list of one Serializable class to unpack to

Returns:

the new offset

class latest.ipv8.messaging.serialization.Bits

Bases: Packer

A packer for bits into a byte.

pack(*data: int) → bytes

Pack multiple bits into a single byte.

Parameters:

*data –

bit values

unpack(data: bytes, offset: int, unpack_list: list, *args: object) → int

Unpack multiple bits from a single byte. The resulting bits are appended to unpack_list.

Returns:: the new offset

class latest.ipv8.messaging.serialization.Raw

Bases: Packer

Paste/unpack the remaining input without (un)packing.

pack(packable: bytes) → bytes: Forward the packable without doing anything to it.

unpack(data: bytes, offset: int, unpack_list: list, *args: object) → int: Match everything remaining in the data as a bytes string.

class latest.ipv8.messaging.serialization.VarLen(length_format: str, base: int = 1)

Bases: Packer

Pack/unpack from an encoded length + data string.

pack(data: bytes) → bytes: Prefix the length of the given data to it and return the result.

unpack(data: bytes, offset: int, unpack_list: list, *args: object) → int: Unpack from VarLen packed data.

class latest.ipv8.messaging.serialization.VarLenUtf8(length_format: str, base: int = 1)

Bases: VarLen

Pack/unpack from an unencoded utf8 length + data string.

pack(data: str) → bytes: Pack a UTF-8 string.

unpack(data: bytes, offset: int, unpack_list: list, *args: object) → int: Unpack an encoded UTF-8 string.

class latest.ipv8.messaging.serialization.IPv4

Bases: Packer

Pack/unpack an IPv4 address.

pack(data: tuple[str, int]) → bytes: Pack an IPv4 address to bytes.

unpack(data: bytes, offset: int, unpack_list: list, *args: object) → int: Unpack a packed IPv4 address.

class latest.ipv8.messaging.serialization.Address(ip_only: bool = False)

Bases: Packer

Any address format: IPv4, IPv6 or host format.

pack(address: tuple[str, int]) → bytes: Pack a generic address as bytes.

unpack(data: bytes, offset: int, unpack_list: list, *args: object) → int: Unpack a generic address from bytes.

class latest.ipv8.messaging.serialization.ListOf(packer: Packer, length_format: str = '>B')

Bases: Packer

A list of a given packer.

pack(data: list) → bytes: Feed a list of objects to the registered packer.

unpack(data: bytes, offset: int, unpack_list: list, *args: object) → int: Unpack a list of objects from the data.

class latest.ipv8.messaging.serialization.DefaultArray(format_str: str, length_format: str)

Bases: Packer

A format known to the array module (like ‘I’, ‘B’, etc.).

Also adds support for ‘?’.

pack(data: list) → bytes: Pack a list of items by forwarding them to array.

unpack(data: bytes, offset: int, unpack_list: list, *args: object) → int: Unpack a list of items from the known array format.

class latest.ipv8.messaging.serialization.DefaultStruct(format_str: str)

Bases: Packer

A format known to the struct module (like ‘I’, ’20s’, etc.).

pack(*data: list) → bytes: Pack a list of items by forwarding them to struct.

unpack(data: bytes, offset: int, unpack_list: list, *args: object) → int: Unpack a list of items from the known struct format.

class latest.ipv8.messaging.serialization.Serializer

The class performing serialization of Serializable objects.

get_available_formats() → list[str]: Get all available packing formats.

get_packer_for(name: str) → Packer: Get a packer by name.

add_packer(name: str, packer: Packer) → None

Register a new packer with a certain name.

Parameters:

name – the name to register
packer – the packer to use for it

pack(fmt: str, item: object) → bytes

Pack data without using a Serializable. Using a Serializable is the preferred method.

Parameters:

fmt – the name of the packer to use while packing
item – object to pack

Returns:

the packed data

unpack(fmt: FormatListType, data: bytes, offset: int = 0) → tuple[object, int]

Unpack data without using a Serializable. Using a Serializable is the preferred method.

Parameters:

fmt – the name of the packer to use while unpacking
data – bytes to unpack

Returns:

the unpacked object

pack_serializable(serializable: Serializable) → bytes

Serialize a single Serializable instance.

Parameters:: serializable (Serializable) – the Serializable to pack
Returns:: the serialized object

pack_serializable_list(serializables: collections.abc.Sequence[Serializable]) → bytes

Serialize a list of Serializable instances.

Parameters:: serializables ([Serializable]) – the Serializables to pack
Returns:: the serialized list

unpack_serializable(serializable: type[S], data: bytes, offset: int = 0) → tuple[S, int]

Use the formats specified in a serializable object and unpack to it.

Parameters:

serializable – the serializable classes to get the format from and unpack to
data – the data to unpack from
offset – the optional offset to unpack data from

unpack_serializable_list(serializables: collections.abc.Sequence[type[Serializable]], data: bytes, offset: int = 0, consume_all: bool = True) → list[Serializable | bytes]

Use the formats specified in a list of serializable objects and unpack to them.

Parameters:

serializables – the serializable classes to get the format from and unpack to
data – the data to unpack from
offset – position at which to start reading from data
consume_all – if having a non-empty remainder should throw an error

Raises:

PackError – if the data could not be fit into the specified serializables
PackError – if consume_all is True and not all of the data was consumed when parsing the serializables

Returns:

the list of Serializable instances

latest.ipv8.messaging.serialization.SelfS

class latest.ipv8.messaging.serialization.Serializable

Interface for serializable objects.

format_list: list[FormatListType] = []

abstract to_pack_list() → list[tuple]

Serialize this object to a Serializer pack list.

E.g.: [(format1, data1), (format2, data2), (format3, data3), ..]

abstract classmethod from_unpack_list(*args: Any, **kwargs) → SelfS: Create a new Serializable object from a list of unpacked variables.

latest.ipv8.messaging.serialization.S

class latest.ipv8.messaging.serialization.Payload

Bases: Serializable, abc.ABC

A serializable that has extra printing functionality.

__str__() → str: The string representation of this payload.

latest.ipv8.messaging.serialization.default_serializer

latest.ipv8.messaging.serialization

Module Contents

Classes

Attributes

`latest.ipv8.messaging.serialization`