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 isList[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 asdatetime
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:
Decimal Type:
Decimal
(docs)
Pathlib:
Path
(docs)
Typed Collections: Typed collections are supported for structured data, including:
ABC Containers (docs):
Type Annotations and Qualifiers:
Enum Types:
Sets:
Mappings:
Sequences:
UUID:
UUID
(docs)
Date and Time:
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
- Effortlessly converts inputs to strings. If already a string, it remains unchanged. Non-strings are converted to their string representation, andNone
becomes an empty string.Examples:
123
→'123'
,None
→''
bool
- JSON values that appear as strings or integers will be de-serialized to abool
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 of0
.
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 toEnum
subclasses via thevalue
attribute, and are serialized back to JSON using the samevalue
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 thehex
attribute – i.e.my_uuid.hex
.Decimal
types are de-serialized using theDecimal(str(o))
syntax – or via an annotated subclass of Decimal – and are serialized via the builtinstr()
function.NamedTuple
sub-types are de-serialized from alist
,tuple
, or any iterable type into the annotated sub-type. They are serialized back as the the annotatedNamedTuple
sub-type; this is mainly because named tuples are essentially just tuples, so they are inherently JSON serializable to begin with.For
date
,time
, anddatetime
types, string values are de-serialized using the builtinfromisoformat()
method; fordatetime
andtime
types, a suffix of “Z” appearing in the string is first replaced with “+00:00”, which represents UTC time. JSON values fordatetime
anddate
annotated types appearing as numbers will be de-serialized using the builtinfromtimestamp()
method.All these types are serialized back to JSON using the builtin
isoformat()
method. Fordatetime
andtime
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 viapip 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 builtinstr()
method, so for exampletimedelta(seconds=3)
will be serialized as “0:00:03”.set
,frozenset
, anddeque
types will be de-serialized using their annotated base types, and serialized aslist
’s.Commonly used
dict
sub-types (such asdefaultdict
) will be de-serialized from JSON objects using the annotated base type, and serialized back as plaindict
objects.