Pydantic-Avro

0.10.0 · active · verified Sat Apr 11

Pydantic-Avro is a Python library designed to convert Pydantic classes into Avro schemas, and vice-versa, allowing for seamless integration between Pydantic models and Avro data formats. It is actively maintained with frequent updates, with the latest stable version being 0.10.0.

Warnings

breaking Pydantic-Avro supports Pydantic versions >=1.4 and <3.0. While this range covers both Pydantic V1 and V2, mixing V1 and V2 models within an application using Pydantic-Avro can lead to unexpected behavior or incompatibilities due to significant architectural and API changes in Pydantic V2. Ensure consistent Pydantic versioning across your codebase, or leverage Pydantic's V1 compatibility layer (`from pydantic import v1 as pydantic_v1`) carefully.
Fix: Standardize your application's Pydantic version. If migrating to V2, update all models to V2 syntax. If using both, consult Pydantic's migration guide for interoperability strategies and ensure `pydantic-avro`'s behavior is as expected with mixed environments.
gotcha Generating an Avro schema for Pydantic fields defined with `typing.Literal` containing only a single string value (e.g., `Literal['only_value']`) may fail or produce incorrect schemas due to a known issue.
Fix: As a workaround, consider using a `Union` with a constant `str` for single-literal cases, or explicitly defining an `enum` Avro type if appropriate, until the issue is resolved.
breaking Prior to version `0.9.0`, `pydantic-avro` had issues with correctly converting unsupported list values and tuples in Pydantic models to their corresponding Avro schema types, potentially leading to errors during schema generation.
Fix: Upgrade to `pydantic-avro` version `0.9.0` or later to ensure proper handling of list and tuple types in Avro schema generation.
gotcha Version `0.9.3` introduced a new `mode` parameter to the `AvroBase.avro_schema()` method, allowing users more fine-grained control over how schemas are generated (e.g., for specific Avro features or compatibility). Users upgrading from older versions might not be aware of this enhanced functionality.
Fix: Review the documentation for the `mode` parameter in `AvroBase.avro_schema()` and incorporate it if you require more control or specific Avro schema generation behaviors.
gotcha From version `0.8.0` onwards, `pydantic-avro` provides explicit support for overriding the default Avro type conversion using `pydantic.Field(..., avro_type="your_avro_type")`. If you previously implemented custom logic or workarounds for specific type mappings, you can now use this native method.
Fix: Migrate any custom type conversion logic to use the `avro_type` argument within `pydantic.Field` for cleaner and officially supported type overrides.

Install

pip install pydantic-avro Install latest version

Imports

AvroBase
```
from pydantic_avro.base import AvroBase
```
Field
```
from pydantic import Field
```
Required for Pydantic field definitions, including Avro type overrides.

Quickstart

This example demonstrates how to define a Pydantic model inheriting from `AvroBase` and then generate its corresponding Avro schema. It also shows how to use `pydantic.Field` for adding descriptions and overriding default Avro type mappings (e.g., `datetime` to a 'string' Avro type explicitly).

import json
from typing import Optional
from pydantic import Field
from pydantic_avro.base import AvroBase

class User(AvroBase):
    id: int
    name: str = Field(..., description="User's full name")
    email: Optional[str] = None
    is_active: bool = True
    creation_date: str = Field(..., avro_type="string", description="Date of user creation in ISO format")

# Generate Avro schema
avro_schema = User.avro_schema()
print(json.dumps(avro_schema, indent=2))

view raw JSON →