# 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)