apicurio-serdes

Python serialization library for Apicurio Registry.

Provides Avro serializers that fetch and cache schemas from an Apicurio Registry v3 instance, with support for both sync and async usage. Two wire formats are supported: the Confluent-compatible payload framing and Apicurio's Kafka-headers mode.

Feature status

Feature	Status
Sync registry client (ApicurioRegistryClient)	Shipped
Async registry client (AsyncApicurioRegistryClient)	Shipped
Avro serializer (AvroSerializer)	Shipped
Avro deserializer (AvroDeserializer)	Shipped
Confluent wire format (magic byte + globalId)	Shipped
Kafka-headers wire format	Shipped

Installation

pip install apicurio-serdes

Quick start

Sync client

from apicurio_serdes import ApicurioRegistryClient

client = ApicurioRegistryClient(
    url="http://localhost:8080/apis/registry/v3",
    group_id="com.example.schemas",
)

cached = client.get_schema("UserEvent")
# cached.schema     — parsed Avro schema dict (fastavro-ready)
# cached.global_id  — Apicurio globalId
# cached.content_id — Apicurio contentId

Async client

from apicurio_serdes import AsyncApicurioRegistryClient

client = AsyncApicurioRegistryClient(
    url="http://localhost:8080/apis/registry/v3",
    group_id="com.example.schemas",
)

cached = await client.get_schema("UserEvent")

Wire formats

from apicurio_serdes import WireFormat

# Magic byte (0x00) + 4-byte globalId prefix — Confluent-compatible
WireFormat.CONFLUENT_PAYLOAD

# Raw Avro bytes; schema ID carried in a Kafka message header
WireFormat.KAFKA_HEADERS

Contributing

See CONTRIBUTING.md for dev setup, coding standards, and how to submit a pull request.

License

MIT