Description

.. image:: https://raw.githubusercontent.com/rnag/dataclass-wizard/main/images/logo.png :alt: Dataclass Wizard logo :width: 160px :align: center **Simple, elegant wizarding tools for Python’s** ``dataclasses``. 📘 Docs → `dcw.ritviknag.com`_ .. image:: https://github.com/rnag/dataclass-wizard/actions/workflows/dev.yml/badge.svg :target: https://github.com/rnag/dataclass-wizard/actions/workflows/dev.yml :alt: CI Status .. image:: https://img.shields.io/pypi/v/dataclass-wizard.svg :target: https://pypi.org/project/dataclass-wizard/ :alt: PyPI Version .. image:: https://img.shields.io/pypi/pyversions/dataclass-wizard.svg :target: https://pypi.org/project/dataclass-wizard/ :alt: Supported Python Versions .. image:: https://static.pepy.tech/badge/dataclass-wizard :target: https://pepy.tech/project/dataclass-wizard :alt: Downloads per Month **Dataclass Wizard** is a fast, well-tested serialization library for Python dataclasses. ------------------- **Behold, the power of Dataclass Wizard**:: >>> from __future__ import annotations >>> from dataclasses import field >>> from dataclass_wizard import DataclassWizard ... >>> class MyClass(DataclassWizard, load_case='AUTO', dump_case='CAMEL'): ... my_str: str | None ... is_active_tuple: tuple[bool, ...] ... list_of_int: list[int] = field(default_factory=list) ... >>> MyClass.from_json( ... '{"my_str": 20, "ListOfInt": ["1", "2", 3], "isActiveTuple": [true, false, 1]}' ... ) MyClass(my_str='20', is_active_tuple=(True, False, True), list_of_int=[1, 2, 3]) .. note:: The example above demonstrates automatic type coercion, key casing transforms, and support for nested dataclasses. ``DataclassWizard`` also auto-applies ``@dataclass`` to subclasses. .. tip:: A new **v1 engine** is available as an opt-in, offering explicit environment precedence, nested dataclass support, and improved performance. ``EnvWizard`` v1 adds field-level configuration on top of these improvements. See the `Field Guide to V1 Opt-in`_ and the `hands-on quickstart`_ for details. .. contents:: Contents :depth: 1 :local: :backlinks: none Why Dataclass Wizard? --------------------- Dataclass Wizard helps you turn Python dataclasses into robust, high-performance serialization schemas with minimal effort. - 🚀 Fast — code-generated loaders and dumpers - 🪶 Lightweight — pure Python, minimal dependencies - 🧠 Typed — powered by Python type hints - 🧙 Flexible — JSON, YAML, TOML, and environment variables - 🧪 Reliable — battle-tested with extensive test coverage Quick Examples -------------- .. rubric:: JSON De/Serialization .. code-block:: python3 from dataclasses import dataclass from dataclass_wizard import JSONWizard @dataclass class Data(JSONWizard): value: int data = Data.from_dict({"value": "123"}) assert data.value == 123 print(data.to_json()) .. rubric:: Environment Variables .. code-block:: python3 import os from dataclass_wizard import EnvWizard os.environ['DEBUG'] = 'true' class Config(EnvWizard): debug: bool cfg = Config() assert cfg.debug is True .. rubric:: EnvWizard v1 (Opt-in) .. code-block:: python3 import os from dataclass_wizard.v1 import EnvWizard, Env os.environ['DEBUG_MODE'] = 'true' class Config(EnvWizard): debug: bool = Env('DEBUG_MODE') cfg = Config() assert cfg.debug is True .. tip:: EnvWizard v1 introduces explicit environment precedence and nested dataclass support. See `Field Guide to V1 Opt-in`_ for full details. Installation ------------ Install from `PyPI`_: .. code-block:: console pip install dataclass-wizard Or via `conda-forge`_: .. code-block:: console conda install -c conda-forge dataclass-wizard Dataclass Wizard supports **Python 3.9+**. .. note:: Python 3.6–3.8 users should install the last supported release, ``dataclass-wizard==0.26.1``. See `PyPI`_ for historical versions and the `Changelog`_ for details. .. _PyPI: https://pypi.org/project/dataclass-wizard/ .. _conda-forge: https://conda-forge.org/ .. _Changelog: https://dcw.ritviknag.com/en/latest/history.html Wizard Mixins ✨ ---------------- In addition to ``JSONWizard``, Dataclass Wizard provides a set of focused Mixin_ classes to simplify common serialization tasks: - 🪄 `EnvWizard`_ — Load environment variables and ``.env`` files into typed schemas, including support for secret directories. - 🎩 `JSONPyWizard`_ — A helper for ``JSONWizard`` that preserves keys as-is (no case transformations). - 🔮 `JSONListWizard`_ — Extend ``JSONWizard`` to convert lists into container objects. - 💼 `JSONFileWizard`_ — Load and save dataclass instances from local JSON files. Optional format support: - 🌳 `TOMLWizard`_ — Map dataclasses to and from TOML. - 🧙‍♂️ `YAMLWizard`_ — Convert between YAML and dataclasses using ``