Serialization and parsing¶

Serial¶

kio.serial.entity_reader(entity_type: type[Entity], nullable: bool = False) → Reader[Entity | None]¶

Parameters:

entity_type (type[Entity]) – Entity class to deserialize into.
nullable (bool) – When True, reading a null value returns None instead of raising.

Return type:

kio.serial.entity_writer(entity_type: type[E], nullable: bool = False) → Callable[[StreamWriter | IO[bytes], E | None], None][source]¶

Overloads:

entity_type (type[E]), nullable (Literal[False]) → Writer[E]
entity_type (type[E]), nullable (Literal[True]) → Writer[E | None]

Parameters:

entity_type (type[TypeVar(E, bound= Entity)])
nullable (bool)

Readers¶

Note

The reader functions below document the public API. The hot-path entity decoder in the native extension calls equivalent internal Rust functions directly and never crosses the Python boundary per field.

class kio.serial.readers.Reader(*args, **kwargs)[source]¶: Bases: Protocol [T_co]

kio.serial.readers.read_boolean(buffer: Buffer, offset: int, /) → tuple[bool, int]¶

Parameters:

buffer (Buffer)
offset (int)

Return type:

tuple[bool, int]

kio.serial.readers.read_int8(buffer: Buffer, offset: int, /) → tuple[i8, int]¶

Parameters:

buffer (Buffer)
offset (int)

Return type:

tuple[i8, int]

kio.serial.readers.read_int16(buffer: Buffer, offset: int, /) → tuple[i16, int]¶

Parameters:

buffer (Buffer)
offset (int)

Return type:

tuple[i16, int]

kio.serial.readers.read_int32(buffer: Buffer, offset: int, /) → tuple[i32, int]¶

Parameters:

buffer (Buffer)
offset (int)

Return type:

tuple[i32, int]

kio.serial.readers.read_int64(buffer: Buffer, offset: int, /) → tuple[i64, int]¶

Parameters:

buffer (Buffer)
offset (int)

Return type:

tuple[i64, int]

kio.serial.readers.read_uint8(buffer: Buffer, offset: int, /) → tuple[u8, int]¶

Parameters:

buffer (Buffer)
offset (int)

Return type:

tuple[u8, int]

kio.serial.readers.read_uint16(buffer: Buffer, offset: int, /) → tuple[u16, int]¶

Parameters:

buffer (Buffer)
offset (int)

Return type:

tuple[u16, int]

kio.serial.readers.read_uint32(buffer: Buffer, offset: int, /) → tuple[u32, int]¶

Parameters:

buffer (Buffer)
offset (int)

Return type:

tuple[u32, int]

kio.serial.readers.read_uint64(buffer: Buffer, offset: int, /) → tuple[u64, int]¶

Parameters:

buffer (Buffer)
offset (int)

Return type:

tuple[u64, int]

kio.serial.readers.read_unsigned_varint(buffer: Buffer, offset: int, /) → tuple[uvarint, int]¶

Deserialize an unsigned integer stored in variable-length encoding (1–5 bytes).

Parameters:

buffer (Buffer)
offset (int)

Return type:

tuple[uvarint, int]

kio.serial.readers.read_signed_varint(buffer: Buffer, offset: int, /) → tuple[svarint, int]¶

Parameters:

buffer (Buffer)
offset (int)

Return type:

tuple[svarint, int]

kio.serial.readers.read_unsigned_varlong(buffer: Buffer, offset: int, /) → tuple[uvarlong, int]¶

Parameters:

buffer (Buffer)
offset (int)

Return type:

tuple[uvarlong, int]

kio.serial.readers.read_signed_varlong(buffer: Buffer, offset: int, /) → tuple[svarlong, int]¶

Parameters:

buffer (Buffer)
offset (int)

Return type:

tuple[svarlong, int]

kio.serial.readers.read_float64(buffer: Buffer, offset: int, /) → tuple[f64, int]¶

Parameters:

buffer (Buffer)
offset (int)

Return type:

tuple[f64, int]

kio.serial.readers.read_compact_string_as_bytes(buffer: Buffer, offset: int, /) → tuple[bytes, int]¶

Parameters:

buffer (Buffer)
offset (int)

Return type:

tuple[bytes, int]

kio.serial.readers.read_compact_string_as_bytes_nullable(buffer: Buffer, offset: int, /) → tuple[bytes | None, int]¶

Parameters:

buffer (Buffer)
offset (int)

Return type:

tuple[bytes | None, int]

kio.serial.readers.read_compact_string(buffer: Buffer, offset: int, /) → tuple[str, int]¶

Parameters:

buffer (Buffer)
offset (int)

Return type:

tuple[str, int]

kio.serial.readers.read_compact_string_nullable(buffer: Buffer, offset: int, /) → tuple[str | None, int]¶

Parameters:

buffer (Buffer)
offset (int)

Return type:

tuple[str | None, int]

kio.serial.readers.read_legacy_bytes(buffer: Buffer, offset: int, /) → tuple[bytes, int]¶

Parameters:

buffer (Buffer)
offset (int)

Return type:

tuple[bytes, int]

kio.serial.readers.read_nullable_legacy_bytes(buffer: Buffer, offset: int, /) → tuple[bytes | None, int]¶

Parameters:

buffer (Buffer)
offset (int)

Return type:

tuple[bytes | None, int]

kio.serial.readers.read_legacy_string(buffer: Buffer, offset: int, /) → tuple[str, int]¶

Parameters:

buffer (Buffer)
offset (int)

Return type:

tuple[str, int]

kio.serial.readers.read_nullable_legacy_string(buffer: Buffer, offset: int, /) → tuple[str | None, int]¶

Parameters:

buffer (Buffer)
offset (int)

Return type:

tuple[str | None, int]

kio.serial.readers.read_legacy_array_length(buffer: Buffer, offset: int, /) → tuple[i32, int]¶

Parameters:

buffer (Buffer)
offset (int)

Return type:

tuple[i32, int]

kio.serial.readers.read_compact_array_length(buffer: Buffer, offset: int, /) → tuple[int | None, int]¶

Parameters:

buffer (Buffer)
offset (int)

Return type:

tuple[int | None, int]

kio.serial.readers.read_uuid(buffer: Buffer, offset: int, /) → tuple[UUID | None, int]¶

Parameters:

buffer (Buffer)
offset (int)

Return type:

tuple[UUID | None, int]

kio.serial.readers.compact_array_reader(item_reader: Reader[T]) → Reader[tuple[T, ...] | None]¶

Parameters:: item_reader (Reader[T]) – Reader for each array element.
Return type:: Reader[tuple[T, …] | None]

kio.serial.readers.legacy_array_reader(item_reader: Reader[T]) → Reader[tuple[T, ...] | None]¶

Parameters:: item_reader (Reader[T]) – Reader for each array element.
Return type:: Reader[tuple[T, …] | None]

kio.serial.readers.read_error_code(buffer: Buffer, offset: int, /) → tuple[ErrorCode, int]¶

Parameters:

buffer (Buffer)
offset (int)

Return type:

tuple[ErrorCode, int]

kio.serial.readers.read_timedelta_i32(buffer: Buffer, offset: int, /) → tuple[i32Timedelta, int]¶

Parameters:

buffer (Buffer)
offset (int)

Return type:

tuple[i32Timedelta, int]

kio.serial.readers.read_timedelta_i64(buffer: Buffer, offset: int, /) → tuple[i64Timedelta, int]¶

Parameters:

buffer (Buffer)
offset (int)

Return type:

tuple[i64Timedelta, int]

kio.serial.readers.tz_aware_from_i64(timestamp_ms: i64) → TZAware¶

Convert a millisecond timestamp to TZAware.

Parameters:: timestamp_ms (i64)
Return type:: TZAware

kio.serial.readers.read_datetime_i64(buffer: Buffer, offset: int, /) → tuple[TZAware, int]¶

Parameters:

buffer (Buffer)
offset (int)

Return type:

tuple[TZAware, int]

kio.serial.readers.read_nullable_datetime_i64(buffer: Buffer, offset: int, /) → tuple[TZAware | None, int]¶

Parameters:

buffer (Buffer)
offset (int)

Return type:

tuple[TZAware | None, int]

Writers¶

kio.serial.writers.write_boolean(buffer: StreamWriter | IO[bytes], value: bool) → None[source]¶

Parameters:

buffer (StreamWriter | IO[bytes])
value (bool)

Return type:

None

kio.serial.writers.write_int8(buffer: StreamWriter | IO[bytes], value: i8) → None[source]¶

Parameters:

buffer (StreamWriter | IO[bytes])
value (i8)

Return type:

None

kio.serial.writers.write_int16(buffer: StreamWriter | IO[bytes], value: i16) → None[source]¶

Parameters:

buffer (StreamWriter | IO[bytes])
value (i16)

Return type:

None

kio.serial.writers.write_int32(buffer: StreamWriter | IO[bytes], value: i32) → None[source]¶

Parameters:

buffer (StreamWriter | IO[bytes])
value (i32)

Return type:

None

kio.serial.writers.write_int64(buffer: StreamWriter | IO[bytes], value: i64) → None[source]¶

Parameters:

buffer (StreamWriter | IO[bytes])
value (i64)

Return type:

None

kio.serial.writers.write_uint8(buffer: StreamWriter | IO[bytes], value: u8) → None[source]¶

Parameters:

buffer (StreamWriter | IO[bytes])
value (u8)

Return type:

None

kio.serial.writers.write_uint16(buffer: StreamWriter | IO[bytes], value: u16) → None[source]¶

Parameters:

buffer (StreamWriter | IO[bytes])
value (u16)

Return type:

None

kio.serial.writers.write_uint32(buffer: StreamWriter | IO[bytes], value: u32) → None[source]¶

Parameters:

buffer (StreamWriter | IO[bytes])
value (u32)

Return type:

None

kio.serial.writers.write_uint64(buffer: StreamWriter | IO[bytes], value: u64) → None[source]¶

Parameters:

buffer (StreamWriter | IO[bytes])
value (u64)

Return type:

None

kio.serial.writers.write_unsigned_varint(buffer: StreamWriter | IO[bytes], value: uvarint) → None[source]¶

Parameters:

buffer (StreamWriter | IO[bytes])
value (uvarint)

Return type:

None

kio.serial.writers.write_unsigned_varlong(buffer: StreamWriter | IO[bytes], value: int) → None[source]¶

Parameters:

buffer (StreamWriter | IO[bytes])
value (int)

Return type:

None

kio.serial.writers.write_signed_varint(buffer: StreamWriter | IO[bytes], value: int) → None[source]¶

Parameters:

buffer (StreamWriter | IO[bytes])
value (int)

Return type:

None

kio.serial.writers.write_signed_varlong(buffer: StreamWriter | IO[bytes], value: int) → None[source]¶

Parameters:

buffer (StreamWriter | IO[bytes])
value (int)

Return type:

None

kio.serial.writers.write_float64(buffer: StreamWriter | IO[bytes], value: float) → None[source]¶

Parameters:

buffer (StreamWriter | IO[bytes])
value (float)

Return type:

None

kio.serial.writers.write_nullable_compact_string(buffer: StreamWriter | IO[bytes], value: str | bytes | None) → None[source]¶

Write a nullable string with compact length encoding.

Parameters:

buffer (StreamWriter | IO[bytes])
value (str | bytes | None)

Return type:

None

kio.serial.writers.write_compact_string(buffer: StreamWriter | IO[bytes], value: str | bytes) → None[source]¶

Write a non-nullable string with compact length encoding.

Parameters:

buffer (StreamWriter | IO[bytes])
value (str | bytes)

Return type:

None

kio.serial.writers.write_nullable_legacy_string(buffer: StreamWriter | IO[bytes], value: str | None) → None[source]¶

Write a nullable string with legacy int16 length encoding.

Parameters:

buffer (StreamWriter | IO[bytes])
value (str | None)

Return type:

None

kio.serial.writers.write_nullable_legacy_bytes(buffer: StreamWriter | IO[bytes], value: bytes | None) → None[source]¶

Write a nullable bytes with legacy int32 length encoding.

Parameters:

buffer (StreamWriter | IO[bytes])
value (bytes | None)

Return type:

None

kio.serial.writers.write_legacy_string(buffer: StreamWriter | IO[bytes], value: str) → None[source]¶

Write a non-nullable string with legacy int16 length encoding.

Parameters:

buffer (StreamWriter | IO[bytes])
value (str)

Return type:

None

kio.serial.writers.write_legacy_bytes(buffer: StreamWriter | IO[bytes], value: bytes) → None[source]¶

Write a non-nullable bytes with legacy int32 length encoding.

Parameters:

buffer (StreamWriter | IO[bytes])
value (bytes)

Return type:

None

kio.serial.writers.write_empty_tagged_fields(buffer: StreamWriter | IO[bytes]) → None[source]¶

Parameters:: buffer (StreamWriter | IO[bytes])
Return type:: None

kio.serial.writers.write_legacy_array_length(buffer: StreamWriter | IO[bytes], value: i32) → None[source]¶

Parameters:

buffer (StreamWriter | IO[bytes])
value (i32)

Return type:

None

kio.serial.writers.write_compact_array_length(buffer: StreamWriter | IO[bytes], value: int | None) → None[source]¶

Parameters:

buffer (StreamWriter | IO[bytes])
value (int | None)

Return type:

None

kio.serial.writers.write_uuid(buffer: StreamWriter | IO[bytes], value: UUID | None) → None[source]¶

Parameters:

buffer (StreamWriter | IO[bytes])
value (UUID | None)

Return type:

None

kio.serial.writers.compact_array_writer(item_writer: Callable[[StreamWriter | IO[bytes], T], None]) → Callable[[StreamWriter | IO[bytes], Sequence[T] | None], None][source]¶

Parameters:: item_writer (Callable[[StreamWriter | IO[bytes], TypeVar(T)], None])
Return type:: Callable[[StreamWriter | IO[bytes], Sequence[TypeVar(T)] | None], None]

kio.serial.writers.legacy_array_writer(item_writer: Callable[[StreamWriter | IO[bytes], T], None]) → Callable[[StreamWriter | IO[bytes], Sequence[T] | None], None][source]¶

Parameters:: item_writer (Callable[[StreamWriter | IO[bytes], TypeVar(T)], None])
Return type:: Callable[[StreamWriter | IO[bytes], Sequence[TypeVar(T)] | None], None]

kio.serial.writers.write_tagged_field(buffer: StreamWriter | IO[bytes], tag: uvarint, writer: Callable[[StreamWriter | IO[bytes], T], None], value: T) → None[source]¶

Parameters:

buffer (StreamWriter | IO[bytes])
tag (uvarint)
writer (Callable[[StreamWriter | IO[bytes], TypeVar(T)], None])
value (TypeVar(T))

Return type:

None

kio.serial.writers.write_error_code(buffer: StreamWriter | IO[bytes], error_code: ErrorCode) → None[source]¶

Parameters:

buffer (StreamWriter | IO[bytes])
error_code (ErrorCode)

Return type:

None

kio.serial.writers.write_timedelta_i32(buffer: StreamWriter | IO[bytes], value: i32Timedelta) → None[source]¶

Parameters:

buffer (StreamWriter | IO[bytes])
value (i32Timedelta)

Return type:

None

kio.serial.writers.write_timedelta_i64(buffer: StreamWriter | IO[bytes], value: i64Timedelta) → None[source]¶

Parameters:

buffer (StreamWriter | IO[bytes])
value (i64Timedelta)

Return type:

None

kio.serial.writers.write_datetime_i64(buffer: StreamWriter | IO[bytes], value: datetime) → None[source]¶

Parameters:

buffer (StreamWriter | IO[bytes])
value (datetime)

Return type:

None

kio.serial.writers.write_nullable_datetime_i64(buffer: StreamWriter | IO[bytes], value: datetime | None) → None[source]¶

Parameters:

buffer (StreamWriter | IO[bytes])
value (datetime | None)

Return type:

None

Errors¶

exception kio.serial.errors.SerialError[source]¶: Bases: Exception

exception kio.serial.errors.DecodeError[source]¶: Bases: SerialError

exception kio.serial.errors.UnexpectedNull[source]¶: Bases: DecodeError

exception kio.serial.errors.BufferUnderflow[source]¶: Bases: DecodeError

exception kio.serial.errors.InvalidUnicode[source]¶: Bases: DecodeError

exception kio.serial.errors.NegativeByteLength[source]¶: Bases: DecodeError

exception kio.serial.errors.SchemaError[source]¶: Bases: SerialError

exception kio.serial.errors.OutOfBoundValue[source]¶: Bases: SerialError

exception kio.serial.errors.EncodeError[source]¶: Bases: SerialError