from dataclasses import dataclass

Oct 13, 2025 by wbrum.org 34 views

Introduction

When working with complex data formats, such as YAML or JSON, it's not uncommon to encounter fields that can have different types of values. In this article, we'll explore how to handle such complex field types using the dataclass-wizard library in Python.

The Problem

Let's consider an example where we have a YAML config format defined and used by ESPHome, a tool for building firmware for home automation devices. In this format, a field like pin can have different types of values, such as an integer, a string (e.g., gpioxx), or an object.

Here's an example of how this might look in code:

### Example YAML Config Format

```yml
switch:
  - platform: gpio
    pin: GPIO14
    name: Relay #1
    id: relay1
  - platform: gpio
    pin:
      number: GPIO14
      inverted: true
    name: Relay #2
    id: relay2
  - platform: gpio
    pin: 15
    name: Relay #3
    id: relay3

The Code

We can represent this YAML config format using Python dataclasses with the dataclass-wizard library. Here's an example:

from __future__ import annotations

from dataclasses import dataclass

from dataclass_wizard import JSONWizard


@dataclass
class Data(JSONWizard):
    """
    Data dataclass

    """
    switch: list[Switch]


@dataclass
class Switch:
    """
    Switch dataclass

    """
    platform: str
    pin: str | Pin | int
    name: str
    id: str


@dataclass
class Pin:
    """
    Pin dataclass

    """
    number: str
    inverted: bool

The Issue

However, when we try to parse this YAML config format using the dataclass-wizard library, we encounter an issue:

### Error Message

```python
dataclass_wizard.errors.ParseError: Failure parsing field `pin` in class `Switch`. Expected a type [<class 'str'>, <class 'int'>], got dict.
  value: {'number': 'GPIO14', 'inverted': True}
  error: Object was not in any of Union types
  tag_key: '__tag__'
  json_object: '{"platform": "gpio", "pin": {"number": "GPIO14", "inverted": true}, "name": "Relay #2", "id": "relay2"}'

The Workaround

As a workaround, we can use a dict instead of the Pin dataclass and perform a second pass to parse the value of the pin field if it's a dictionary:

from __future__ import annotations

from dataclasses import dataclass

from dataclass_wizard import JSONWizard


@dataclass
class Data(JSONWizard):
    """
    Data dataclass

    """
    switch: list[Switch]


@dataclass
class Switch:
    """
    Switch dataclass

    """
    platform: str
    pin: str | dict | int
    name: str
    id: str

The Ideal Solution

However, it would be great if the dataclass-wizard library could handle this for us, at least to check the schema. This would make our code more robust and easier to maintain.

Conclusion

In this article, we've explored how to handle complex field types in dataclass-wizard. We've seen how to represent a YAML config format using Python dataclasses and how to encounter issues when parsing this format using the dataclass-wizard library. We've also discussed a workaround and an ideal solution to this problem.

Future Work

In the future, we'd like to see the dataclass-wizard library improve its support for complex field types. This would make it easier to work with complex data formats and reduce the need for workarounds like the one we've discussed.

Example Use Cases

Here are some example use cases for handling complex field types in dataclass-wizard:

YAML Config Format: We can use dataclass-wizard to parse a YAML config format that contains complex field types, such as a pin field that can be an integer, a string, or an object.
JSON Data: We can use dataclass-wizard to parse JSON data that contains complex field types, such as a pin field that can be an integer, a string, or an object.
API Responses: We can use dataclass-wizard to parse API responses that contain complex field types, such as a pin field that can be an integer, a string, or an object.

Code Snippets

Here are some code snippets that demonstrate how to handle complex field types in dataclass-wizard:

Example 1: We can use the dataclass-wizard library to parse a YAML config format that contains complex field types:

from future import annotations

from dataclasses import dataclass

from dataclass_wizard import JSONWizard

@dataclass class Data(JSONWizard): """ Data dataclass

"""
switch: list[Switch]

@dataclass class Switch: """ Switch dataclass

"""
platform: str
pin: str | Pin | int
name: str
id: str

@dataclass class Pin: """ Pin dataclass

"""
number: str
inverted: bool


*   **Example 2**: We can use the `dataclass-wizard` library to parse JSON data that contains complex field types:
    ```python
from __future__ import annotations

from dataclasses import dataclass

from dataclass_wizard import JSONWizard


@dataclass
class Data(JSONWizard):
    """
    Data dataclass

    """
    switch: list[Switch]


@dataclass
class Switch:
    """
    Switch dataclass

    """
    platform: str
    pin: str | Pin | int
    name: str
    id: str


@dataclass
class Pin:
    """
    Pin dataclass

    """
    number: str
    inverted: bool

Example 3: We can use the dataclass-wizard library to parse API responses that contain complex field types:

from future import annotations

from dataclasses import dataclass

from dataclass_wizard import JSONWizard

@dataclass class Data(JSONWizard): """ Data dataclass

"""
switch: list[Switch]

@dataclass class Switch: """ Switch dataclass

"""
platform: str
pin: str | Pin | int
name: str
id: str

@dataclass class Pin: """ Pin dataclass

"""
number: str
inverted: bool


**Commit Message**
-----------------

Here's an example commit message that summarizes the changes made in this article:

`feat: add support for complex field types in dataclass-wizard`

**API Documentation**
----------------------

Here's an example API documentation that describes the changes made in this article:

`dataclass-wizard`

*   **`Data` class**: Represents a dataclass that can be parsed from a YAML config format or JSON data.
*   **`Switch` class**: Represents a switch dataclass that contains complex field types, such as a `pin` field that can be an integer, a string, or an object.
*   **`Pin` class**: Represents a pin dataclass that contains complex field types, such as a `number` field that can be a string, and an `inverted` field that can be a boolean.

**Testing**
------------

Here are some example tests that demonstrate how to handle complex field types in dataclass-wizard:

*   **Test 1**: We can use the `unittest` library to test the `Data` class and ensure that it can be parsed from a YAML config format that contains complex field types:
    ```python
import unittest

from dataclass_wizard import JSONWizard


class TestData(unittest.TestCase):
    def test_parse_yaml(self):
        yaml_data = """
        switch:
          - platform: gpio
            pin: GPIO14
            name: Relay #1
            id: relay1
          - platform: gpio
            pin:
              number: GPIO14
              inverted: true
            name: Relay #2
            id: relay2
          - platform: gpio
            pin: 15
            name: Relay #3
            id: relay3
        """
        data = Data.from_yaml(yaml_data)
        self.assertEqual(data.switch[0].pin, "GPIO14")
        self.assertEqual(data.switch[1].pin, {"number": "GPIO14", "inverted": True})
        self.assertEqual(data.switch[2].pin, 15)

Test 2: We can use the unittest library to test the Switch class and ensure that it can be parsed from JSON data that contains complex field types:

import unittest

from dataclass_wizard import JSONWizard

$class TestSwitch(unittest.TestCase): def test_parse_json(self): json_data = """ { "switch": [ { "platform": "gpio", "pin": "GPIO14", "name": "Relay #1", "id": "relay1" }, { <br/> **Q&A: Handling Complex Field Types in Dataclass-Wizard**$

Q: What are complex field types in dataclass-wizard?

A: Complex field types in dataclass-wizard refer to fields that can have different types of values, such as an integer, a string, or an object.

Q: Why do I need to handle complex field types in dataclass-wizard?

A: You need to handle complex field types in dataclass-wizard because they are common in many data formats, such as YAML and JSON. If you don't handle them correctly, you may encounter errors when parsing your data.

Q: How do I handle complex field types in dataclass-wizard?

A: You can handle complex field types in dataclass-wizard by using the Union type to specify the possible types of values for a field. For example:

from dataclasses import dataclass
from dataclass_wizard import JSONWizard

@dataclass
class Switch(JSONWizard):
    platform: str
    pin: str | int | dict
    name: str
    id: str

Q: What is the `Union` type in dataclass-wizard?

A: The Union type in dataclass-wizard is a type that represents a union of two or more types. It is used to specify the possible types of values for a field.

Q: How do I use the `Union` type in dataclass-wizard?

A: You can use the Union type in dataclass-wizard by specifying the possible types of values for a field. For example:

from dataclasses import dataclass
from dataclass_wizard import JSONWizard
from typing import Union

@dataclass
class Switch(JSONWizard):
    platform: str
    pin: Union[str, int, dict]
    name: str
    id: str

Q: What are some common use cases for handling complex field types in dataclass-wizard?

A: Some common use cases for handling complex field types in dataclass-wizard include:

YAML Config Format: You can use dataclass-wizard to parse a YAML config format that contains complex field types, such as a pin field that can be an integer, a string, or an object.
JSON Data: You can use dataclass-wizard to parse JSON data that contains complex field types, such as a pin field that can be an integer, a string, or an object.
API Responses: You can use dataclass-wizard to parse API responses that contain complex field types, such as a pin field that can be an integer, a string, or an object.

Q: How do I test my code that handles complex field types in dataclass-wizard?

A: You can test your code that handles complex field types in dataclass-wizard by using the unittest library to write unit tests. For example:

import unittest
from dataclass_wizard import JSONWizard

class TestData(unittest.TestCase):
    def test_parse_yaml(self):
        yaml_data = """
        switch:
          - platform: gpio
            pin: GPIO14
            name: Relay #1
            id: relay1
          - platform: gpio
            pin:
              number: GPIO14
              inverted: true
            name: Relay #2
            id: relay2
          - platform: gpio
            pin: 15
            name: Relay #3
            id: relay3
        """
        data = Data.from_yaml(yaml_data)
        self.assertEqual(data.switch[0].pin, "GPIO14")
        self.assertEqual(data.switch[1].pin, {"number": "GPIO14", "inverted": True})
        self.assertEqual(data.switch[2].pin, 15)

Q: What are some best practices for handling complex field types in dataclass-wizard?

A: Some best practices for handling complex field types in dataclass-wizard include:

Use the Union type to specify the possible types of values for a field.
Use type hints to specify the type of a field.
Use the dataclass-wizard library to parse your data.
Write unit tests to ensure that your code works correctly.

Q: What are some common pitfalls to avoid when handling complex field types in dataclass-wizard?

A: Some common pitfalls to avoid when handling complex field types in dataclass-wizard include:

Not using the Union type to specify the possible types of values for a field.
Not using type hints to specify the type of a field.
Not using the dataclass-wizard library to parse your data.
Not writing unit tests to ensure that your code works correctly.