{"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":"python","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,"search_vec":"'0.10.0':47 'activ':36 'allow':23 'avro':3,6,17,31,49 'class':15 'convert':13 'data':32,52 'design':11 'format':33 'frequent':39 'integr':26 'kafka':54 'latest':43 'librari':10 'maintain':37 'model':29 'pydant':2,5,14,28,48 'pydantic-avro':1,4 'python':9 'schema':18,50 'seamless':25 'serial':51 'stabl':44 'updat':40 'valid':53 'versa':22 'version':45 'vice':21 'vice-versa':20","created_at":"2026-04-12T03:44:37.924341+00:00","updated_at":"2026-04-16T18:23:48.110362+00:00","problems":[{"fix":"Simplify the Pydantic model's complex types, for example, by breaking down deeply nested unions or tuples into simpler, directly supported types, or by ensuring enum values are strings if an enum is involved. Upgrading `pydantic-avro` to the latest version might also resolve issues with previously unsupported complex types, as fixes have been implemented for some of these cases.","cause":"This error often occurs when pydantic-avro encounters complex Pydantic types, particularly nested lists, tuples, or unions, that it cannot properly convert into a corresponding Avro schema type, leading to an unexpected `None` value being processed.","error":"AttributeError: 'NoneType' object has no attribute 'get' (or similar AttributeError within pydantic_avro/base.py during avro_schema generation)"},{"fix":"Modify the Avro schema to ensure unique names for fields and nested records, or manually adjust the generated Pydantic model to resolve the naming collision. A proposed fix is to include parent names in the generated class naming scheme to ensure uniqueness.","cause":"This validation error arises when `avsc_to_pydantic` generates Pydantic models from an Avro schema where a field and a nested record (class) are given the same name. Pydantic then struggles to correctly parse the input when instantiating the generated model, expecting `None` due to the naming conflict.","error":"pydantic_core._pydantic_core.ValidationError: 1 validation error for [model_name] [field_name] Input should be None [type=none_required, input_value=[...], input_type=dict]"},{"fix":"Install the library using pip: `pip install pydantic-avro`.","cause":"The `pydantic-avro` library has not been installed in your current Python environment, or the environment where the code is being run does not have access to the installed package.","error":"ModuleNotFoundError: No module named 'pydantic_avro'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.10.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/godatadriven/pydantic-avro","docs":null,"changelog":null,"pypi":"https://pypi.org/project/pydantic-avro/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-29","next_check":"2026-07-28","install_tag":null}}