Schema

Schema entities are generated from the upstream schema specification. Every API version has separate schema entities, to allow best-in-class typing support for message models. Schema entities are exposed in sub-modules under the kio.schema package, following this structure: kio.schema.<api-name>.<version>.<type>. So for example, if you want to use the response for version 12 of the metadata API, you would import it like so.

from kio.schema.metadata.v12.request import MetadataRequest

Introspection protocols

class kio.static.protocol.Entity(*args, **kwargs)

Bases: DataclassInstance, Protocol

All schema entities adhere to this protocol.

__version__: ClassVar[i16]

The version of the protocol API that the entity is modeling.

__flexible__: ClassVar[bool]

Whether the API version is “flexible” or not, see upstream protocol documentation.

class kio.static.protocol.Payload(*args, **kwargs)

Bases: DataclassInstance, Protocol

All payload entities, i.e. requests and responses, adhere to this protocol.

__version__: ClassVar[i16]

The version of the protocol API that the entity is modeling.

__flexible__: ClassVar[bool]

Whether the API version is “flexible” or not, see upstream protocol documentation.

__api_key__: ClassVar[i16]

Corresponding key of the modeled API.

property __header_schema__: type[RequestHeader | RequestHeader | RequestHeader | ResponseHeader | ResponseHeader]

The header entity type that should be used when sending or receiving this payload.

kio.static.protocol.ResponsePayload: TypeAlias = kio.static.protocol.HeaderV0ResponsePayload | kio.static.protocol.HeaderV1ResponsePayload

Convenient union type of all possible response payloads.

kio.static.protocol.RequestPayload: TypeAlias = kio.static.protocol.HeaderV0RequestPayload | kio.static.protocol.HeaderV1RequestPayload | kio.static.protocol.HeaderV2RequestPayload

Convenient union type of all possible request payloads.

kio.static.protocol.RequestHeader: TypeAlias = kio.schema.request_header.v0.header.RequestHeader | kio.schema.request_header.v1.header.RequestHeader | kio.schema.request_header.v2.header.RequestHeader

Convenient union type of all possible request header types.

kio.static.protocol.ResponseHeader: TypeAlias = kio.schema.response_header.v0.header.ResponseHeader | kio.schema.response_header.v1.header.ResponseHeader

Convenient union type of all possible response header types.

kio.static.protocol.Header: TypeAlias = kio.schema.request_header.v0.header.RequestHeader | kio.schema.request_header.v1.header.RequestHeader | kio.schema.request_header.v2.header.RequestHeader | kio.schema.response_header.v0.header.ResponseHeader | kio.schema.response_header.v1.header.ResponseHeader

Convenient union type of all possible request and response header types.

class kio.static.protocol.HeaderV0RequestPayload(*args, **kwargs)

Bases: Payload, Protocol

Protocol describing a request payload entity type with a V0 header.

class kio.static.protocol.HeaderV1RequestPayload(*args, **kwargs)

Bases: Payload, Protocol

Protocol describing a request payload entity type with a V1 header.

class kio.static.protocol.HeaderV2RequestPayload(*args, **kwargs)

Bases: Payload, Protocol

Protocol describing a request payload entity type with a V2 header.

class kio.static.protocol.HeaderV0ResponsePayload(*args, **kwargs)

Bases: Payload, Protocol

Protocol describing a response payload entity type with a V0 header.

class kio.static.protocol.HeaderV1ResponsePayload(*args, **kwargs)

Bases: Payload, Protocol

Protocol describing a response payload entity type with a V1 header.

Primitives

class kio.static.primitive.Records(instance)

Bases: bytes, Phantom

class kio.static.primitive.PhantomStr(instance)

Bases: str, Phantom

Phantom base for nominal string types (e.g. TopicName, GroupId).

Any plain str satisfies isinstance(x, SubClass) at runtime, so the Rust decoder can hand over a raw Python str without an extra wrapping call-object allocation.

class kio.static.primitive.Interval(instance)

Bases: int, Phantom

class kio.static.primitive.i64(instance)

Bases: Interval

class kio.static.primitive.i32(instance)

Bases: i64

class kio.static.primitive.i16(instance)

Bases: i32

class kio.static.primitive.i8(instance)

Bases: i16

class kio.static.primitive.uvarlong(instance)

Bases: Interval

class kio.static.primitive.u64(instance)

Bases: uvarlong

class kio.static.primitive.uvarint(instance)

Bases: u64

class kio.static.primitive.u32(instance)

Bases: uvarint

class kio.static.primitive.u16(instance)

Bases: u32

class kio.static.primitive.u8(instance)

Bases: u16

class kio.static.primitive.svarlong(instance)

Bases: Interval

class kio.static.primitive.svarint(instance)

Bases: svarlong

class kio.static.primitive.f64(instance)

Bases: float, Phantom

class kio.static.primitive.i32Timedelta(instance)

Bases: timedelta, Phantom

class kio.static.primitive.i64Timedelta(instance)

Bases: timedelta, Phantom

class kio.static.primitive.TZAwareMicros(instance)

Bases: datetime, Phantom

Type describing all datetime.datetime instances that are timezone aware, and have a non-negative unix timestamp representation.

• Timezone awareness means any object lacking timezone data is excluded.

• Kafka uses -1 to represent NULL, so negative unix timestamps are not supported.

class kio.static.primitive.TZAware(instance)

Bases: datetime, Phantom

Type describing all datetime.datetime instances that are timezone aware, have millisecond precision, and have a non-negative unix timestamp representation.

• Timezone awareness means any object lacking timezone data is excluded.

• Millisecond precision means any object with microsecond != 0 is excluded.

• Kafka uses -1 to represent NULL, so negative unix timestamps are not supported.

Types

class kio.schema.types.BrokerId(instance)

Bases: i32

class kio.schema.types.GroupId(instance)

Bases: PhantomStr

class kio.schema.types.ProducerId(instance)

Bases: i64

class kio.schema.types.TopicName(instance)

Bases: PhantomStr

class kio.schema.types.TransactionalId(instance)

Bases: PhantomStr

Constants

class kio.static.constants.EntityType(*values)

Bases: Enum