Serializer implementation tools

Serializer implementation tools module.

class easynetwork.serializers.tools.GeneratorStreamReader

Bases: object

A binary stream-like object using an in-memory bytes buffer.

The “blocking” operation is done with the generator’s yield statement. It is an helper for incremental serializer implementations.

__init__(initial_bytes: bytes = b'') → None

Parameters:: initial_bytes (bytes) – a bytes object that contains initial data.

read_all() → bytes

Read and return all the bytes currently in the reader.

Returns:: a bytes object.
Return type:: bytes

read(size: int) → Generator[None, bytes, bytes]

Read and return up to size bytes.

Example:

def incremental_deserialize(self) -> Generator[None, bytes, tuple[Packet, bytes]]:
    reader = GeneratorStreamReader()

    data: bytes = yield from reader.read(1024)  # Get at most 1024 bytes.

    ...

Yields:: if there is no data in buffer.
Returns:: a bytes object.
Return type:: Generator[None, bytes, bytes]

read_exactly(n: int) → Generator[None, bytes, bytes]

Read exactly n bytes.

Example:

def incremental_deserialize(self) -> Generator[None, bytes, tuple[Packet, bytes]]:
    reader = GeneratorStreamReader()

    header: bytes = yield from reader.read_exactly(32)
    assert len(header) == 32

    ...

Yields:: until n bytes is in the buffer.
Returns:: a bytes object.
Return type:: Generator[None, bytes, bytes]

read_until(separator: bytes, limit: int, *, keep_end: bool = True) → Generator[None, bytes, bytes]

Read data from the stream until separator is found.

On success, the data and separator will be removed from the internal buffer (consumed).

If the amount of data read exceeds limit, a LimitOverrunError exception is raised, and the data is left in the internal buffer and can be read again.

Example:

def incremental_deserialize(self) -> Generator[None, bytes, tuple[Packet, bytes]]:
    reader = GeneratorStreamReader()

    line: bytes = yield from reader.read_until(b"\r\n", limit=65535)
    assert line.endswith(b"\r\n")

    ...

Parameters:

separator (bytes) – The byte sequence to find.
limit (int) – The maximum buffer size.
keep_end (bool) – If True (the default), returned data will include the separator at the end.

Raises:

LimitOverrunError – Reached buffer size limit.

Yields:

until separator is found in the buffer.

Returns:

a bytes object.

Return type:

Generator[None, bytes, bytes]