Overview

Requirements

The dataclass-wizard library officially supports Python 3.9+

There are no core requirements outside of the Python standard library. That being said, this library does utilize a few conditional dependencies:

• typing-extensions - this is a lightweight and highly useful library that backports the most recently added features to the typing module. For more info, check out the Py Compatibility section.

Advantages

• Minimal setup required. In most cases, all you need is a dataclass that sub-classes from JSONWizard.

• Speed. It is up to 25 times faster than libraries such as dataclasses-json that use marshmallow, and about 60 x faster than libraries such as jsons which don’t seem to handle dataclasses as well as you’d expect.

• Adds the ability to use field properties (with default values) in dataclasses.

• Automatic key transform to/from JSON (ex. camel to snake). Custom key mappings also supported.

• Automatic type conversion when loading from JSON or a dict object. For instance, strings are converted to boolean if a type annotation is List[bool].

• Built-in support for standard Python collections, as well as most Generics from the typing module. Other commonly used types such as Enums, defaultdict, and date and time objects such as datetime are also natively supported.

• Latest Python features such as parameterized standard collections can be used.

• Ability to construct ad-hoc dataclass schemas using JSON input (either as a file or string) using the included wiz-cli utility.

Supported Types

Tip

See the section on Special Cases for additional information on how Dataclass Wizard handles JSON load/dump for special Python types.

Dataclass Wizard supports a wide range of Python types, making it easier to work with complex data structures. This includes built-in types, collections, and more advanced type annotations. The following types are supported:

• Basic Types:

  • str

  • int

  • float

  • bool

  • None (docs)

• Binary Types:

  • bytes (docs)

  • bytearray (docs)

• Decimal Type:

  • Decimal (docs)

• Pathlib:

  • Path (docs)

• Typed Collections: Typed collections are supported for structured data, including:

  • TypedDict (docs)

  • NamedTuple (docs)

  • namedtuple (docs)

• ABC Containers (docs):

  • Sequence (docs) – instantiated as tuple

  • MutableSequence (docs) – mapped to list

  • Collection (docs) – instantiated as list

• Type Annotations and Qualifiers:

  • Required, NotRequired, ReadOnly (docs)

  • Annotated (docs)

  • Literal (docs)

  • LiteralString (docs)

  • Union (docs) – Also supports using dataclasses.

  • Optional (docs)

  • Any (docs)

• Enum Types:

  • Enum (docs)

  • StrEnum (docs)

  • IntEnum (docs)

• Sets:

  • set (docs)

  • frozenset (docs)

• Mappings:

  • dict (docs)

  • defaultdict (docs)

  • OrderedDict (docs)

• Sequences:

  • list (docs)

  • deque (docs)

  • tuple (docs)

• UUID:

  • UUID (docs)

• Date and Time:

  • datetime (docs)

  • date (docs)

  • time (docs)

  • timedelta (docs)

• Nested Dataclasses: Nested dataclasses are supported, allowing you to serialize and deserialize nested data structures.

Starting with v0.34.0, recursive and self-referential dataclasses are supported out of the box when the v1 option is enabled in the Meta setting (i.e., v1 = True). This removes the need for custom settings like recursive_classes and expands type support beyond what is available in v0.x.

For more advanced functionality and additional types, enabling v1 is recommended. It forms the basis for more complex cases and will evolve into the standard model for Dataclass Wizard.

For more info, see the Field Guide to V1 Opt-in.

Special Cases

Note

With most annotated Python types, it is clear and unambiguous how they are to be loaded from JSON, or dumped when they are serialized back to JSON.

However, here a few special cases that are worth going over.

• str - Converts inputs to strings. If already a string, it remains unchanged. Non-strings are converted to their string representation.

  By default in v1, None is converted using str(None) (i.e. 'None') for str fields, and preserved as None for Optional[str] fields. Set Meta.v1_coerce_none_to_empty_str = True to coerce None to '' instead.

  Examples: 123 → '123', None → 'None' (or '' with opt-in)

• bool - JSON values that appear as strings or integers will be de-serialized to a bool using a case-insensitive search that matches against the following “truthy” values:

  TRUE, T, YES, Y, ON, 1

• int - Converts valid inputs to integers:

  • String representations of integers (e.g., "123").

  • Floats or float strings with or without fractional parts (e.g., 123.4 or "123.4"), rounded to the nearest integer.

  • Empty strings or None return the default value of 0.

  Warning

  Starting in v1.0, floats or float strings with fractional parts (e.g., 123.4 or "123.4") will raise an error instead of being rounded.

• Enum - JSON values (ideally strings) are de-serialized to Enum subclasses via the value attribute, and are serialized back to JSON using the same value attribute.

• UUID types are de-serialized from JSON strings using the constructor method – i.e. UUID(string), and by default are serialized back to JSON using the hex attribute – i.e. my_uuid.hex.

• Decimal types are de-serialized using the Decimal(str(o)) syntax – or via an annotated subclass of Decimal – and are serialized via the builtin str() function.

• NamedTuple sub-types are de-serialized from a list, tuple, or any iterable type into the annotated sub-type. They are serialized back as the the annotated NamedTuple sub-type; this is mainly because named tuples are essentially just tuples, so they are inherently JSON serializable to begin with.

• For date, time, and datetime types, string values are de-serialized using the builtin fromisoformat() method; for datetime and time types, a suffix of “Z” appearing in the string is first replaced with “+00:00”, which represents UTC time. JSON values for datetime and date annotated types appearing as numbers will be de-serialized using the builtin fromtimestamp() method.

  All these types are serialized back to JSON using the builtin isoformat() method. For datetime and time types, there is one noteworthy addition: the suffix “+00:00” is replaced with “Z”, which is a common abbreviation for UTC time.

• For timedelta types, the values to de-serialize can either be strings or numbers, so we check the type explicitly. If the value is a string, we first ensure it’s in a numeric form like ‘1.23’, and if so convert it to a float value in seconds; otherwise, we convert values like ‘01:45’ or ‘3hr12m56s’ via the pytimeparse module, which is also available as an extra via pip install dataclass-wizard[timedelta]. Lastly, any numeric values are assumed to be in seconds and are used as is.

  All timedelta values are serialized back to JSON using the builtin str() method, so for example timedelta(seconds=3) will be serialized as “0:00:03”.

• set, frozenset, and deque types will be de-serialized using their annotated base types, and serialized as list’s.

• Commonly used dict sub-types (such as defaultdict) will be de-serialized from JSON objects using the annotated base type, and serialized back as plain dict objects.

Extending Supported Types

If a type is not supported out of the box, you can extend Dataclass Wizard using custom type hooks.

Type hooks allow you to define how a type is loaded and dumped, without modifying the type itself.

See Type Hooks for more information.