{"id":4186,"library":"pydantic-avro","title":"Pydantic-Avro","description":"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.","status":"active","version":"0.10.0","language":"en","source_language":"en","source_url":"https://github.com/godatadriven/pydantic-avro","tags":["pydantic","avro","schema","serialization","data validation","kafka"],"install":[{"cmd":"pip install pydantic-avro","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core dependency for defining data models, supporting versions >=1.4,<3.0.","package":"pydantic","optional":false}],"imports":[{"symbol":"AvroBase","correct":"from pydantic_avro.base import AvroBase"},{"note":"Required for Pydantic field definitions, including Avro type overrides.","symbol":"Field","correct":"from pydantic import Field"}],"quickstart":{"code":"import json\nfrom typing import Optional\nfrom pydantic import Field\nfrom pydantic_avro.base import AvroBase\n\nclass User(AvroBase):\n    id: int\n    name: str = Field(..., description=\"User's full name\")\n    email: Optional[str] = None\n    is_active: bool = True\n    creation_date: str = Field(..., avro_type=\"string\", description=\"Date of user creation in ISO format\")\n\n# Generate Avro schema\navro_schema = User.avro_schema()\nprint(json.dumps(avro_schema, indent=2))","lang":"python","description":"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)."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<0.10.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions up to 0.10.0"},{"fix":"Upgrade to `pydantic-avro` version `0.9.0` or later to ensure proper handling of list and tuple types in Avro schema generation.","message":"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.","severity":"breaking","affected_versions":"<0.9.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<0.9.3"},{"fix":"Migrate any custom type conversion logic to use the `avro_type` argument within `pydantic.Field` for cleaner and officially supported type overrides.","message":"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.","severity":"gotcha","affected_versions":"<0.8.0"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}