Wizard Mixin Classes¶

In addition to the JSONWizard, here a few extra Wizard Mixin classes that might prove to be quite convenient to use.

`EnvWizard`¶

Effortlessly load environment variables and .env files into typed schemas. Supports secrets via files (file names as keys).

Automatically applies the @dataclass decorator and supports type hinting with string-to-type conversion. Requires subclass instantiation to function.

For a detailed example and advanced features:

📖 Full Documentation

`JSONPyWizard`¶

A subclass of JSONWizard that disables the default key transformation behavior, ensuring that keys are not transformed during JSON serialization (e.g., no camelCase transformation).

class JSONPyWizard(JSONWizard):
    """Helper for JSONWizard that ensures dumping to JSON keeps keys as-is."""

    def __init_subclass__(cls, str=True, debug=False):
        """Bind child class to DumpMeta with no key transformation."""
        DumpMeta(key_transform='NONE').bind_to(cls)
        super().__init_subclass__(str, debug)

Use Case¶

Use JSONPyWizard when you want to prevent the automatic camelCase conversion of dictionary keys during serialization, keeping them in their original snake_case format.

`JSONListWizard`¶

The JSON List Wizard is a Mixin class that extends JSONWizard to return Container - instead of list - objects.

Note

Container objects are simply convenience wrappers around a collection of dataclass instances. For all intents and purposes, they behave exactly the same as list objects, with some added helper methods:

prettify() - Convert the list of instances to a prettified JSON string.

to_json() - Convert the list of instances to a JSON string.

to_json_file() - Serialize the list of instances and write it to a JSON file.

Simple example of usage below:

from __future__ import annotations  # Note: In 3.10+, this import can be removed

from dataclasses import dataclass

from dataclass_wizard import JSONListWizard, Container


@dataclass
class Outer(JSONListWizard):
    my_str: str | None
    inner: list[Inner]


@dataclass
class Inner:
    other_str: str


my_list = [
    {"my_str": 20,
     "inner": [{"otherStr": "testing 123"}]},
    {"my_str": "hello",
     "inner": [{"otherStr": "world"}]},
]

# De-serialize the JSON string into a list of `MyClass` objects
c = Outer.from_list(my_list)

# Container is just a sub-class of list
assert isinstance(c, list)
assert type(c) == Container

print(c)
# [Outer(my_str='20', inner=[Inner(other_str='testing 123')]),
#  Outer(my_str='hello', inner=[Inner(other_str='world')])]

print(c.prettify())
# [
#   {
#     "myStr": "20",
#   ...

# serializes the list of dataclass instances to a JSON file
c.to_json_file('my_file.json')

`JSONFileWizard`¶

The JSON File Wizard is a minimalist Mixin class that makes it easier to interact with JSON files, as shown below.

It comes with only two added methods: from_json_file() and to_json_file().

Note

This can be paired with the JSONWizard Mixin class for more complete extensibility.

from __future__ import annotations  # Note: In 3.10+, this import can be removed

from dataclasses import dataclass

from dataclass_wizard import JSONFileWizard


@dataclass
class MyClass(JSONFileWizard):
    my_str: str | None
    my_int: int = 14


c1 = MyClass(my_str='Hello, world!')
print(c1)

# Serializes the dataclass instance to a JSON file
c1.to_json_file('my_file.json')

# contents of my_file.json:
#> {"myStr": "Hello, world!", "myInt": 14}

c2 = MyClass.from_json_file('my_file.json')

# assert that data is the same
assert c1 == c2

`YAMLWizard`¶

The YAML Wizard leverages the PyYAML library – which can be installed as an extra via pip install dataclass-wizard[yaml] – to easily convert dataclass instances to/from YAML.

Note

The default key transform used in the YAML dump process is lisp-case, however this can easily be customized without the need to sub-class from JSONWizard, as shown below.

>>> @dataclass
>>> class MyClass(YAMLWizard, key_transform='CAMEL'):
>>>     ...

A (mostly) complete example of using the YAMLWizard is as follows:

from __future__ import annotations  # Note: In 3.10+, this import can be removed

from dataclasses import dataclass, field

from dataclass_wizard import YAMLWizard


@dataclass
class MyClass(YAMLWizard):
    str_or_num: str | int = 42
    nested: MyNestedClass | None = None


@dataclass
class MyNestedClass:
    list_of_map: list[dict[int, str]] = field(default_factory=list)
    my_int: int = 14


c1 = MyClass.from_yaml("""
str-or-num: 23
nested:
    ListOfMap:
        - 111: Hello,
          222: World!
        - 333: 'Testing'
          444: 123
""")

# serialize the dataclass instance to a YAML file
c1.to_yaml_file('my_file.yaml')

# sample contents of `my_file.yaml` would be:
#> nested:
#>   list-of-map:
#>   - 111: Hello,
#>   ...

# now read it back...
c2 = MyClass.from_yaml_file('my_file.yaml')

# assert we get back the same data
assert c1 == c2

# let's create a list of dataclass instances
objects = [MyClass(), c2, MyClass(3, nested=MyNestedClass())]

# and now, serialize them all...
yaml_string = MyClass.list_to_yaml(objects)

print(yaml_string)
# - nested: null
#   str-or-num: 42
# - nested:
#     list-of-map:
#   ...

`TOMLWizard`¶

Added in v0.28.0

The TOMLWizard was introduced in version 0.28.0.

The TOML Wizard provides an easy, convenient interface for converting dataclass instances to/from TOML. This mixin enables simple loading, saving, and flexible serialization of TOML data, including support for custom key casing transforms.

Note

By default, NO key transform is used in the TOML dump process. This means that a snake_case field name in Python is saved as snake_case in TOML. However, this can be customized without subclassing from JSONWizard, as below.

>>> @dataclass
>>> class MyClass(TOMLWizard, key_transform='CAMEL'):
>>>     ...

Dependencies¶

For reading TOML, TOMLWizard uses Tomli for Python 3.9 and 3.10, and the built-in tomllib for Python 3.11+.
For writing TOML, Tomli-W is used across all Python versions.

Example¶

A (mostly) complete example of using the TOMLWizard is as follows:

from dataclasses import dataclass, field
from dataclass_wizard import TOMLWizard


@dataclass
class InnerData:
    my_float: float
    my_list: list[str] = field(default_factory=list)


@dataclass
class MyData(TOMLWizard):
    my_str: str
    my_dict: dict[str, int] = field(default_factory=dict)
    inner_data: InnerData = field(default_factory=lambda: InnerData(3.14, ["hello", "world"]))


# TOML input string with nested tables and lists
toml_string = """
my_str = 'example'
[my_dict]
key1 = 1
key2 = '2'

[inner_data]
my_float = 2.718
my_list = ['apple', 'banana', 'cherry']
"""

# Load from TOML string
data = MyData.from_toml(toml_string)

# Sample output of `data` after loading from TOML:
#> my_str = 'example'
#> my_dict = {'key1': 1, 'key2': 2}
#> inner_data = InnerData(my_float=2.718, my_list=['apple', 'banana', 'cherry'])

# Save to TOML file
data.to_toml_file('data.toml')

# Now read it back from the TOML file
new_data = MyData.from_toml_file('data.toml')

# Assert we get back the same data
assert data == new_data, "Data read from TOML file does not match the original."

# Create a list of dataclass instances
data_list = [data, new_data, MyData("another_example", {"key3": 3}, InnerData(1.618, ["one", "two"]))]

# Serialize the list to a TOML string
toml_output = MyData.list_to_toml(data_list, header='testing')

print(toml_output)
# [[testing]]
# my_str = "example"
#
# [testing.my_dict]
# key1 = 1
# key2 = 2
#
# [testing.inner_data]
# my_float = 2.718
# my_list = [
#     "apple",
#     "banana",
#     "cherry",
# ]
# ...

This approach provides a straightforward way to handle TOML data within Python dataclasses.

Methods¶

from_toml(cls, string_or_stream, *, decoder=None, header='items', parse_float=float)¶

Parses a TOML string or stream and converts it into an instance (or list of instances) of the dataclass. If header is provided and the corresponding value in the parsed data is a list, the return type is List[T].

Example usage:

>>> data_str = '''my_str = "test"\n[inner]\nmy_float = 1.2'''
>>> obj = MyClass.from_toml(data_str)

from_toml_file(cls, file, *, decoder=None, header='items', parse_float=float)¶

Reads the contents of a TOML file and converts them into an instance (or list of instances) of the dataclass. Similar to from_toml(), it can return a list if header is specified and points to a list in the TOML data.

Example usage:

>>> obj = MyClass.from_toml_file('config.toml')

to_toml(self, /, *encoder_args, encoder=None, multiline_strings=False, indent=4)¶

Converts a dataclass instance to a TOML string. Optional parameters include multiline_strings for enabling/disabling multiline formatting of strings and indent for setting the indentation level.

Example usage:

>>> toml_str = obj.to_toml()

to_toml_file(self, file, mode='wb', encoder=None, multiline_strings=False, indent=4)¶

Serializes a dataclass instance and writes it to a TOML file. By default, opens the file in “write binary” mode.

Example usage:

>>> obj.to_toml_file('output.toml')

list_to_toml(cls, instances, header='items', encoder=None, **encoder_kwargs)¶

Serializes a list of dataclass instances into a TOML string, grouped under a specified header.

Example usage:

>>> obj_list = [MyClass(), MyClass(my_str="example")]
>>> toml_str = MyClass.list_to_toml(obj_list)

Wizard Mixin Classes¶

`EnvWizard`¶

`JSONPyWizard`¶

Use Case¶

`JSONListWizard`¶

`JSONFileWizard`¶

`YAMLWizard`¶

`TOMLWizard`¶

Dependencies¶

Example¶

Methods¶

Dataclass Wizard

Useful Links

Table of Contents

Related Topics

API Reference

This Page

Wizard Mixin Classes¶

EnvWizard¶

JSONPyWizard¶

Use Case¶

JSONListWizard¶

JSONFileWizard¶

YAMLWizard¶

TOMLWizard¶

Dependencies¶

Example¶

Methods¶

`EnvWizard`¶

`JSONPyWizard`¶

`JSONListWizard`¶

`JSONFileWizard`¶

`YAMLWizard`¶

`TOMLWizard`¶