pydantic-avro

pydantic-avro bridges Pydantic and Apache Avro by converting a Pydantic model class into an Avro schema (via the AvroBase mixin’s avro_schema() method) and, in the other direction, generating Pydantic model source code from an existing .avsc schema file. It supports explicit Avro type overrides via Field(..., avro_type=...) for cases where the default Python-to-Avro type mapping needs to be customized, and ships both a Python API and a pydantic-avro CLI command for the avro-to-pydantic code generation workflow.

What You Get

• An AvroBase mixin class whose avro_schema() method converts any Pydantic model to an Avro schema dict
• A pydantic-avro avro_to_pydantic CLI command that generates Pydantic model source code from an .avsc schema file
• Field-level Avro type overrides via Field(..., avro_type="long") for precise control over generated schema types
• Support for both Pydantic v1 and v2 (pydantic>=1.4,<3.0)

Common Use Cases

• Generating Avro schemas for Kafka producers directly from existing Pydantic request/response models
• Bootstrapping Pydantic models from a team’s existing Avro schema registry to keep application types in sync with wire formats
• Keeping API validation models and event-streaming schemas from drifting apart in data-pipeline services
• Customizing Avro type mapping (e.g. timestamp precision) for fields where the default inference isn’t precise enough

Under The Hood

Architecture - The library splits cleanly into two directional converters under src/pydantic_avro/: to_avro/base.py and to_avro/types.py implement the AvroBase mixin and Python-to-Avro type mapping, while from_avro/avro_to_pydantic.py, from_avro/types.py, and from_avro/class_registery.py implement the reverse direction, parsing an Avro schema and emitting Pydantic source code; __main__.py wires the CLI (pydantic-avro entry point) to the avro_to_pydantic code path. Tech Stack - Pure Python (>=3.8.1,<4.0) managed with Poetry, with pydantic as the sole runtime dependency (supporting both v1 and v2 via version-range pinning), and dev tooling covering black, isort, pyproject-flake8, mypy, and pytest-cov for linting/type-checking/coverage. Code Quality - The tests/ directory has dedicated suites for each direction (test_to_avro.py, test_from_avro.py), a test_main.py for the CLI entry point, and test_public_api.py guarding the exported surface; CI runs a GitHub Actions workflow with CodeQL scanning and Codecov reporting, though GitHub activity shows the project has cooled to infrequent maintenance in recent months. API Design - The AvroBase mixin keeps the to-avro direction essentially zero-boilerplate (inherit from AvroBase, call .avro_schema()), while the avro-to-pydantic direction is exposed identically via both a Python function and a CLI flag, giving users a choice between scripting and one-off command-line generation.