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.

GitHub - rnag/dataclass-wizard: A simple, yet elegant, set of wizarding tools for interacting with Python dataclasses.Simple, elegant, wizarding tools for interacting with Python's dataclasses. - rnag/dataclass-wizardGitHub · github.com

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 documentationdataclass-wizard.readthedocs.io

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.

Converting Between JSON and YAML with yq - Qiita概要 yq コマンドを用いて JSON ⇔ YAML の相互変換を行う。 Install 最初に Mac 環境で yqをインストールする。 % brew install yq 環境 環境としては、カレントディレクトリに 以下の comman…Qiita · qiita.com

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.