Overview

Requirements

The dataclass-mage library officially supports Python 3.9+

There are no core requirements outside of the Python standard library.

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 below section on Special Cases for additional info on the JSON load/dump process for special Python types.

  • Strings

    • str

    • bytes

    • bytearray

  • Numerics

    • int

    • float

    • Decimal

  • Booleans (bool)

  • Sequences (and their equivalents in the typing module)

    • list

    • deque

    • tuple

    • NamedTuple

  • Sets (and their equivalents in the typing module)

    • set

    • frozenset

  • Mappings (and their equivalents in the typing module)

    • dict

    • defaultdict

    • TypedDict

    • OrderedDict

  • Enum subclasses

  • UUID

  • date and time objects

    • datetime

    • date

    • time

    • timedelta

  • Special typing primitives from the typing module
  • Recently introduced Generic types

    • Annotated

    • Literal

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.

  • 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, 1

  • 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-mage[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.