djangorestframework-dataclasses

djangorestframework-dataclasses provides a DataclassSerializer for Django REST Framework that mirrors the ergonomics of ModelSerializer, but for plain Python dataclasses instead of Django models. Point it at a dataclass with type annotations and it derives serializer fields automatically, covering primitives, dates, decimals, UUIDs, enums, typing.Literal, typing.Union (including PEP 604 pipe unions), nested dataclasses, and Django model relations.

The library goes deep on typing introspection, supporting both immediate and postponed annotation evaluation, PEP 585 generic collections, and constrained/bound type variables, so the generated fields track the real shape of the data rather than a hand-maintained duplicate. It ships default create()/update() implementations, an empty-sentinel mechanism to distinguish unset fields from default values during partial updates, and extra field types (EnumField, UnionField, IterableField, MappingField) for cases DRF doesn’t cover out of the box.

What You Get

• DataclassSerializer - a drop-in serializer that reads a dataclass’s type annotations and metadata to auto-generate the equivalent DRF fields, including required/optional and nullable flags derived from defaults and typing.Optional.
• Deep typing support - correct field generation for typing.Literal, typing.Union / PEP 604 unions, PEP 585 generics (list[int], dict[str, int]), enums, and type variables with bounds or constraints.
• Automatic nesting - dataclasses nested inside other dataclasses (directly, in lists, or in dicts) are serialized with an auto-generated nested DataclassSerializer, several layers deep if needed.
• Model relation fields - dataclass fields typed as a Django Model automatically become PrimaryKeyRelatedField (or HyperlinkedRelatedField via HyperlinkedDataclassSerializer).
• Custom field types - EnumField, UnionField (with discriminator-based polymorphic serialization), IterableField, and MappingField fill gaps in DRF’s built-in field set.
• Partial-update correctness - an explicit empty sentinel distinguishes ‘field not provided’ from ‘field set to its default’, so partial updates on nested and top-level dataclasses behave predictably.

Common Use Cases

• API responses from non-model data - exposing computed or in-memory dataclass structures (e.g. aggregation results, service-layer DTOs) through a DRF endpoint without hand-writing a serializer field by field.
• Typed request/response schemas - defining an API contract as a dataclass and letting the serializer, and downstream tools like drf-spectacular, derive validation and OpenAPI schemas from a single source of truth.
• Polymorphic payloads - modeling a field that can hold one of several dataclass shapes (a union type) and serializing it with an explicit discriminator field for the client to branch on.
• Mixed model/dataclass domains - services that combine Django ORM models and plain dataclasses in the same response, using relational fields for the model parts and generated fields for the rest.

Under The Hood

Architecture The library is organized around a single central serializer class, DataclassSerializer (rest_framework_dataclasses/serializers.py, ~760 lines), which subclasses DRF’s Serializer and mirrors ModelSerializer’s field-building contract: a dispatch of build_standard_field / build_relational_field / build_dataclass_field / build_union_field / build_enum_field / build_literal_field / build_composite_field methods, each documented as stable override points. Field generation itself is decoupled into field_utils.py (dataclass field introspection, metadata extraction) and typing_utils.py (runtime type-hint introspection abstracted behind helpers like get_origin/get_args, since Python’s typing module offers no stable public API for this). A DataclassListSerializer and HyperlinkedDataclassSerializer extend the base class for list endpoints and hyperlinked relations respectively. Partial updates and create/update are handled via an empty sentinel value threaded through validated_data and stripped by a recursive _strip_empty_sentinels helper, letting the serializer distinguish an omitted field from one explicitly set to its default across arbitrarily nested dataclasses.

Tech Stack Pure Python, distributed via a standard setuptools/pyproject.toml build with no compiled extensions. Runtime dependencies are just Django (>=2.0) and Django REST Framework (>=3.9); typing_extensions is pulled in only for Python <3.8. The dev/test extras add django-stubs, djangorestframework-stubs and mypy for static typing, plus tox and coverage for the test matrix. CI (GitHub Actions) runs the test suite across Python 3.8 through 3.14-dev via tox, uploads coverage to Codecov, and runs a separate mypy job — the package ships a py.typed marker and is written to be fully type-checked against the DRF and Django stub packages.

Code Quality The tests/ directory mirrors the source layout with dedicated suites for field generation, field behavior, functional round-trips, typing-utils edge cases, and regression tests tied to specific reported issues (test_issues.py), plus a Python-3.12-specific suite. Coverage is measured with branch coverage enabled and scoped to the package source. The codebase uses from __future__ import annotations throughout, extensive Generic/TypeVar-based typing on the public serializer classes, and mypy is enforced in CI as a separate job rather than a soft check, giving reasonable confidence that the type surface is accurate for consumers who also type-check their code.

What Makes It Unique Most DRF serializer helpers exist for Django models; this library instead targets the general case of any type-annotated dataclass, and invests specifically in getting Python’s typing introspection right — including PEP 604 unions, PEP 585 generics, both immediate and postponed (string) annotation evaluation, and bounded/constrained TypeVars. The UnionField’s discriminator-based polymorphic serialization, and the empty-sentinel approach to correctly distinguishing ‘unset’ from ‘default’ during partial updates on nested structures, are both solutions to problems that are easy to get subtly wrong with a hand-rolled approach.