Dataclass Wizard

Warnings

• breaking Starting with v1.0.0, the default key transformation for JSON serialization will change from camelCase (e.g., 'myField') to keeping keys as-is (e.g., 'my_field'). Users relying on automatic camelCase conversion should explicitly set `v1_key_case='camel'` in the inner `Meta` class or use `JSONPyWizard` if no transformation is desired.
  Fix: For existing code, either explicitly configure `v1_key_case='camel'` in the `Meta` class of your dataclasses, or update your JSON input/output to match the as-is key names. Alternatively, use `JSONPyWizard` for strict Pythonic (snake_case) key handling.
• deprecated The old 'nested path' functionality (prior to v0.35.0) for mapping deeply nested JSON keys to dataclass fields is deprecated and will no longer be maintained. It has been superseded by enhanced v1 opt-in features.
  Fix: Migrate to the new v1 opt-in features for mapping nested JSON paths, utilizing `KeyPath` or `path_field` in conjunction with `Annotated` types (e.g., `field_name: Annotated[str, KeyPath('data.items.value')]`).
• gotcha When working with `Union` types that contain nested dataclasses, `dataclass-wizard` may raise `ParseError` if it cannot infer the correct type, especially in ambiguous cases.
  Fix: To resolve `ParseError` for `Union` types, explicitly define a `tag_key` and a unique `tag` within the inner `Meta` class of each dataclass participating in the `Union`. This provides clear discrimination for the parser.
• gotcha By default, unknown or extraneous JSON keys encountered during deserialization (`from_dict` or `from_json`) are ignored, and a warning is emitted if debug mode is enabled.
  Fix: To enforce strict parsing and raise an `UnknownKeysError` (or `UnknownJSONKey` in older versions) when unknown keys are present, configure `v1_on_unknown_key='RAISE'` within the inner `Meta` class of your dataclass.
• gotcha Older versions of `dataclass-wizard` (prior to fixes around v0.32.1 and subsequent v1 improvements) might encounter `ParseError` when attempting to parse types that include `typing.Any` when running on Python 3.11+.
  Fix: Ensure you are using a recent version of `dataclass-wizard` (0.32.1 or newer) for improved compatibility and correct parsing of `Any` types, particularly with Python 3.11 and later.
• gotcha The `JSONSerializable` (and its alias `JSONWizard` or `DataclassWizard`) mixin class overrides the default `__str__` method to pretty-print the JSON representation of the object, which is useful for debugging but might not be desired for all use cases.
  Fix: If you prefer the default dataclass `__str__` behavior, you can disable the override by passing `str=False` when inheriting from the mixin, e.g., `class MyClass(DataclassWizard, str=False):`.

Install

• pip install dataclass-wizard Install stable version

Imports

• DataclassWizard

  from dataclass_wizard import DataclassWizard

  While JSONSerializable is functionally equivalent, DataclassWizard is the new preferred base class for the v1 API as of v0.36.0+ and auto-applies the @dataclass decorator, reducing boilerplate.
• JSONWizard

  from dataclass_wizard import JSONWizard

  An alias for JSONSerializable, commonly used for JSON (de)serialization.
• EnvWizard

  from dataclass_wizard import EnvWizard

  Used for loading environment variables into dataclass schemas.
• property_wizard

  from dataclass_wizard import property_wizard

  Used as a metaclass to support field properties with default values in dataclasses.
• json_field

  from dataclass_wizard import json_field

  A helper function for configuring dataclass fields for JSON serialization, similar to `dataclasses.field`.

Quickstart

This quickstart demonstrates basic JSON serialization and deserialization using the `DataclassWizard` mixin, as well as loading configuration from environment variables using `EnvWizard`.

import os
from dataclasses import dataclass
from dataclass_wizard import DataclassWizard, EnvWizard

# --- JSON Serialization/Deserialization ---
@dataclass
class User(DataclassWizard):
    id: int
    name: str
    email: str

json_data = '{"id": 1, "name": "Ritvik", "email": "test@example.com"}'
user = User.from_json(json_data)
print(f"Deserialized User: {user!r}")
# Expected: User(id=1, name='Ritvik', email='test@example.com')

user_dict = user.to_dict()
print(f"User to dict: {user_dict}")
# Expected: {'id': 1, 'name': 'Ritvik', 'email': 'test@example.com'}

# --- Environment Variable Loading ---
os.environ['APP_NAME'] = 'MyEnvApp'
os.environ['DEBUG_MODE'] = 'true'

@dataclass
class AppConfig(EnvWizard):
    app_name: str
    debug_mode: bool

config = AppConfig.from_env()
print(f"App Config: {config!r}")
# Expected: AppConfig(app_name='MyEnvApp', debug_mode=True)