{"id":2917,"library":"dataclasses-avroschema","title":"Dataclasses Avro Schema","description":"Dataclasses Avro Schema is a Python library that enables the generation of Avro schemas from Python dataclasses, Pydantic models, and Faust Records. It also provides functionalities for serializing and deserializing Python instances with these Avro schemas. The library is actively maintained, with frequent releases, and is currently at version 0.66.3.","status":"active","version":"0.66.3","language":"en","source_language":"en","source_url":"https://github.com/marcosschroh/dataclasses-avroschema","tags":["avro","dataclasses","serialization","deserialization","schema generation","pydantic","apache avro"],"install":[{"cmd":"pip install dataclasses-avroschema","lang":"bash","label":"Basic Installation"},{"cmd":"pip install 'dataclasses-avroschema[pydantic]' # For Pydantic integration","lang":"bash","label":"Pydantic Support"},{"cmd":"pip install 'dataclasses-avroschema[faust]' # For Faust integration","lang":"bash","label":"Faust Streaming Support"},{"cmd":"pip install 'dataclasses-avroschema[faker]' # For generating fake data","lang":"bash","label":"Fake Data Generation"},{"cmd":"pip install 'dataclasses-avroschema[cli]' # For CLI tools (dc-avro)","lang":"bash","label":"CLI Tools"}],"dependencies":[{"reason":"Requires Python 3.10 or higher.","package":"python","optional":false},{"reason":"Optional, for integrating with Pydantic models.","package":"pydantic","optional":true},{"reason":"Optional, for integrating with Faust Records.","package":"faust-streaming","optional":true},{"reason":"Optional, for generating fake data for models.","package":"faker","optional":true},{"reason":"Optional, for command-line interface tools.","package":"dc-avro","optional":true}],"imports":[{"symbol":"AvroModel","correct":"from dataclasses_avroschema import AvroModel"},{"note":"As of v0.14.0, the recommended way is to inherit from AvroModel, not use SchemaGenerator directly.","wrong":"from dataclasses_avroschema.schema_generator import SchemaGenerator","symbol":"AvroModel","correct":"from dataclasses_avroschema import AvroModel"},{"note":"Prior to v0.23.0, `types.Enum` was used. Now, standard Python `enum.Enum` (potentially mixed with `str`) is expected.","wrong":"favorite_colors: types.Enum = types.Enum([...])","symbol":"types.Enum","correct":"import enum; class MyEnum(enum.Enum): ..."}],"quickstart":{"code":"import dataclasses\nimport enum\nimport typing\nfrom dataclasses_avroschema import AvroModel\n\n\nclass FavoriteColor(enum.Enum):\n    BLUE = \"Blue\"\n    YELLOW = \"Yellow\"\n    GREEN = \"Green\"\n\n\n@dataclasses.dataclass\nclass User(AvroModel):\n    \"An User\"\n    name: str\n    age: int\n    pets: typing.List[str]\n    accounts: typing.Dict[str, int]\n    favorite_color: FavoriteColor\n    country: str = \"Argentina\"\n    address: typing.Optional[str] = None\n\n    class Meta:\n        namespace = \"User.v1\"\n        aliases = [\"user-v1\", \"super user\"]\n\n# Generate Avro schema\navro_schema = User.avro_schema()\nprint(\"Avro Schema:\")\nprint(avro_schema)\n\n# Create an instance\nuser_instance = User(\n    name=\"John Doe\",\n    age=30,\n    pets=[\"dog\", \"cat\"],\n    accounts={\"bank\": 1000, \"crypto\": 500},\n    favorite_color=FavoriteColor.BLUE,\n    country=\"USA\",\n    address=\"123 Main St\"\n)\n\n# Serialize to Avro binary\nserialized_data = user_instance.serialize()\nprint(\"\\nSerialized data (bytes):\", serialized_data)\n\n# Deserialize from Avro binary\ndeserialized_user = User.deserialize(serialized_data)\nprint(\"\\nDeserialized user:\", deserialized_user)","lang":"python","description":"This quickstart demonstrates how to define a dataclass with `AvroModel`, including enums, lists, and dictionaries. It shows how to generate the Avro schema, serialize a Python instance to Avro binary format, and then deserialize it back into a Python object."},"warnings":[{"fix":"Upgrade Python to 3.10 or newer.","message":"Python 3.9 support was dropped in version 0.66.0. Users on Python 3.9 or older must upgrade their Python environment to 3.10+.","severity":"breaking","affected_versions":">=0.66.0"},{"fix":"Refactor your dataclasses to inherit from `dataclasses_avroschema.AvroModel` and use `YourModel.avro_schema()` instead of `SchemaGenerator(YourModel).avro_schema()`.","message":"The primary API for schema generation changed from using `SchemaGenerator` to inheriting directly from `AvroModel` as of version 0.14.0. Old code using `SchemaGenerator` will no longer work as expected.","severity":"breaking","affected_versions":">=0.14.0"},{"fix":"Define a custom `enum.Enum` class for your enum fields. For string enums, consider `class MyEnum(str, enum.Enum): ...`.","message":"The `types.Enum` class was replaced with the expectation of using standard Python `enum.Enum` (potentially mixed with `str`) as of version 0.23.0. This requires creating custom enum classes instead of passing a list of symbols to `types.Enum`.","severity":"breaking","affected_versions":">=0.23.0"},{"fix":"Explicitly set `field: typing.Optional[str] = None` or for non-null defaults, ensure the default's type is compatible with the first type in the generated union.","message":"When defining optional fields (e.g., `typing.Optional[str] = None`), Avro unions require the default value's type to be the first in the union array. If `None` is the default, the schema will be `[\"null\", \"string\"]`. Ensure explicit `None` defaults for optional fields if you want `null` to be the first type in the union to avoid schema resolution issues.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}