{"id":1984,"library":"dataclass-wizard","title":"Dataclass Wizard","description":"Dataclass Wizard is a fast, lightweight, and pure Python serialization library for extending native Python dataclasses. It provides elegant tools for marshalling dataclass instances to and from JSON, Python dictionary objects, and environment variables, along with support for field properties with default values. The library is actively maintained, with frequent updates and a recently introduced opt-in v1 engine offering enhanced features and improved performance.","status":"active","version":"0.39.1","language":"en","source_language":"en","source_url":"https://github.com/rnag/dataclass-wizard","tags":["dataclasses","json","serialization","deserialization","config","environment variables","type hints"],"install":[{"cmd":"pip install dataclass-wizard","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Backports new typing features for Python 3.10 and earlier versions. Automatically included if needed.","package":"typing-extensions","optional":true}],"imports":[{"note":"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.","wrong":"from dataclass_wizard import JSONSerializable","symbol":"DataclassWizard","correct":"from dataclass_wizard import DataclassWizard"},{"note":"An alias for JSONSerializable, commonly used for JSON (de)serialization.","symbol":"JSONWizard","correct":"from dataclass_wizard import JSONWizard"},{"note":"Used for loading environment variables into dataclass schemas.","symbol":"EnvWizard","correct":"from dataclass_wizard import EnvWizard"},{"note":"Used as a metaclass to support field properties with default values in dataclasses.","symbol":"property_wizard","correct":"from dataclass_wizard import property_wizard"},{"note":"A helper function for configuring dataclass fields for JSON serialization, similar to `dataclasses.field`.","symbol":"json_field","correct":"from dataclass_wizard import json_field"}],"quickstart":{"code":"import os\nfrom dataclasses import dataclass\nfrom dataclass_wizard import DataclassWizard, EnvWizard\n\n# --- JSON Serialization/Deserialization ---\n@dataclass\nclass User(DataclassWizard):\n    id: int\n    name: str\n    email: str\n\njson_data = '{\"id\": 1, \"name\": \"Ritvik\", \"email\": \"test@example.com\"}'\nuser = User.from_json(json_data)\nprint(f\"Deserialized User: {user!r}\")\n# Expected: User(id=1, name='Ritvik', email='test@example.com')\n\nuser_dict = user.to_dict()\nprint(f\"User to dict: {user_dict}\")\n# Expected: {'id': 1, 'name': 'Ritvik', 'email': 'test@example.com'}\n\n# --- Environment Variable Loading ---\nos.environ['APP_NAME'] = 'MyEnvApp'\nos.environ['DEBUG_MODE'] = 'true'\n\n@dataclass\nclass AppConfig(EnvWizard):\n    app_name: str\n    debug_mode: bool\n\nconfig = AppConfig.from_env()\nprint(f\"App Config: {config!r}\")\n# Expected: AppConfig(app_name='MyEnvApp', debug_mode=True)","lang":"python","description":"This quickstart demonstrates basic JSON serialization and deserialization using the `DataclassWizard` mixin, as well as loading configuration from environment variables using `EnvWizard`."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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')]`).","message":"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.","severity":"deprecated","affected_versions":"<0.35.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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+.","severity":"gotcha","affected_versions":"<0.32.1 (especially with Python 3.11+)"},{"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):`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}