dacite

Dacite is a small, focused Python library that solves one specific problem well: turning a plain dictionary — the kind you get back from a JSON payload, a database row, or a config file — into an instance of a @dataclass-decorated type. Instead of writing manual MyClass(**data) unpacking and hoping the shapes line up, you call dacite.from_dict(data_class=MyClass, data=raw_dict) and get back a fully-typed, validated instance, with nested dataclasses, Optional fields, Union types, generics, and collections all resolved recursively.

Unlike heavier validation libraries, dacite deliberately stays out of the validation business. It checks that the input matches the declared types (and raises clear, structured exceptions like WrongTypeError or MissingValueError when it doesn’t), but it does not offer field-level validators, coercion pipelines, or serialization back to dict/JSON. That narrow scope is the point: dacite is meant to be paired with a validation library like marshmallow or pydantic upstream, and used purely as the final step that lifts already-trusted data into typed Python objects your application code can work with confidently.

The library is commonly reached for in HTTP APIs (turning a Flask/FastAPI request body into a typed DTO), config loading (turning parsed YAML/TOML into a typed settings object), and any place a service boundary hands you “just a dict” that the rest of the codebase shouldn’t have to keep re-parsing. An LRU cache over type-hint resolution keeps repeated conversions fast even for large or deeply nested dataclass graphs.

What You Get

• A single public entry point, from_dict(data_class, data, config=None), that recursively converts a dict into a typed dataclass instance
• A Config object for customizing behavior per call: type_hooks, cast, strict, strict_unions_match, check_types, forward_references, and convert_key
• Structured, path-aware exceptions (WrongTypeError, MissingValueError, UnionMatchError, StrictUnionMatchError, UnexpectedDataError, ForwardReferenceError) that report exactly which field failed and why
• Full support for nested dataclasses, typing.Optional, typing.Union, generic dataclasses (including multi-generic and inherited generics), forward references, and standard collections (List, Dict, Tuple, sets)
• An LRU-cached type-hint resolution layer (set_cache_size/get_cache_size/clear_cache) so repeated conversions of the same dataclass shapes stay fast
• Zero runtime dependencies and a py.typed marker for full static-typing support in consuming code

Common Use Cases

• Converting a Flask/FastAPI/Django request body (already-parsed JSON) into a typed dataclass DTO before it reaches business logic
• Loading parsed YAML/TOML/JSON configuration files into a typed, IDE-autocompletable settings object
• Deserializing rows or documents fetched from a database or external API response into typed value objects
• Layering dacite on top of a validation library (marshmallow, pydantic-style validators) as the final step that lifts validated dict data into real Python types
• Rebuilding structured domain objects from cache/queue payloads (Redis, message queues) that were serialized as plain dicts

Under The Hood

Architecture The library is organized as a small set of single-purpose modules under dacite/: core.py holds the public from_dict entry point and the recursive _build_value/_build_value_for_union/_build_value_for_collection helpers that walk a dataclass’s fields and reconstruct values field-by-field; types.py centralizes all typing-introspection logic (union/optional/generic-collection detection, origin extraction); generics.py resolves concrete type hints for generic dataclasses, including multi-generic and inherited-generic cases; config.py defines the Config dataclass that threads behavior (type hooks, casting, strictness) through every recursive call; and exceptions.py defines a small hierarchy of DaciteFieldError subclasses that accumulate a dotted field path as errors bubble up through nested calls. The recursive design means the same _build_value function handles a top-level dataclass and every nested dataclass, union member, and collection item uniformly — there is no separate “deserializer per type” registry, keeping the core surface area small and predictable.

Tech Stack Dacite is pure Python with zero runtime dependencies, targeting Python 3.7+ and tested through 3.13 in CI. It relies entirely on the standard library — dataclasses, typing, and functools.lru_cache for its caching layer (cache.py) — with a small FrozenDict helper (frozen_dict.py) used to make forward-reference mappings hashable for the LRU cache. Packaging is handled with a classic setup.py, and development dependencies (pytest, pytest-benchmark, mypy, pylint, black) are declared under extras_require["dev"].

Code Quality The tests/ directory is organized into tests/core (behavioral tests per feature), tests/performance (a dedicated pytest-benchmark suite tracked across Python versions in CI), plus focused unit tests for the cache, dataclass helpers, and type-introspection utilities. CI (code_check.yaml) runs the full test suite with coverage across seven Python versions, then enforces black formatting, mypy type checking, and pylint linting on every push — a stricter quality bar than many libraries of comparable size. The project also tracks performance regressions explicitly via pytest-benchmark comparisons stored per Python version.

API Design The public API is intentionally minimal: one function (from_dict) and one configuration dataclass (Config) cover the entire feature set, which keeps the learning curve low despite the library supporting a comparatively wide range of typing constructs (unions, generics, forward references, casting, key conversion). Errors are structured and path-aware rather than generic exceptions, which makes debugging a failed conversion in a deeply nested dataclass tractable. The trade-off is that all configuration lives on one growing Config object rather than being composable per-field, which is simple to reach for but can make advanced per-field customization (e.g. different type_hooks scoped to specific nested dataclasses) less ergonomic than schema-based validation libraries.