{"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":"python","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,"search_vec":"'activ':49 'along':37 'config':73 'dataclass':1,3,18,25,69 'default':44 'deseri':72 'dictionari':32 'eleg':21 'engin':62 'enhanc':64 'environ':35,74 'extend':15 'fast':7 'featur':65 'field':41 'frequent':52 'hint':77 'improv':67 'instanc':26 'introduc':57 'json':30,70 'librari':13,47 'lightweight':8 'maintain':50 'marshal':24 'nativ':16 'object':33 'offer':63 'opt':59 'opt-in':58 'perform':68 'properti':42 'provid':20 'pure':10 'python':11,17,31 'recent':56 'serial':12,71 'support':39 'tool':22 'type':76 'updat':53 'v1':61 'valu':45 'variabl':36,75 'wizard':2,4","created_at":"2026-04-09T18:38:33.375489+00:00","updated_at":"2026-04-16T05:25:26.985375+00:00","problems":[{"fix":"To fix this, either define the 'your_unmapped_key' field in your dataclass, or configure the `JSONWizard.Meta` class to ignore unknown keys or capture them using a `CatchAll` field.\n\nExample to ignore unknown keys:\n```python\nfrom dataclasses import dataclass\nfrom dataclass_wizard import JSONWizard\n\n@dataclass\nclass MyData(JSONWizard):\n    class _(JSONWizard.Meta):\n        raise_on_unknown_json_key = False # Default behavior, but can be explicitly set\n    field_a: str\n    field_b: int\n\n# Or to capture them:\nfrom dataclass_wizard.enums import CatchAll\n@dataclass\nclass MyDataWithCatchAll(JSONWizard):\n    field_a: str\n    unknown_fields: CatchAll\n```","cause":"This error occurs when the JSON input contains a key that does not have a corresponding field defined in the dataclass being deserialized, and the `raise_on_unknown_json_key` setting is enabled.","error":"dataclass_wizard.errors.UnknownJSONKey: Unknown JSON key 'your_unmapped_key' in class 'YourDataclassName'"},{"fix":"This issue has been resolved in newer versions of `dataclass-wizard`. Upgrade the library to the latest version (0.32.1 or higher is mentioned as a fix for a related bug in 0.32.0, so generally upgrading is the solution).\n\n```bash\npip install --upgrade dataclass-wizard\n```","cause":"This specific error was a known bug in `dataclass-wizard` when used with Python 3.11, related to how `typing.Any` was handled during type introspection.","error":"dataclass_wizard.errors.ParseError: Failure parsing field None in class None. Expected a type Any, got NoneType. value: None error: Provided type is not currently supported. unsupported_type: typing.Any"},{"fix":"Enable the `recursive_classes` flag in the `Meta` configuration for your dataclass, or bind it using `LoadMeta`.\n\n```python\nfrom dataclasses import dataclass\nfrom dataclass_wizard import JSONWizard, LoadMeta\n\n@dataclass\nclass Node:\n    name: str\n    children: list['Node']\n\n# Method 1: Using an inner Meta class\n@dataclass\nclass MyTree(JSONWizard):\n    class _(JSONWizard.Meta):\n        recursive_classes = True\n    root: Node\n\n# Method 2: Using LoadMeta.bind_to\nLoadMeta(recursive_classes=True).bind_to(Node)\n```","cause":"This error occurs when attempting to deserialize a dataclass that has self-referential or cyclic (recursive) type hints without explicitly enabling the `recursive_classes` flag in the `Meta` configuration.","error":"dataclass_wizard.errors.RecursiveClassError: Failure parsing class `YourRecursiveClass`. Consider updating the Meta config to enable the `recursive_classes` flag."},{"fix":"Define a `tag_key` in the `JSONWizard.Meta` configuration and ensure your JSON input includes this tag to help `dataclass-wizard` determine the correct class for deserialization within the Union type.\n\n```python\nfrom dataclasses import dataclass\nfrom typing import Union\nfrom dataclass_wizard import JSONWizard\n\n@dataclass\nclass Cat:\n    name: str\n    type: str = 'cat'\n\n@dataclass\nclass Dog:\n    name: str\n    type: str = 'dog'\n\n@dataclass\nclass PetContainer(JSONWizard):\n    class _(JSONWizard.Meta):\n        # 'type' field in the JSON will determine which class to use\n        tag_key = 'type'\n        auto_assign_tags = True # Automatically adds the 'type' field on serialization\n    pet: Union[Cat, Dog]\n\n# Example JSON: {'pet': {'type': 'cat', 'name': 'Whiskers'}}\n```","cause":"This `ParseError` typically occurs when a dataclass field is annotated with a `Union` of other dataclasses (e.g., `Union[ClassA, ClassB]`), and the library cannot automatically infer which specific class to use for deserialization from the input data. This often happens if a `tag_key` is not specified to disambiguate.","error":"dataclass_wizard.errors.ParseError: Cannot determine which class to deserialize to for field 'your_union_field'. No tag key 'type' found in input."}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.0.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/rnag/dataclass-wizard","docs":"https://dcw.ritviknag.com","changelog":"https://dcw.ritviknag.com/en/latest/history.html","pypi":"https://pypi.org/project/dataclass-wizard/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}