3.0.ipv8.messaging.serialization ================================ .. py:module:: 3.0.ipv8.messaging.serialization Attributes ---------- .. autoapisummary:: 3.0.ipv8.messaging.serialization.ADDRESS_TYPE_IPV4 3.0.ipv8.messaging.serialization.ADDRESS_TYPE_DOMAIN_NAME 3.0.ipv8.messaging.serialization.ADDRESS_TYPE_IPV6 3.0.ipv8.messaging.serialization.FormatListType 3.0.ipv8.messaging.serialization.T 3.0.ipv8.messaging.serialization.A 3.0.ipv8.messaging.serialization.SelfS 3.0.ipv8.messaging.serialization.S 3.0.ipv8.messaging.serialization.default_serializer Exceptions ---------- .. autoapisummary:: 3.0.ipv8.messaging.serialization.PackError Classes ------- .. autoapisummary:: 3.0.ipv8.messaging.serialization.Packer 3.0.ipv8.messaging.serialization.NestedPayload 3.0.ipv8.messaging.serialization.Bits 3.0.ipv8.messaging.serialization.Raw 3.0.ipv8.messaging.serialization.VarLen 3.0.ipv8.messaging.serialization.VarLenUtf8 3.0.ipv8.messaging.serialization.IPv4 3.0.ipv8.messaging.serialization.Address 3.0.ipv8.messaging.serialization.ListOf 3.0.ipv8.messaging.serialization.DefaultArray 3.0.ipv8.messaging.serialization.DefaultStruct 3.0.ipv8.messaging.serialization.Serializer 3.0.ipv8.messaging.serialization.Serializable 3.0.ipv8.messaging.serialization.Payload Module Contents --------------- .. py:data:: ADDRESS_TYPE_IPV4 :value: 1 .. py:data:: ADDRESS_TYPE_DOMAIN_NAME :value: 2 .. py:data:: ADDRESS_TYPE_IPV6 :value: 3 .. py:data:: FormatListType .. py:exception:: PackError Bases: :py:obj:`RuntimeError` A given message format could not be packed to bytes or unpacked from bytes. .. py:data:: T .. py:data:: A .. py:class:: Packer Bases: :py:obj:`Generic`\ [\ :py:obj:`T`\ , :py:obj:`A`\ ] A class that can pack and unpack objects to and from bytes. .. py:method:: pack(data: T) -> bytes :abstractmethod: Pack the given data. .. py:method:: unpack(data: bytes, offset: int, unpack_list: list, *args: A) -> int :abstractmethod: Unpack an object from the given data buffer and return the new offset in the data buffer. .. py:class:: NestedPayload(serializer: Serializer) Bases: :py:obj:`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) .. py:attribute:: serializer .. py:method:: pack(serializable: Serializable) -> bytes Pack some serializable. :param serializable: the Serializable instance which we should serialize. :return: the serialized data .. py:method:: 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. :param data: the data to unpack from :param offset: the offset in the list of data to unpack from :param unpack_list: the list to which to append the Serializable :param args: a list of one Serializable class to unpack to :return: the new offset .. py:class:: Bits Bases: :py:obj:`Packer` A packer for bits into a byte. .. py:method:: pack(*data: int) -> bytes Pack multiple bits into a single byte. :param *data: bit values :type *data: list of 8 True or False values (or anything that maps to it in an if-statement) .. py:method:: 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 .. py:class:: Raw Bases: :py:obj:`Packer` Paste/unpack the remaining input without (un)packing. .. py:method:: pack(packable: bytes) -> bytes Forward the packable without doing anything to it. .. py:method:: unpack(data: bytes, offset: int, unpack_list: list, *args: object) -> int Match everything remaining in the data as a bytes string. .. py:class:: VarLen(length_format: str, base: int = 1) Bases: :py:obj:`Packer` Pack/unpack from an encoded length + data string. .. py:attribute:: length_format .. py:attribute:: length_size .. py:attribute:: base .. py:method:: pack(data: bytes) -> bytes Prefix the length of the given data to it and return the result. .. py:method:: unpack(data: bytes, offset: int, unpack_list: list, *args: object) -> int Unpack from VarLen packed data. .. py:class:: VarLenUtf8(length_format: str, base: int = 1) Bases: :py:obj:`VarLen` Pack/unpack from an unencoded utf8 length + data string. .. py:method:: pack(data: str) -> bytes Pack a UTF-8 string. .. py:method:: unpack(data: bytes, offset: int, unpack_list: list, *args: object) -> int Unpack an encoded UTF-8 string. .. py:class:: IPv4 Bases: :py:obj:`Packer` Pack/unpack an IPv4 address. .. py:method:: pack(data: tuple[str, int]) -> bytes Pack an IPv4 address to bytes. .. py:method:: unpack(data: bytes, offset: int, unpack_list: list, *args: object) -> int Unpack a packed IPv4 address. .. py:class:: Address(ip_only: bool = False) Bases: :py:obj:`Packer` Any address format: IPv4, IPv6 or host format. .. py:attribute:: ip_only .. py:method:: pack(address: tuple[str, int]) -> bytes Pack a generic address as bytes. .. py:method:: unpack(data: bytes, offset: int, unpack_list: list, *args: object) -> int Unpack a generic address from bytes. .. py:class:: ListOf(packer: Packer, length_format: str = '>B') Bases: :py:obj:`Packer` A list of a given packer. .. py:attribute:: packer .. py:attribute:: length_format .. py:attribute:: length_size .. py:method:: pack(data: list) -> bytes Feed a list of objects to the registered packer. .. py:method:: unpack(data: bytes, offset: int, unpack_list: list, *args: object) -> int Unpack a list of objects from the data. .. py:class:: DefaultArray(format_str: str, length_format: str) Bases: :py:obj:`Packer` A format known to the ``array`` module (like 'I', 'B', etc.). Also adds support for '?'. .. py:attribute:: format_str .. py:attribute:: real_format_str .. py:attribute:: length_format .. py:attribute:: length_size .. py:attribute:: base .. py:method:: pack(data: list) -> bytes Pack a list of items by forwarding them to ``array``. .. py:method:: unpack(data: bytes, offset: int, unpack_list: list, *args: object) -> int Unpack a list of items from the known ``array`` format. .. py:class:: DefaultStruct(format_str: str) Bases: :py:obj:`Packer` A format known to the ``struct`` module (like 'I', '20s', etc.). .. py:attribute:: format_str .. py:attribute:: size .. py:method:: pack(*data: list) -> bytes Pack a list of items by forwarding them to ``struct``. .. py:method:: unpack(data: bytes, offset: int, unpack_list: list, *args: object) -> int Unpack a list of items from the known ``struct`` format. .. py:class:: Serializer The class performing serialization of Serializable objects. .. py:attribute:: _packers :type: dict[str, Packer] .. py:method:: get_available_formats() -> list[str] Get all available packing formats. .. py:method:: get_packer_for(name: str) -> Packer Get a packer by name. .. py:method:: add_packer(name: str, packer: Packer) -> None Register a new packer with a certain name. :param name: the name to register :param packer: the packer to use for it .. py:method:: pack(fmt: str, item: object) -> bytes Pack data without using a Serializable. Using a Serializable is the preferred method. :param fmt: the name of the packer to use while packing :param item: object to pack :return: the packed data .. py:method:: unpack(fmt: FormatListType, data: bytes, offset: int = 0) -> tuple[object, int] Unpack data without using a Serializable. Using a Serializable is the preferred method. :param fmt: the name of the packer to use while unpacking :param data: bytes to unpack :return: the unpacked object .. py:method:: pack_serializable(serializable: Serializable) -> bytes Serialize a single Serializable instance. :param serializable: the Serializable to pack :type serializable: Serializable :return: the serialized object .. py:method:: pack_serializable_list(serializables: collections.abc.Sequence[Serializable]) -> bytes Serialize a list of Serializable instances. :param serializables: the Serializables to pack :type serializables: [Serializable] :return: the serialized list .. py:method:: 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. :param serializable: the serializable classes to get the format from and unpack to :param data: the data to unpack from :param offset: the optional offset to unpack data from .. py:method:: 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. :param serializables: the serializable classes to get the format from and unpack to :param data: the data to unpack from :param offset: position at which to start reading from data :param consume_all: if having a non-empty remainder should throw an error :except PackError: if the data could not be fit into the specified serializables :except PackError: if consume_all is True and not all of the data was consumed when parsing the serializables :return: the list of Serializable instances .. py:data:: SelfS .. py:class:: Serializable Interface for serializable objects. .. py:attribute:: format_list :type: list[FormatListType] :value: [] .. py:method:: to_pack_list() -> list[tuple] :abstractmethod: Serialize this object to a Serializer pack list. E.g.: ``[(format1, data1), (format2, data2), (format3, data3), ..]`` .. py:method:: from_unpack_list(*args: Any, **kwargs) -> SelfS :classmethod: :abstractmethod: Create a new Serializable object from a list of unpacked variables. .. py:data:: S .. py:class:: Payload Bases: :py:obj:`Serializable`, :py:obj:`abc.ABC` A serializable that has extra printing functionality. .. py:method:: __str__() -> str The string representation of this payload. .. py:data:: default_serializer