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