Dataclasses Avro Schema

Warnings

• breaking 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+.
  Fix: Upgrade Python to 3.10 or newer.
• breaking 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.
  Fix: Refactor your dataclasses to inherit from `dataclasses_avroschema.AvroModel` and use `YourModel.avro_schema()` instead of `SchemaGenerator(YourModel).avro_schema()`.
• breaking 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`.
  Fix: Define a custom `enum.Enum` class for your enum fields. For string enums, consider `class MyEnum(str, enum.Enum): ...`.
• gotcha 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.
  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.

Install

• pip install dataclasses-avroschema Basic Installation
• pip install 'dataclasses-avroschema[pydantic]' # For Pydantic integration Pydantic Support
• pip install 'dataclasses-avroschema[faust]' # For Faust integration Faust Streaming Support
• pip install 'dataclasses-avroschema[faker]' # For generating fake data Fake Data Generation
• pip install 'dataclasses-avroschema[cli]' # For CLI tools (dc-avro) CLI Tools

Imports

• AvroModel

  from dataclasses_avroschema import AvroModel

• AvroModel

  from dataclasses_avroschema import AvroModel

  As of v0.14.0, the recommended way is to inherit from AvroModel, not use SchemaGenerator directly.
• types.Enum

  import enum; class MyEnum(enum.Enum): ...

  Prior to v0.23.0, `types.Enum` was used. Now, standard Python `enum.Enum` (potentially mixed with `str`) is expected.

Quickstart

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.

import dataclasses
import enum
import typing
from dataclasses_avroschema import AvroModel


class FavoriteColor(enum.Enum):
    BLUE = "Blue"
    YELLOW = "Yellow"
    GREEN = "Green"


@dataclasses.dataclass
class User(AvroModel):
    "An User"
    name: str
    age: int
    pets: typing.List[str]
    accounts: typing.Dict[str, int]
    favorite_color: FavoriteColor
    country: str = "Argentina"
    address: typing.Optional[str] = None

    class Meta:
        namespace = "User.v1"
        aliases = ["user-v1", "super user"]

# Generate Avro schema
avro_schema = User.avro_schema()
print("Avro Schema:")
print(avro_schema)

# Create an instance
user_instance = User(
    name="John Doe",
    age=30,
    pets=["dog", "cat"],
    accounts={"bank": 1000, "crypto": 500},
    favorite_color=FavoriteColor.BLUE,
    country="USA",
    address="123 Main St"
)

# Serialize to Avro binary
serialized_data = user_instance.serialize()
print("\nSerialized data (bytes):", serialized_data)

# Deserialize from Avro binary
deserialized_user = User.deserialize(serialized_data)
print("\nDeserialized user:", deserialized_user)