Converting YAML into Dataclass Values with dataclass-wizard
This article was automatically translated from Japanese by AI. Read the original Japanese version →
Table of Contents
No matter what language you're writing in—not just Python—there are times when you want to separate sets of static configuration values into a separate JSON or YAML file. Today I want to introduce dataclass-wizard, a handy library for marshaling JSON or YAML into dataclasses.
Background
When loading and working with YAML in Python, you would normally reach for PyYAML, where something like yaml.load returns a dict. To extract values from it, you end up specifying string keys like dict["key"].
That might be fine in small doses, but you don't get IDE or editor autocomplete for key names, and when you pass grouped values into a function as a dict, it becomes hard to tell inside that function which keys are even supposed to exist.
That's where dataclass-wizard comes in—it loads JSON or YAML and marshals it directly into dataclass instances.
Overview of Features
For example, suppose we prepare the following Python code and YAML file.
from dataclasses import dataclass, field from dataclass_wizard import YAMLWizard @dataclass class MyNestedClass: list_of_map: list[dict[int, str]] = field(default_factory=list) my_int: int = 14 @dataclass class MyClass(YAMLWizard): str_or_num: str | int = 42 nested: MyNestedClass | None = None @property def sum(self): return self.str_or_num + self.nested.my_int
str-or-num: 23 nested: ListOfMap: - 111: Hello, 222: World! - 333: 'Testing' 444: 123
With the code below, you can load the YAML file and instantiate a MyClass object.
obj = MyClass.from_yaml_file('my_file.yml') ob.str_or_num # => 23 obj.nested.my_int # => 14 obj.sum # => 37
The example above includes a str | int union type and default values, though in most cases you probably won't even need features that fancy.
Since MyClass is just a regular class, you can add whatever methods you like, such as the sum property. Also, because from_yaml_file returns a MyClass object, attribute completion and static type checking both work cleanly.
Auto-Generating Dataclasses
Even so, some people might find it tedious to write dataclasses by hand to match their YAML files. For those cases, dataclass-wizard also comes with a dataclass code generator.
The CLI Tool — Dataclass Wizard 0.22.3 documentation
This tool automatically generates Python dataclass code from a JSON file. What it does is immediately obvious, so reading the official docs should be plenty to get started.
However, it doesn't support YAML directly, so you'll need to convert YAML to JSON first. In that case, you can use a tool like yq as described in the article below—nothing complicated there either.
While it's a handy feature, the generated file has a few quirks, and once you have your dataclass code set up it isn't hard to keep the YAML and code in sync. Because of that, I'd recommend using the generator only when you already have a large YAML file and want to adopt dataclass-wizard now. When creating a new YAML file or adding a few keys to an existing one, it's better to update the dataclasses manually—especially since regenerating would clash with any custom methods or comments you've written.
Summary
That's a quick introduction to dataclass-wizard. There are actually plenty of libraries out there that convert dicts or files into dataclasses, but I like this one because the code generation feature makes it effortless to adopt. If you're only loading JSON or YAML config files, you don't need extreme performance or heavy validation features anyway. It's a simple and pleasant library to work with, so give it a try.

