`__ section.
8 |
9 | You can optionally add hooks that are run before a JSON string or a
10 | Python ``dict`` object is loaded to a dataclass instance, or before the
11 | dataclass instance is converted back to a Python ``dict`` object.
12 |
13 | To customize the load process:
14 |
15 | * To pre-process data before ``from_dict`` is called, simply
16 | implement a ``_pre_from_dict`` method which will be called
17 | whenever you invoke the ``from_dict`` or ``from_json`` methods.
18 | Please note that this will pass in the original ``dict`` object,
19 | so updating any values will affect data in the underlying ``dict``
20 | (**this might change in a future revision**).
21 | * To post-process data, *after* a dataclass instance is de-serialized,
22 | simply implement the ``__post_init__`` method which will be run
23 | by the ``dataclass`` decorator.
24 |
25 | To customize the dump process, simply implement
26 | a ``_pre_dict`` method which will be called
27 | whenever you invoke the ``to_dict`` or ``to_json``
28 | methods. Please note that this will pass in the
29 | original dataclass instance, so updating any values
30 | will affect the fields of the underlying dataclass
31 | (**this might change in a future revision**).
32 |
33 | A simple example to illustrate both approaches is shown below:
34 |
35 | .. code:: python3
36 |
37 | from dataclasses import dataclass
38 | from dataclass_wizard import JSONWizard
39 | from dataclass_wizard.type_def import JSONObject
40 |
41 |
42 | @dataclass
43 | class MyClass(JSONWizard):
44 | my_str: str
45 | my_int: int
46 | my_bool: bool = False
47 |
48 | def __post_init__(self):
49 | self.my_str = self.my_str.title()
50 | self.my_int *= 2
51 |
52 | @classmethod
53 | def _pre_from_dict(cls, o: JSONObject) -> JSONObject:
54 | # o = o.copy() # Copying the `dict` object is optional
55 | o['my_bool'] = True # Adds a new key/value pair
56 | return o
57 |
58 | def _pre_dict(self):
59 | self.my_str = self.my_str.swapcase()
60 |
61 |
62 | data = {"my_str": "my string", "myInt": "10"}
63 |
64 | c = MyClass.from_dict(data)
65 | print(repr(c))
66 | # prints:
67 | # MyClass(my_str='My String', my_int=20, my_bool=True)
68 |
69 | string = c.to_json()
70 | print(string)
71 | # prints:
72 | # {"myStr": "mY sTRING", "myInt": 20, "myBool": true}
73 |
--------------------------------------------------------------------------------
/docs/quickstart.rst:
--------------------------------------------------------------------------------
1 | ==========
2 | Quickstart
3 | ==========
4 |
5 | Here are the supported features that Dataclass Wizard currently provides:
6 |
7 | - *JSON (de)serialization*: marshal dataclasses to/from JSON and Python
8 | ``dict`` objects.
9 | - *Field properties*: support for using properties with default
10 | values in dataclass instances.
11 |
12 | The below is an quick demo of both of these features - how to marshal dataclasses to/from JSON and Python ``dict`` objects,
13 | and declare and use field properties with default values.
14 |
15 |
16 | .. code:: python3
17 |
18 | from dataclasses import dataclass, field
19 | from datetime import datetime
20 | from typing import Optional
21 |
22 | from dataclass_wizard import JSONSerializable, property_wizard
23 |
24 |
25 | @dataclass
26 | class MyClass(JSONSerializable, metaclass=property_wizard):
27 |
28 | my_str: Optional[str]
29 | list_of_int: list[int] = field(default_factory=list)
30 | # You can also define this as `my_dt`, however only the annotation
31 | # will carry over in that case, since the value is re-declared by
32 | # the property below. See also the 'Using Field Properties' section
33 | # in the docs for a more elegant approach.
34 | _my_dt: datetime = datetime(2000, 1, 1)
35 |
36 | @property
37 | def my_dt(self):
38 | """
39 | A sample `getter` which returns the datetime with year set as 2010
40 | """
41 | if self._my_dt is not None:
42 | return self._my_dt.replace(year=2010)
43 | return self._my_dt
44 |
45 | @my_dt.setter
46 | def my_dt(self, new_dt: datetime):
47 | """
48 | A sample `setter` which sets the inverse (roughly) of the `month` and `day`
49 | """
50 | self._my_dt = new_dt.replace(
51 | month=13 - new_dt.month,
52 | day=31 - new_dt.day)
53 |
54 |
55 | string = '''{"myStr": 42, "listOFInt": [1, "2", 3]}'''
56 | # Uses the default value for `my_dt`, with year=2000, month=1, day=1
57 | c = MyClass.from_json(string)
58 |
59 | print(repr(c))
60 | # prints:
61 | # MyClass(my_str='42', list_of_int=[1, 2, 3], my_dt=datetime.datetime(2010, 12, 30, 0, 0))
62 |
63 | my_dict = {'My_Str': 'string', 'myDT': '2021-01-20T15:55:30Z'}
64 | c = MyClass.from_dict(my_dict)
65 |
66 | print(repr(c))
67 | # prints:
68 | # MyClass(my_str='string', list_of_int=[], my_dt=datetime.datetime(2010, 12, 11, 15, 55, 30, tzinfo=datetime.timezone.utc))
69 |
70 | print(c.to_json())
71 | # prints:
72 | # {"myStr": "string", "listOfInt": [], "myDt": "2010-12-11T15:55:30Z"}
73 |
--------------------------------------------------------------------------------
/dataclass_wizard/v1/enums.py:
--------------------------------------------------------------------------------
1 | from enum import Enum
2 |
3 | from ..utils.string_conv import (to_camel_case,
4 | to_lisp_case,
5 | to_pascal_case,
6 | to_snake_case)
7 | from ..utils.wrappers import FuncWrapper
8 |
9 |
10 | class KeyAction(Enum):
11 | """
12 | Specifies how to handle unknown keys encountered during deserialization.
13 |
14 | Actions:
15 | - `IGNORE`: Skip unknown keys silently.
16 | - `RAISE`: Raise an exception upon encountering the first unknown key.
17 | - `WARN`: Log a warning for each unknown key.
18 |
19 | For capturing unknown keys (e.g., including them in a dataclass), use the `CatchAll` field.
20 | More details: https://dcw.ritviknag.com/en/latest/common_use_cases/handling_unknown_json_keys.html#capturing-unknown-keys-with-catchall
21 | """
22 | IGNORE = 0 # Silently skip unknown keys.
23 | RAISE = 1 # Raise an exception for the first unknown key.
24 | WARN = 2 # Log a warning for each unknown key.
25 | # INCLUDE = 3
26 |
27 |
28 | class KeyCase(Enum):
29 | """
30 | Defines transformations for string keys, commonly used for mapping JSON keys to dataclass fields.
31 |
32 | Key transformations:
33 |
34 | - `CAMEL`: Converts snake_case to camelCase.
35 | Example: `my_field_name` -> `myFieldName`
36 | - `PASCAL`: Converts snake_case to PascalCase (UpperCamelCase).
37 | Example: `my_field_name` -> `MyFieldName`
38 | - `KEBAB`: Converts camelCase or snake_case to kebab-case.
39 | Example: `myFieldName` -> `my-field-name`
40 | - `SNAKE`: Converts camelCase to snake_case.
41 | Example: `myFieldName` -> `my_field_name`
42 | - `AUTO`: Automatically maps JSON keys to dataclass fields by
43 | attempting all valid key casing transforms at runtime.
44 | Example: `My-Field-Name` -> `my_field_name` (cached for future lookups)
45 |
46 | By default, no transformation is applied:
47 | * Example: `MY_FIELD_NAME` -> `MY_FIELD_NAME`
48 | """
49 | # Key casing options
50 | CAMEL = C = FuncWrapper(to_camel_case) # Convert to `camelCase`
51 | PASCAL = P = FuncWrapper(to_pascal_case) # Convert to `PascalCase`
52 | KEBAB = K = FuncWrapper(to_lisp_case) # Convert to `kebab-case`
53 | SNAKE = S = FuncWrapper(to_snake_case) # Convert to `snake_case`
54 | AUTO = A = None # Attempt all valid casing transforms at runtime.
55 |
56 | def __call__(self, *args):
57 | """Apply the key transformation."""
58 | return self.value.f(*args)
59 |
60 |
61 | class DateTimeTo(Enum):
62 | ISO = 0 # ISO 8601 string (default)
63 | TIMESTAMP = 1 # Unix timestamp (seconds)
64 |
--------------------------------------------------------------------------------
/tests/unit/test_property_wizard_with_future_import.py:
--------------------------------------------------------------------------------
1 | from __future__ import annotations
2 |
3 | import logging
4 | from dataclasses import dataclass, field
5 |
6 | from dataclass_wizard import property_wizard
7 |
8 |
9 | log = logging.getLogger(__name__)
10 |
11 |
12 | def test_property_wizard_with_public_property_and_field_with_or():
13 | """
14 | Using `property_wizard` when the dataclass has both a property and field
15 | name *without* a leading underscore, and using the OR ("|") operator,
16 | instead of the `typing.Union` usage.
17 | """
18 | @dataclass
19 | class Vehicle(metaclass=property_wizard):
20 |
21 | # The value of `wheels` here will be ignored, since `wheels` is simply
22 | # re-assigned on the following property definition.
23 | wheels: int | str = 4
24 |
25 | @property
26 | def wheels(self) -> int:
27 | return self._wheels
28 |
29 | @wheels.setter
30 | def wheels(self, wheels: int | str):
31 | self._wheels = int(wheels)
32 |
33 | v = Vehicle()
34 | log.debug(v)
35 | assert v.wheels == 0
36 |
37 | v = Vehicle(wheels=3)
38 | log.debug(v)
39 | assert v.wheels == 3
40 |
41 | v = Vehicle('6')
42 | log.debug(v)
43 | assert v.wheels == 6, 'The constructor should use our setter method'
44 |
45 | v.wheels = '123'
46 | assert v.wheels == 123, 'Expected assignment to use the setter method'
47 |
48 |
49 | def test_property_wizard_with_unresolvable_forward_ref():
50 | """
51 | Using `property_wizard` when the annotated field for a property references
52 | a class or type that is not yet declared.
53 | """
54 | @dataclass
55 | class Car:
56 | spare_tires: int
57 |
58 | class Truck:
59 | ...
60 |
61 | globals().update(locals())
62 |
63 | @dataclass
64 | class Vehicle(metaclass=property_wizard):
65 |
66 | # The value of `cars` here will be ignored, since `cars` is simply
67 | # re-assigned on the following property definition.
68 | cars: list[Car] = field(default_factory=list)
69 | trucks: list[Truck] = field(default_factory=list)
70 |
71 | @property
72 | def cars(self) -> int:
73 | return self._cars
74 |
75 | @cars.setter
76 | def cars(self, cars: list[Car]):
77 | self._cars = cars * 2 if cars else cars
78 |
79 |
80 | v = Vehicle()
81 | log.debug(v)
82 | assert not v.cars
83 | # assert v.cars is None
84 |
85 | v = Vehicle([Car(1)])
86 | log.debug(v)
87 | assert v.cars == [Car(1), Car(1)], 'The constructor should use our ' \
88 | 'setter method'
89 |
90 | v.cars = [Car(3)]
91 | assert v.cars == [Car(3), Car(3)], 'Expected assignment to use the ' \
92 | 'setter method'
93 |
--------------------------------------------------------------------------------
/docs/_templates/sidebarintro.html:
--------------------------------------------------------------------------------
1 |
7 |
8 |
23 |
33 |
34 |
35 |
36 |
37 | Bring Python dataclasses to life — the wizard way!
38 |
39 |
40 |
41 |
42 |
43 | Useful Links
44 |
76 |
--------------------------------------------------------------------------------
/run_bench.py:
--------------------------------------------------------------------------------
1 | import glob
2 | import json
3 | import os
4 | import shutil
5 | import subprocess
6 | import matplotlib.pyplot as plt
7 |
8 |
9 | def run_benchmarks():
10 | # Ensure the `.benchmarks` folder exists
11 | os.makedirs(".benchmarks", exist_ok=True)
12 |
13 | # Run pytest benchmarks and save results
14 | print("Running benchmarks...")
15 | result = subprocess.run(
16 | ["pytest", "benchmarks/catch_all.py", "--benchmark-save=benchmark_results"],
17 | capture_output=True,
18 | text=True
19 | )
20 | print(result.stdout)
21 |
22 |
23 | def load_benchmark_results(file_path):
24 | """Load the benchmark results from the provided JSON file."""
25 | with open(file_path, "r") as f:
26 | return json.load(f)
27 |
28 |
29 | def plot_relative_performance(results):
30 | """Plot relative performance for different benchmark groups."""
31 | benchmarks = results["benchmarks"]
32 |
33 | # Extract and format data
34 | names = []
35 | ops = []
36 | for bm in benchmarks:
37 | group = bm.get("group", "")
38 | library = "dataclass-wizard" if "wizard" in bm["name"] else "dataclasses-json"
39 | formatted_name = f"{group} ({library})"
40 | names.append(formatted_name)
41 | ops.append(bm["stats"]["ops"])
42 |
43 | # Calculate relative performance (ratio of each ops to the slowest ops)
44 | baseline = min(ops)
45 | relative_performance = [op / baseline for op in ops]
46 |
47 | # Plot bar chart
48 | plt.figure(figsize=(10, 6))
49 | bars = plt.barh(names, relative_performance, color="skyblue")
50 | plt.xlabel("Performance Relative to Slowest (times faster)")
51 | plt.title("Catch All: Relative Performance of dataclass-wizard vs dataclasses-json")
52 | plt.tight_layout()
53 |
54 | # Add data labels to the bars
55 | for bar, rel_perf in zip(bars, relative_performance):
56 | plt.text(bar.get_width() + 0.1, bar.get_y() + bar.get_height() / 2,
57 | f"{rel_perf:.1f}x", va="center")
58 |
59 | # Save and display the plot
60 | plt.savefig("catch_all.png")
61 | plt.show()
62 |
63 |
64 | def find_latest_benchmark_file():
65 | """Find the most recent benchmark result file."""
66 | benchmark_dir = ".benchmarks"
67 | pattern = os.path.join(benchmark_dir, "**", "*.json")
68 | files = glob.glob(pattern, recursive=True)
69 | if not files:
70 | raise FileNotFoundError("No benchmark files found.")
71 | latest_file = max(files, key=os.path.getctime) # Find the most recently created file
72 | return latest_file
73 |
74 |
75 | if __name__ == "__main__":
76 | # Step 1: Run benchmarks
77 | run_benchmarks()
78 |
79 | # Step 2: Find the latest benchmark results file
80 | benchmark_file = find_latest_benchmark_file()
81 | print(f"Latest benchmark file: {benchmark_file}")
82 |
83 | # Step 3: Load the benchmark results
84 | if os.path.exists(benchmark_file):
85 | results = load_benchmark_results(benchmark_file)
86 |
87 | # Step 4: Plot results
88 | plot_relative_performance(results)
89 |
90 | else:
91 | print(f"Benchmark file not found: {benchmark_file}")
92 |
93 | # Step 5: Move the generated image to docs folder for easy access
94 | shutil.copy("catch_all.png", "docs/")
95 |
--------------------------------------------------------------------------------
/docs/common_use_cases/easier_debug_mode.rst:
--------------------------------------------------------------------------------
1 | Easier Debug Mode
2 | =================
3 |
4 | The ``dataclass-wizard`` library provides a convenient way to enable logging for debugging. While one approach is to enable the ``debug_enabled`` flag in ``JSONWizard.Meta``, this requires proper setup of the ``logging`` module, as shown below:
5 |
6 | .. code:: python3
7 |
8 | import logging
9 | from dataclasses import dataclass
10 | from dataclass_wizard import JSONWizard
11 |
12 | # Manually set logging level
13 | logging.basicConfig(level=logging.DEBUG)
14 |
15 | @dataclass
16 | class MyClass(JSONWizard):
17 | class _(JSONWizard.Meta):
18 | debug_enabled = True
19 |
20 | Simpler Debugging with ``debug``
21 | --------------------------------
22 |
23 | A simpler and more flexible approach is to pass the ``debug`` argument directly when subclassing ``JSONWizard``. This not only sets the ``logging.basicConfig(level=logging.DEBUG)`` automatically, but also lets you customize the log level by passing a value like ``logging.INFO`` or ``logging.DEBUG``:
24 |
25 | .. code:: python3
26 |
27 | import logging
28 | from dataclasses import dataclass
29 | from dataclass_wizard import JSONWizard
30 |
31 | @dataclass
32 | class MyClass(JSONWizard, debug=logging.INFO):
33 | class _(JSONWizard.Meta):
34 | skip_defaults = True
35 | key_transform_with_dump = 'PASCAL'
36 |
37 | my_bool: bool
38 | my_int: int = 2
39 |
40 | @classmethod
41 | def _pre_from_dict(cls, o):
42 | o['myBool'] = True
43 | return o
44 |
45 | # Setting `debug=logging.INFO` automatically configures the logger:
46 | # logging.getLogger('dataclass_wizard').setLevel(logging.INFO)
47 |
48 | c = MyClass.from_dict({'myBool': 'false'})
49 | print(c)
50 | # {
51 | # "MyBool": true
52 | # }
53 |
54 | Key Points
55 | ----------
56 |
57 | 1. **Automatic Logging Setup**:
58 | When ``debug=True`` (or ``debug=logging.DEBUG``, etc.), ``logging.basicConfig(level=logging.DEBUG)`` is automatically configured for the library.
59 |
60 | 2. **Custom Log Levels**:
61 | - Pass a **boolean** (``True``) to enable ``DEBUG`` level logs.
62 | - Pass a **logging level** (e.g., ``logging.INFO``, ``logging.WARNING``) to set a custom log level.
63 | This internally maps to ``JSONWizard.Meta.debug_enabled``, configuring the library’s logger with the specified level.
64 |
65 | 3. **Library Logger**:
66 | The library logger (``dataclass_wizard``) is dynamically set via ``logging.getLogger('dataclass_wizard').setLevel(input_level)`` based on the ``debug`` argument.
67 |
68 | 4. **Convenient Defaults**:
69 | No need to manually configure ``logging.basicConfig`` or adjust log levels outside your class definition.
70 |
71 | Examples of Log Levels
72 | ----------------------
73 |
74 | .. code:: python3
75 |
76 | import logging
77 | from dataclasses import dataclass
78 | from dataclass_wizard import JSONWizard
79 |
80 | @dataclass
81 | class DebugExample(JSONWizard, debug=True):
82 | ... # DEBUG level (default for boolean True)
83 |
84 | @dataclass
85 | class InfoExample(JSONWizard, debug="INFO"):
86 | ... # INFO level
87 |
88 | @dataclass
89 | class WarningExample(JSONWizard, debug=logging.WARNING):
90 | ... # WARNING level
91 |
--------------------------------------------------------------------------------
/docs/common_use_cases/skip_inheritance.rst:
--------------------------------------------------------------------------------
1 | Skip the Class Inheritance
2 | --------------------------
3 |
4 | It is important to note that the main purpose of sub-classing from
5 | ``JSONWizard`` Mixin class is to provide helper methods like :meth:`from_dict`
6 | and :meth:`to_dict`, which makes it much more convenient and easier to load or
7 | dump your data class from and to JSON.
8 |
9 | That is, it's meant to *complement* the usage of the ``dataclass`` decorator,
10 | rather than to serve as a drop-in replacement for data classes, or to provide type
11 | validation for example; there are already excellent libraries like `pydantic`_ that
12 | provide these features if so desired.
13 |
14 | However, there may be use cases where we prefer to do away with the class
15 | inheritance model introduced by the Mixin class. In the interests of convenience
16 | and also so that data classes can be used *as is*, the Dataclass
17 | Wizard library provides the helper functions :func:`fromlist` and :func:`fromdict`
18 | for de-serialization, and :func:`asdict` for serialization. These functions also
19 | work recursively, so there is full support for nested dataclasses -- just as with
20 | the class inheritance approach.
21 |
22 | Here is an example to demonstrate the usage of these helper functions:
23 |
24 | .. code:: python3
25 |
26 | from dataclasses import dataclass
27 | from datetime import datetime
28 | from typing import Optional, Union
29 |
30 | from dataclass_wizard import fromdict, asdict, DumpMeta
31 |
32 |
33 | @dataclass
34 | class Container:
35 | id: int
36 | created_at: datetime
37 | my_elements: list['MyElement']
38 |
39 |
40 | @dataclass
41 | class MyElement:
42 | order_index: Optional[int]
43 | status_code: Union[int, str]
44 |
45 |
46 | source_dict = {'id': '123',
47 | 'createdAt': '2021-01-01 05:00:00Z',
48 | 'myElements': [
49 | {'orderIndex': 111, 'statusCode': '200'},
50 | {'order_index': '222', 'status_code': 404}
51 | ]}
52 |
53 | # De-serialize the JSON dictionary object into a `Container` instance.
54 | c = fromdict(Container, source_dict)
55 |
56 | print(repr(c))
57 | # prints:
58 | # Container(id=123, created_at=datetime.datetime(2021, 1, 1, 5, 0), my_elements=[MyElement(order_index=111, status_code='200'), MyElement(order_index=222, status_code=404)])
59 |
60 | # (Optional) Set up dump config for the inner class, as unfortunately there's
61 | # no option currently to have the meta config apply in a recursive fashion.
62 | _ = DumpMeta(MyElement, key_transform='SNAKE')
63 |
64 | # Serialize the `Container` instance to a Python dict object with a custom
65 | # dump config, for example one which converts field names to snake case.
66 | json_dict = asdict(c, DumpMeta(Container,
67 | key_transform='SNAKE',
68 | marshal_date_time_as='TIMESTAMP'))
69 |
70 | expected_dict = {'id': 123,
71 | 'created_at': 1609477200,
72 | 'my_elements': [
73 | {'order_index': 111, 'status_code': '200'},
74 | {'order_index': 222, 'status_code': 404}
75 | ]}
76 |
77 | # Assert that we get the expected dictionary object.
78 | assert json_dict == expected_dict
79 |
80 |
81 | .. _`pydantic`: https://pydantic-docs.helpmanual.io/
82 |
--------------------------------------------------------------------------------
/recipe/meta.yaml:
--------------------------------------------------------------------------------
1 | # Recipe used to publish this package to Anaconda and Conda Forge
2 | #
3 | # Note:
4 | # To publish, replace `source -> sha256` below, and run `make release-conda`
5 | #
6 | # Credits:
7 | # - https://github.com/conda-forge/staged-recipes
8 | # - https://docs.conda.io/projects/conda-build/en/latest/resources/define-metadata.html
9 |
10 | {% set data = load_setup_py_data(setup_file='../setup.py', from_recipe_dir=True) %}
11 | {% set name = data['name'] %}
12 | {% set version = data['version'] %}
13 | {% set author = "rnag" %}
14 | {% set repo_url = data['url'] %}
15 | {% set description = data['description'] %}
16 |
17 | package:
18 | name: {{ name|lower }}
19 | version: {{ version }}
20 |
21 | source:
22 | url: https://pypi.io/packages/source/{{ name[0] }}/{{ name }}/{{ name }}-{{ version }}.tar.gz
23 | sha256: 1a870882a8ff19e7ab9ede7b672b2f7c1ce8d69bbd2fc6d9629da749227268fd
24 | # sha256 is the preferred checksum -- you can get it for a file with:
25 | # `openssl sha256 `.
26 | # You may need the openssl package, available on conda-forge:
27 | # `conda install openssl -c conda-forge`
28 |
29 | build:
30 | number: 0
31 | entry_points:
32 | - wiz={{ name|replace('-', '_') }}.wizard_cli.cli:main
33 | script: {{ PYTHON }} -m pip install . -vv
34 | noarch: python
35 | # Add the line "skip: True # [py<35]" (for example) to limit to Python 3.5 and newer, or "skip: True # [not win]" to limit to Windows.
36 | skip: True # [py<39]
37 |
38 | requirements:
39 | host:
40 | - python
41 | - pip
42 | - setuptools
43 | run:
44 | - python
45 | - typing-extensions >=4.9.0 # [py<=312]
46 |
47 | test:
48 | imports:
49 | - {{ name|replace('-', '_') }}
50 | requires:
51 | - pip
52 | # - pytest
53 | commands:
54 | - pip check
55 | - wiz --help
56 | # - pytest -v
57 |
58 | about:
59 | home: {{ repo_url }}
60 | # See https://spdx.org/licenses/
61 | license: Apache-2.0
62 | # The license_family, i.e. "BSD" if license is "BSD-3-Clause". (optional)
63 | license_family: Apache
64 | # It is strongly encouraged to include a license file in the package,
65 | # (even if the license doesn't require it) using the license_file entry.
66 | # See https://docs.conda.io/projects/conda-build/en/latest/resources/define-metadata.html#license-file
67 | license_file: LICENSE
68 | summary: Lightning-fast JSON wizardry for Python dataclasses — effortless serialization right out of the box!
69 | # The remaining entries in this section are optional, but recommended.
70 | description: |
71 | The dataclass-wizard library provides a set of simple, yet
72 | elegant *wizarding* tools for interacting with the Python
73 | `dataclasses` module in Python 3.9+.
74 |
75 | The primary use is as a fast serialization framework that enables
76 | dataclass instances to be converted to/from JSON; this works well
77 | in particular with a *nested dataclass* model.
78 |
79 | The dataclass-wizard is pure Python code that relies entirely on
80 | stdlib, with the only added dependency being
81 | `typing-extensions`
82 | for Python 3.12 and below.
83 | doc_url: https://{{ name }}.readthedocs.io/
84 | dev_url: {{ repo_url }}
85 |
86 | extra:
87 | recipe-maintainers:
88 | # GitHub IDs for maintainers of the recipe.
89 | # Always check with the people listed below if they are OK becoming maintainers of the recipe. (There will be spam!)
90 | - {{ author }}
91 |
--------------------------------------------------------------------------------
/dataclass_wizard/utils/object_path.pyi:
--------------------------------------------------------------------------------
1 | from dataclasses import MISSING
2 | from typing import Any, Sequence, TypeAlias, Union
3 |
4 | PathPart: TypeAlias = Union[str, int, float, bool]
5 | PathType: TypeAlias = Sequence[PathPart]
6 |
7 |
8 | def safe_get(data: dict | list,
9 | path: PathType,
10 | default=MISSING,
11 | raise_: bool = True) -> Any:
12 | """
13 | Retrieve a value from a nested structure safely.
14 |
15 | Traverses a nested structure (e.g., dictionaries or lists) following a sequence of keys or indices specified in `path`.
16 | Handles missing keys, out-of-bounds indices, or invalid types gracefully.
17 |
18 | Args:
19 | data (Any): The nested structure to traverse.
20 | path (Iterable): A sequence of keys or indices to follow.
21 | default (Any): The value to return if the path cannot be fully traversed.
22 | If not provided and an error occurs, the exception is re-raised.
23 | raise_ (bool): True to raise an error on invalid path (default True).
24 |
25 | Returns:
26 | Any: The value at the specified path, or `default` if traversal fails.
27 |
28 | Raises:
29 | KeyError, IndexError, AttributeError, TypeError: If `default` is not provided
30 | and an error occurs during traversal.
31 | """
32 | ...
33 |
34 |
35 | def v1_safe_get(data: dict | list,
36 | path: PathType,
37 | raise_: bool) -> Any:
38 | """
39 | Retrieve a value from a nested structure safely.
40 |
41 | Traverses a nested structure (e.g., dictionaries or lists) following a sequence of keys or indices specified in `path`.
42 | Handles missing keys, out-of-bounds indices, or invalid types gracefully.
43 |
44 | Args:
45 | data (Any): The nested structure to traverse.
46 | path (Iterable): A sequence of keys or indices to follow.
47 | raise_ (bool): True to raise an error on invalid path.
48 |
49 | Returns:
50 | Any: The value at the specified path, or `MISSING` if traversal fails.
51 |
52 | Raises:
53 | KeyError, IndexError, AttributeError, TypeError: If `default` is not provided
54 | and an error occurs during traversal.
55 | """
56 | ...
57 |
58 |
59 | def _format_err(e: Exception,
60 | current_data: Any,
61 | path: PathType,
62 | current_path: PathPart):
63 | """Format and return a `ParseError`."""
64 | ...
65 |
66 |
67 | def split_object_path(_input: str) -> PathType:
68 | """
69 | Parse a custom object path string into a list of components.
70 |
71 | This function interprets a custom object path syntax and breaks it into individual path components,
72 | including dictionary keys, list indices, attributes, and nested elements.
73 | It handles escaped characters and supports mixed types (e.g., strings, integers, floats, booleans).
74 |
75 | Args:
76 | _input (str): The object path string to parse.
77 |
78 | Returns:
79 | PathType: A list of components representing the parsed path. Components can be strings,
80 | integers, floats, booleans, or other valid key/index types.
81 |
82 | Example:
83 | >>> split_object_path(r'''a[b][c]["d\\\"o\\\""][e].f[go]['1'].then."y\\e\\\"s"[1]["we can!"].five.2.3.[ok][4.56].[-7.89].'let\\'sd\\othisy\\'all!'.yeah.123.False['True'].thanks!''')
84 | ['a', 'b', 'c', 'd"o"', 'e', 'f', 'go', '1', 'then', 'y\\e"s', 1, 'we can!', 'five', 2, 3, 'ok', 4.56, -7.89,
85 | "let'sd\\othisy'all!", 'yeah', 123, False, 'True', 'thanks!']
86 | """
87 |
--------------------------------------------------------------------------------
/tests/unit/environ/test_loaders.py:
--------------------------------------------------------------------------------
1 | import os
2 | from collections import namedtuple
3 | from dataclasses import dataclass
4 | from datetime import datetime, date, timezone
5 | from typing import Tuple, NamedTuple, List
6 |
7 | import pytest
8 |
9 | from dataclass_wizard import EnvWizard
10 | from dataclass_wizard.environ.loaders import EnvLoader
11 |
12 |
13 | def test_load_to_bytes():
14 | assert EnvLoader.load_to_bytes('testing 123', bytes) == b'testing 123'
15 |
16 |
17 | @pytest.mark.parametrize(
18 | 'input,expected',
19 | [
20 | ('testing 123', bytearray(b'testing 123')),
21 | (b'test', bytearray(b'test')),
22 | ([1, 2, 3], bytearray([1, 2, 3]))
23 | ]
24 | )
25 | def test_load_to_bytearray(input, expected):
26 | assert EnvLoader.load_to_byte_array(input, bytearray) == expected
27 |
28 |
29 | def test_load_to_tuple_and_named_tuple():
30 | os.environ['MY_TUP'] = '1,2,3'
31 | os.environ['MY_NT'] = '[1.23, "string"]'
32 | os.environ['my_untyped_nt'] = 'hello , world, 123'
33 |
34 | class MyNT(NamedTuple):
35 | my_float: float
36 | my_str: str
37 |
38 | untyped_tup = namedtuple('untyped_tup', ('a', 'b', 'c'))
39 |
40 | class MyClass(EnvWizard, reload_env=True):
41 | my_tup: Tuple[int, ...]
42 | my_nt: MyNT
43 | my_untyped_nt: untyped_tup
44 |
45 | c = MyClass()
46 |
47 | assert c.dict() == {'my_nt': MyNT(my_float=1.23, my_str='string'),
48 | 'my_tup': (1, 2, 3),
49 | 'my_untyped_nt': untyped_tup(a='hello', b='world', c='123')}
50 |
51 | assert c.to_dict() == {'my_nt': MyNT(my_float=1.23, my_str='string'),
52 | 'my_tup': (1, 2, 3),
53 | 'my_untyped_nt': untyped_tup(a='hello', b='world', c='123')}
54 |
55 |
56 | def test_load_to_dataclass():
57 | """When an `EnvWizard` subclass has a nested dataclass schema."""
58 |
59 | os.environ['inner_cls_1'] = 'my_bool=false, my_string=test'
60 | os.environ['inner_cls_2'] = '{"answerToLife": "42", "MyList": "testing, 123 , hello!"}'
61 |
62 | @dataclass
63 | class Inner1:
64 | my_bool: bool
65 | my_string: str
66 |
67 | @dataclass
68 | class Inner2:
69 | answer_to_life: int
70 | my_list: List[str]
71 |
72 | class MyClass(EnvWizard, reload_env=True):
73 |
74 | inner_cls_1: Inner1
75 | inner_cls_2: Inner2
76 |
77 | c = MyClass()
78 | # print(c)
79 |
80 | assert c.dict() == {
81 | 'inner_cls_1': Inner1(my_bool=False,
82 | my_string='test'),
83 | 'inner_cls_2': Inner2(answer_to_life=42,
84 | my_list=['testing', '123', 'hello!']),
85 | }
86 |
87 | assert c.to_dict() == {
88 | 'inner_cls_1': {'my_bool': False,
89 | 'my_string': 'test'},
90 | 'inner_cls_2': {'answer_to_life': 42,
91 | 'my_list': ['testing', '123', 'hello!']}
92 | }
93 |
94 |
95 | @pytest.mark.parametrize(
96 | 'input,expected',
97 | [
98 | ('2021-11-28T17:35:55', datetime(2021, 11, 28, 17, 35, 55)),
99 | (1577952245, datetime(2020, 1, 2, 8, 4, 5, tzinfo=timezone.utc)),
100 | (datetime.min, datetime.min)
101 | ]
102 | )
103 | def test_load_to_datetime(input, expected):
104 | assert EnvLoader.load_to_datetime(input, datetime) == expected
105 |
106 |
107 | @pytest.mark.parametrize(
108 | 'input,expected',
109 | [
110 | ('2021-11-28', date(2021, 11, 28)),
111 | (1577952245, date(2020, 1, 2)),
112 | (date.min, date.min)
113 | ]
114 | )
115 | def test_load_to_date(input, expected):
116 | assert EnvLoader.load_to_date(input, date) == expected
117 |
--------------------------------------------------------------------------------
/benchmarks/catch_all.py:
--------------------------------------------------------------------------------
1 | import logging
2 | from dataclasses import dataclass
3 | from typing import Any
4 |
5 | import pytest
6 |
7 | from dataclasses_json import (dataclass_json, Undefined, CatchAll as CatchAllDJ)
8 | from dataclass_wizard import (JSONWizard, CatchAll as CatchAllWizard)
9 |
10 |
11 | log = logging.getLogger(__name__)
12 |
13 |
14 | @dataclass()
15 | class DontCareAPIDump:
16 | endpoint: str
17 | data: dict[str, Any]
18 |
19 |
20 | @dataclass_json(undefined=Undefined.INCLUDE)
21 | @dataclass()
22 | class DontCareAPIDumpDJ(DontCareAPIDump):
23 | unknown_things: CatchAllDJ
24 |
25 |
26 | @dataclass()
27 | class DontCareAPIDumpWizard(DontCareAPIDump, JSONWizard):
28 |
29 | class _(JSONWizard.Meta):
30 | v1 = True
31 |
32 | unknown_things: CatchAllWizard
33 |
34 |
35 | # Fixtures for test data
36 | @pytest.fixture(scope='session')
37 | def data():
38 | return {"endpoint": "some_api_endpoint",
39 | "data": {"foo": 1, "bar": "2"},
40 | "undefined_field_name": [1, 2, 3]}
41 |
42 |
43 | @pytest.fixture(scope='session')
44 | def data_no_extras():
45 | return {"endpoint": "some_api_endpoint",
46 | "data": {"foo": 1, "bar": "2"}}
47 |
48 |
49 | # Benchmark for deserialization (from_dict)
50 | @pytest.mark.benchmark(group="deserialization")
51 | def test_deserialize_wizard(benchmark, data):
52 | benchmark(lambda: DontCareAPIDumpWizard.from_dict(data))
53 |
54 |
55 | @pytest.mark.benchmark(group="deserialization")
56 | def test_deserialize_json(benchmark, data):
57 | benchmark(lambda: DontCareAPIDumpDJ.from_dict(data))
58 |
59 |
60 | # Benchmark for deserialization with no extra data
61 | @pytest.mark.benchmark(group="deserialization_no_extra_data")
62 | def test_deserialize_wizard_no_extras(benchmark, data_no_extras):
63 | benchmark(lambda: DontCareAPIDumpWizard.from_dict(data_no_extras))
64 |
65 |
66 | @pytest.mark.benchmark(group="deserialization_no_extra_data")
67 | def test_deserialize_json_no_extras(benchmark, data_no_extras):
68 | benchmark(lambda: DontCareAPIDumpDJ.from_dict(data_no_extras))
69 |
70 |
71 | # Benchmark for serialization (to_dict)
72 | @pytest.mark.benchmark(group="serialization")
73 | def test_serialize_wizard(benchmark, data):
74 | dump1 = DontCareAPIDumpWizard.from_dict(data)
75 | benchmark(lambda: dump1.to_dict())
76 |
77 |
78 | @pytest.mark.benchmark(group="serialization")
79 | def test_serialize_json(benchmark, data):
80 | dump2 = DontCareAPIDumpDJ.from_dict(data)
81 | benchmark(lambda: dump2.to_dict())
82 |
83 |
84 | def test_validate(data, data_no_extras):
85 | dump1 = DontCareAPIDumpDJ.from_dict(data_no_extras) # DontCareAPIDump(endpoint='some_api_endpoint', data={'foo': 1, 'bar': '2'})
86 | dump2 = DontCareAPIDumpWizard.from_dict(data_no_extras) # DontCareAPIDump(endpoint='some_api_endpoint', data={'foo': 1, 'bar': '2'})
87 |
88 | assert dump1.endpoint == dump2.endpoint
89 | assert dump1.data == dump2.data
90 | assert dump1.unknown_things == dump2.unknown_things == {}
91 |
92 | expected = {'endpoint': 'some_api_endpoint', 'data': {'foo': 1, 'bar': '2'}}
93 |
94 | assert dump1.to_dict() == dump2.to_dict() == expected
95 |
96 | dump1 = DontCareAPIDumpDJ.from_dict(data) # DontCareAPIDump(endpoint='some_api_endpoint', data={'foo': 1, 'bar': '2'})
97 | dump2 = DontCareAPIDumpWizard.from_dict(data) # DontCareAPIDump(endpoint='some_api_endpoint', data={'foo': 1, 'bar': '2'})
98 |
99 | assert dump1.endpoint == dump2.endpoint
100 | assert dump1.data == dump2.data
101 | assert dump1.unknown_things == dump2.unknown_things
102 |
103 | expected = {'endpoint': 'some_api_endpoint', 'data': {'foo': 1, 'bar': '2'}, 'undefined_field_name': [1, 2, 3]}
104 |
105 | assert dump1.to_dict() == dump2.to_dict() == expected
106 |
--------------------------------------------------------------------------------
/docs/common_use_cases/cyclic_or_recursive_dataclasses.rst:
--------------------------------------------------------------------------------
1 | Cyclic or "Recursive" Dataclasses
2 | =================================
3 |
4 | .. note::
5 | **Important:** The current functionality for cyclic or "recursive" dataclasses is being re-imagined.
6 | Please refer to the new docs for **V1 Opt-in** features, which introduces enhanced support for these use
7 | cases. For more details, see the `Field Guide to V1 Opt‐in`_ and the `Recursive Types and Dataclasses with Cyclic References in V1`_ documentation.
8 |
9 | This change is part of the ongoing improvements in version ``v0.34.0+``, and the old functionality will no longer be maintained in future releases.
10 |
11 | .. _Field Guide to V1 Opt‐in: https://github.com/rnag/dataclass-wizard/wiki/Field-Guide-to-V1-Opt%E2%80%90in
12 | .. _Recursive Types and Dataclasses with Cyclic References in V1: https://github.com/rnag/dataclass-wizard/wiki/V1:-Recursive-Types-and-Dataclasses-with-Cyclic-References
13 |
14 | Prior to version ``v0.27.0``, dataclasses with cyclic references
15 | or self-referential structures were not supported. This
16 | limitation is shown in the following toy example:
17 |
18 | .. code:: python3
19 |
20 | from dataclasses import dataclass
21 |
22 | from dataclass_wizard import JSONWizard
23 |
24 |
25 | @dataclass
26 | class A(JSONWizard):
27 | a: 'A | None' = None
28 |
29 |
30 | a = A.from_dict({'a': {'a': {'a': None}}})
31 | assert a == A(a=A(a=A(a=None)))
32 |
33 | This has been a `longstanding issue`_.
34 |
35 | New in ``v0.27.0``: The Dataclass Wizard now extends its support
36 | to cyclic and self-referential dataclass models.
37 |
38 | The example below demonstrates recursive dataclasses with cyclic
39 | dependencies, following the pattern ``A -> B -> A -> B``.
40 |
41 | With Class Inheritance
42 | **********************
43 |
44 | Here’s a basic example demonstrating the use of recursive dataclasses
45 | with cyclic dependencies, using a class inheritance model and
46 | the :class:`JSONWizard` mixin:
47 |
48 | .. code:: python3
49 |
50 | from __future__ import annotations # This can be removed in Python 3.10+
51 |
52 | from dataclasses import dataclass
53 |
54 | from dataclass_wizard import JSONWizard
55 |
56 |
57 | @dataclass
58 | class A(JSONWizard):
59 | class _(JSONWizard.Meta):
60 | # enable support for self-referential / recursive dataclasses
61 | recursive_classes = True
62 |
63 | b: 'B | None' = None
64 |
65 |
66 | @dataclass
67 | class B:
68 | a: A | None = None
69 |
70 |
71 | # confirm that `from_dict` with a recursive, self-referential
72 | # input `dict` works as expected.
73 | a = A.from_dict({'b': {'a': {'b': {'a': None}}}})
74 | assert a == A(b=B(a=A(b=B())))
75 |
76 | Without Class Inheritance
77 | *************************
78 |
79 | Here is the same example as above, but with relying solely on ``dataclasses``, without
80 | using any special class inheritance model:
81 |
82 |
83 | .. code:: python3
84 |
85 | from __future__ import annotations # This can be removed in Python 3.10+
86 |
87 | from dataclasses import dataclass
88 |
89 | from dataclass_wizard import fromdict, LoadMeta
90 |
91 |
92 | @dataclass
93 | class A:
94 | b: 'B | None' = None
95 |
96 |
97 | @dataclass
98 | class B:
99 | a: A | None = None
100 |
101 |
102 | # enable support for self-referential / recursive dataclasses
103 | LoadMeta(recursive_classes=True).bind_to(A)
104 |
105 | # confirm that `from_dict` with a recursive, self-referential
106 | # input `dict` works as expected.
107 | a = fromdict(A, {'b': {'a': {'b': {'a': None}}}})
108 | assert a == A(b=B(a=A(b=B())))
109 |
110 | .. _longstanding issue: https://github.com/rnag/dataclass-wizard/issues/62
111 |
--------------------------------------------------------------------------------
/tests/unit/utils/test_string_conv.py:
--------------------------------------------------------------------------------
1 | import pytest
2 |
3 | from dataclass_wizard.utils.string_conv import *
4 |
5 |
6 | @pytest.mark.parametrize(
7 | 'string,expected',
8 | [
9 | ('device_type', 'deviceType'),
10 | ('io_error', 'ioError'),
11 | ('isACamelCasedWORD', 'isACamelCasedWORD'),
12 | ('ATitledWordToTESTWith', 'aTitledWordToTESTWith'),
13 | ('not-a-tester', 'notATester'),
14 | ('device_type', 'deviceType'),
15 | ('helloworld', 'helloworld'),
16 | ('A', 'a'),
17 | ('TESTing_if_thisWorks', 'tESTingIfThisWorks'),
18 | ('a_B_Cde_fG_hi', 'aBCdeFGHi'),
19 | ('ALL_CAPS', 'aLLCAPS'),
20 | ('WoRd', 'woRd'),
21 | ('HIThereHOWIsItGoinG', 'hIThereHOWIsItGoinG'),
22 | ('How_-Are-_YoUDoing__TeST', 'howAreYoUDoingTeST'),
23 | ('thisIsWithANumber42ToTEST', 'thisIsWithANumber42ToTEST'),
24 | ('Number 42 With spaces', 'number42WithSpaces')
25 | ]
26 | )
27 | def test_to_camel_case(string, expected):
28 | actual = to_camel_case(string)
29 | assert actual == expected
30 |
31 |
32 | @pytest.mark.parametrize(
33 | 'string,expected',
34 | [
35 | ('device_type', 'DeviceType'),
36 | ('io_error', 'IoError'),
37 | ('isACamelCasedWORD', 'IsACamelCasedWORD'),
38 | ('ATitledWordToTESTWith', 'ATitledWordToTESTWith'),
39 | ('not-a-tester', 'NotATester'),
40 | ('device_type', 'DeviceType'),
41 | ('helloworld', 'Helloworld'),
42 | ('A', 'A'),
43 | ('TESTing_if_thisWorks', 'TESTingIfThisWorks'),
44 | ('a_B_Cde_fG_hi', 'ABCdeFGHi'),
45 | ('ALL_CAPS', 'ALLCAPS'),
46 | ('WoRd', 'WoRd'),
47 | ('HIThereHOWIsItGoinG', 'HIThereHOWIsItGoinG'),
48 | ('How_-Are-_YoUDoing__TeST', 'HowAreYoUDoingTeST'),
49 | ('thisIsWithANumber42ToTEST', 'ThisIsWithANumber42ToTEST'),
50 | ('Number 42 With spaces', 'Number42WithSpaces')
51 | ]
52 | )
53 | def test_to_pascal_case(string, expected):
54 | actual = to_pascal_case(string)
55 | assert actual == expected
56 |
57 |
58 | @pytest.mark.parametrize(
59 | 'string,expected',
60 | [
61 | ('device_type', 'device-type'),
62 | ('IO_Error', 'io-error'),
63 | ('isACamelCasedWORD', 'is-a-camel-cased-word'),
64 | ('ATitledWordToTESTWith', 'a-titled-word-to-test-with'),
65 | ('not-a-tester', 'not-a-tester'),
66 | ('helloworld', 'helloworld'),
67 | ('A', 'a'),
68 | ('TESTing_if_thisWorks', 'tes-ting-if-this-works'),
69 | ('a_B_Cde_fG_hi', 'a-b-cde-f-g-hi'),
70 | ('ALL_CAPS', 'all-caps'),
71 | ('WoRd', 'wo-rd'),
72 | ('HIThereHOWIsItGoinG', 'hi-there-how-is-it-goin-g'),
73 | ('How_-Are-_YoUDoing__TeST', 'how-are-yo-u-doing-te-st'),
74 | ('thisIsWithANumber42ToTEST', 'this-is-with-a-number42-to-test'),
75 | ('Number 42 With spaces', 'number-42-with-spaces')
76 | ]
77 | )
78 | def test_to_lisp_case(string, expected):
79 | actual = to_lisp_case(string)
80 | assert actual == expected
81 |
82 |
83 | @pytest.mark.parametrize(
84 | 'string,expected',
85 | [
86 | ('device_type', 'device_type'),
87 | ('IO_Error', 'io_error'),
88 | ('isACamelCasedWORD', 'is_a_camel_cased_word'),
89 | ('ATitledWordToTESTWith', 'a_titled_word_to_test_with'),
90 | ('not-a-tester', 'not_a_tester'),
91 | ('helloworld', 'helloworld'),
92 | ('A', 'a'),
93 | ('TESTing_if_thisWorks', 'tes_ting_if_this_works'),
94 | ('a_B_Cde_fG_hi', 'a_b_cde_f_g_hi'),
95 | ('ALL_CAPS', 'all_caps'),
96 | ('WoRd', 'wo_rd'),
97 | ('HIThereHOWIsItGoinG', 'hi_there_how_is_it_goin_g'),
98 | ('How_-Are-_YoUDoing__TeST', 'how_are_yo_u_doing_te_st'),
99 | ('thisIsWithANumber42ToTEST', 'this_is_with_a_number42_to_test'),
100 | ('Number 42 With spaces', 'number_42_with_spaces')
101 | ]
102 | )
103 | def test_to_snake_case(string, expected):
104 | actual = to_snake_case(string)
105 | assert actual == expected
106 |
--------------------------------------------------------------------------------
/docs/_static/dark_mode.css:
--------------------------------------------------------------------------------
1 | /* General dark mode body */
2 | body.dark-mode {
3 | background-color: #1e1e1e;
4 | color: #cfcfcf;
5 | }
6 |
7 | /* Main page content */
8 | body.dark-mode .body {
9 | background-color: #1e1e1e;
10 | color: #cfcfcf;
11 | }
12 |
13 | /* Fix for the main content on index */
14 | body.dark-mode .content {
15 | background-color: #1e1e1e;
16 | color: #cfcfcf;
17 | }
18 |
19 | /* Sidebar elements */
20 | body.dark-mode .wy-nav-side,
21 | body.dark-mode .wy-side-nav-search {
22 | background-color: #22272e;
23 | color: #cfcfcf;
24 | }
25 |
26 | /* Headings */
27 | body.dark-mode h1,
28 | body.dark-mode h2,
29 | body.dark-mode h3,
30 | body.dark-mode h4 {
31 | color: #ffffff;
32 | }
33 |
34 | /* Links */
35 | body.dark-mode a {
36 | color: #79b8ff;
37 | }
38 |
39 | /* Code blocks */
40 | body.dark-mode pre,
41 | body.dark-mode code {
42 | background-color: #2d333b;
43 | color: #f0f0f0;
44 | }
45 |
46 | /* General REPL Python output */
47 | body.dark-mode pre.highlight,
48 | body.dark-mode code.highlight {
49 | background-color: #2d333b;
50 | color: #f0f0f0; /* Ensures all text in REPL blocks is visible */
51 | }
52 |
53 | /* Handle the '>>>', '...' prompts */
54 | body.dark-mode .highlight .gp {
55 | color: #79b8ff; /* Color for REPL prompts like '>>>' */
56 | }
57 |
58 | /* Handle REPL output */
59 | body.dark-mode .highlight .go {
60 | color: #d5a476; /* Distinct color for REPL outputs */
61 | }
62 |
63 | /* Decorators (e.g., @dataclass) */
64 | body.dark-mode .highlight .nd {
65 | color: rgba(192, 144, 2, 0.87); /* Dark, burnished gold for decorators */
66 | }
67 |
68 | /* Operators (e.g., ==, +, -, etc.) */
69 | body.dark-mode .highlight .o {
70 | color: #d5a476; /* Match your REPL output lighter gold */
71 | }
72 |
73 | /* Punctuation (e.g., . , ( )) */
74 | body.dark-mode .highlight .p {
75 | color: #cfcfcf; /* Neutral light gray for punctuation */
76 | }
77 |
78 | /* Built-in types and constants (e.g., str, int, True, False) */
79 | body.dark-mode .highlight .nb {
80 | color: #4ec9b0; /* Teal for built-in types/constants */
81 | }
82 |
83 | /* Function and variable names */
84 | body.dark-mode .highlight .nf,
85 | body.dark-mode .highlight .n {
86 | color: #9cdcfe; /* Light blue for function/variable names */
87 | }
88 |
89 | /* General admonition block */
90 | body.dark-mode .admonition {
91 | background-color: #2e3b4e; /* Neutral dark background */
92 | color: #b0b0b0; /* Softer silver text */
93 | border-left: 4px solid #79b8ff; /* Default blue accent */
94 | padding: 10px;
95 | border-radius: 6px; /* Rounded corners */
96 | }
97 |
98 | /* Title of admonition blocks */
99 | body.dark-mode .admonition .admonition-title {
100 | color: #79b8ff; /* Bright title text for clarity */
101 | font-weight: bold;
102 | }
103 |
104 | /* Specific styles for ..warning:: */
105 | body.dark-mode .admonition.warning {
106 | background-color: #4a3224; /* Warm dark terracotta */
107 | border-left-color: #d8845e; /* Subdued orange for less vibrancy */
108 | color: #d3b8a6; /* Soft beige text for a smoother contrast */
109 | }
110 |
111 | /* Specific styles for ..note:: */
112 | body.dark-mode .admonition.note {
113 | background-color: #4b4430; /* Subdued dark olive-brown background */
114 | border-left-color: #bfa45e; /* Muted goldenrod border */
115 | color: #d4c8a8; /* Softer light tan text to reduce glare */
116 | }
117 |
118 | /* Specific styles for ..tip:: */
119 | body.dark-mode .admonition.tip {
120 | background-color: #2b4e4e; /* Teal background */
121 | border-left-color: #56b6c2; /* Cyan border for tips */
122 | color: #d8e0e0; /* Softer light teal text */
123 | }
124 |
125 | /* Specific styles for ..important:: */
126 | body.dark-mode .admonition.important {
127 | background-color: #4e3b2b; /* Brownish background */
128 | border-left-color: #d19a66; /* Amber border for important */
129 | color: #e0d6d1; /* Softer light beige text */
130 | }
131 |
132 | /* Highlighting inline code within admonitions */
133 | body.dark-mode .admonition code {
134 | background-color: #2d333b;
135 | color: #f0f0f0;
136 | padding: 2px 4px;
137 | border-radius: 4px;
138 | }
139 |
--------------------------------------------------------------------------------
/docs/dataclass_wizard.rst:
--------------------------------------------------------------------------------
1 | dataclass\_wizard package
2 | =========================
3 |
4 | Subpackages
5 | -----------
6 |
7 | .. toctree::
8 | :maxdepth: 4
9 |
10 | dataclass_wizard.environ
11 | dataclass_wizard.utils
12 | dataclass_wizard.v1
13 | dataclass_wizard.wizard_cli
14 |
15 | Submodules
16 | ----------
17 |
18 | dataclass\_wizard.abstractions module
19 | -------------------------------------
20 |
21 | .. automodule:: dataclass_wizard.abstractions
22 | :members:
23 | :undoc-members:
24 | :show-inheritance:
25 |
26 | dataclass\_wizard.bases module
27 | ------------------------------
28 |
29 | .. automodule:: dataclass_wizard.bases
30 | :members:
31 | :undoc-members:
32 | :show-inheritance:
33 |
34 | dataclass\_wizard.bases\_meta module
35 | ------------------------------------
36 |
37 | .. automodule:: dataclass_wizard.bases_meta
38 | :members:
39 | :undoc-members:
40 | :show-inheritance:
41 |
42 | dataclass\_wizard.class\_helper module
43 | --------------------------------------
44 |
45 | .. automodule:: dataclass_wizard.class_helper
46 | :members:
47 | :undoc-members:
48 | :show-inheritance:
49 |
50 | dataclass\_wizard.constants module
51 | ----------------------------------
52 |
53 | .. automodule:: dataclass_wizard.constants
54 | :members:
55 | :undoc-members:
56 | :show-inheritance:
57 |
58 | dataclass\_wizard.decorators module
59 | -----------------------------------
60 |
61 | .. automodule:: dataclass_wizard.decorators
62 | :members:
63 | :undoc-members:
64 | :show-inheritance:
65 |
66 | dataclass\_wizard.dumpers module
67 | --------------------------------
68 |
69 | .. automodule:: dataclass_wizard.dumpers
70 | :members:
71 | :undoc-members:
72 | :show-inheritance:
73 |
74 | dataclass\_wizard.enums module
75 | ------------------------------
76 |
77 | .. automodule:: dataclass_wizard.enums
78 | :members:
79 | :undoc-members:
80 | :show-inheritance:
81 |
82 | dataclass\_wizard.errors module
83 | -------------------------------
84 |
85 | .. automodule:: dataclass_wizard.errors
86 | :members:
87 | :undoc-members:
88 | :show-inheritance:
89 |
90 | dataclass\_wizard.lazy\_imports module
91 | --------------------------------------
92 |
93 | .. automodule:: dataclass_wizard.lazy_imports
94 | :members:
95 | :undoc-members:
96 | :show-inheritance:
97 |
98 | dataclass\_wizard.loader\_selection module
99 | ------------------------------------------
100 |
101 | .. automodule:: dataclass_wizard.loader_selection
102 | :members:
103 | :undoc-members:
104 | :show-inheritance:
105 |
106 | dataclass\_wizard.loaders module
107 | --------------------------------
108 |
109 | .. automodule:: dataclass_wizard.loaders
110 | :members:
111 | :undoc-members:
112 | :show-inheritance:
113 |
114 | dataclass\_wizard.log module
115 | ----------------------------
116 |
117 | .. automodule:: dataclass_wizard.log
118 | :members:
119 | :undoc-members:
120 | :show-inheritance:
121 |
122 | dataclass\_wizard.models module
123 | -------------------------------
124 |
125 | .. automodule:: dataclass_wizard.models
126 | :members:
127 | :undoc-members:
128 | :show-inheritance:
129 |
130 | dataclass\_wizard.parsers module
131 | --------------------------------
132 |
133 | .. automodule:: dataclass_wizard.parsers
134 | :members:
135 | :undoc-members:
136 | :show-inheritance:
137 |
138 | dataclass\_wizard.property\_wizard module
139 | -----------------------------------------
140 |
141 | .. automodule:: dataclass_wizard.property_wizard
142 | :members:
143 | :undoc-members:
144 | :show-inheritance:
145 |
146 | dataclass\_wizard.serial\_json module
147 | -------------------------------------
148 |
149 | .. automodule:: dataclass_wizard.serial_json
150 | :members:
151 | :undoc-members:
152 | :show-inheritance:
153 |
154 | dataclass\_wizard.type\_def module
155 | ----------------------------------
156 |
157 | .. automodule:: dataclass_wizard.type_def
158 | :members:
159 | :undoc-members:
160 | :show-inheritance:
161 |
162 | dataclass\_wizard.wizard\_mixins module
163 | ---------------------------------------
164 |
165 | .. automodule:: dataclass_wizard.wizard_mixins
166 | :members:
167 | :undoc-members:
168 | :show-inheritance:
169 |
170 | Module contents
171 | ---------------
172 |
173 | .. automodule:: dataclass_wizard
174 | :members:
175 | :undoc-members:
176 | :show-inheritance:
177 |
--------------------------------------------------------------------------------
/dataclass_wizard/wizard_mixins.pyi:
--------------------------------------------------------------------------------
1 | __all__ = ['JSONListWizard',
2 | 'JSONFileWizard',
3 | 'TOMLWizard',
4 | 'YAMLWizard']
5 |
6 | import json
7 | from os import PathLike
8 | from typing import AnyStr, TextIO, BinaryIO, Union, TypeAlias
9 |
10 | from .abstractions import W
11 | from .enums import LetterCase
12 | from .models import Container
13 | from .serial_json import JSONSerializable, SerializerHookMixin
14 | from .type_def import (T, ListOfJSONObject,
15 | Encoder, Decoder, FileDecoder, FileEncoder, ParseFloat)
16 |
17 |
18 | # A type that can be string or `path.Path`
19 | # https://stackoverflow.com/a/78070015/10237506
20 | # A type that can be string, bytes, or `PathLike`
21 | FileType: TypeAlias = str | bytes | PathLike
22 |
23 |
24 | class JSONListWizard(JSONSerializable, str=False):
25 |
26 | @classmethod
27 | def from_json(cls: type[W], string: AnyStr, *,
28 | decoder: Decoder = json.loads,
29 | **decoder_kwargs) -> W | Container[W]:
30 |
31 | ...
32 |
33 | @classmethod
34 | def from_list(cls: type[W], o: ListOfJSONObject) -> Container[W]:
35 | ...
36 |
37 |
38 | class JSONFileWizard(SerializerHookMixin):
39 |
40 | @classmethod
41 | def from_json_file(cls: type[T], file: FileType, *,
42 | decoder: FileDecoder = json.load,
43 | **decoder_kwargs) -> T | list[T]:
44 | ...
45 |
46 | def to_json_file(self: T, file: FileType, mode: str = 'w',
47 | encoder: FileEncoder = json.dump,
48 | **encoder_kwargs) -> None:
49 | ...
50 |
51 |
52 | class TOMLWizard(SerializerHookMixin):
53 |
54 | def __init_subclass__(cls, key_transform=LetterCase.NONE):
55 | ...
56 |
57 | @classmethod
58 | def from_toml(cls: type[T],
59 | string_or_stream: AnyStr | BinaryIO, *,
60 | decoder: Decoder | None = None,
61 | header: str = 'items',
62 | parse_float: ParseFloat = float) -> T | list[T]:
63 | ...
64 |
65 | @classmethod
66 | def from_toml_file(cls: type[T], file: FileType, *,
67 | decoder: FileDecoder | None = None,
68 | header: str = 'items',
69 | parse_float: ParseFloat = float) -> T | list[T]:
70 | ...
71 |
72 | def to_toml(self: T,
73 | /,
74 | *encoder_args,
75 | encoder: Encoder | None = None,
76 | multiline_strings: bool = False,
77 | indent: int = 4) -> AnyStr:
78 | ...
79 |
80 | def to_toml_file(self: T, file: FileType, mode: str = 'wb',
81 | encoder: FileEncoder | None = None,
82 | multiline_strings: bool = False,
83 | indent: int = 4) -> None:
84 | ...
85 |
86 | @classmethod
87 | def list_to_toml(cls: type[T],
88 | instances: list[T],
89 | header: str = 'items',
90 | encoder: Encoder | None = None,
91 | **encoder_kwargs) -> AnyStr:
92 | ...
93 |
94 |
95 | class YAMLWizard(SerializerHookMixin):
96 |
97 | def __init_subclass__(cls, key_transform=LetterCase.LISP):
98 | ...
99 |
100 | @classmethod
101 | def from_yaml(cls: type[T],
102 | string_or_stream: AnyStr | TextIO | BinaryIO, *,
103 | decoder: Decoder | None = None,
104 | **decoder_kwargs) -> T | list[T]:
105 | ...
106 |
107 | @classmethod
108 | def from_yaml_file(cls: type[T], file: FileType, *,
109 | decoder: FileDecoder | None = None,
110 | **decoder_kwargs) -> T | list[T]:
111 | ...
112 |
113 | def to_yaml(self: T, *,
114 | encoder: Encoder | None = None,
115 | **encoder_kwargs) -> AnyStr:
116 | ...
117 |
118 | def to_yaml_file(self: T, file: FileType, mode: str = 'w',
119 | encoder: FileEncoder | None = None,
120 | **encoder_kwargs) -> None:
121 | ...
122 |
123 | @classmethod
124 | def list_to_yaml(cls: type[T],
125 | instances: list[T],
126 | encoder: Encoder | None = None,
127 | **encoder_kwargs) -> AnyStr:
128 | ...
129 |
--------------------------------------------------------------------------------
/dataclass_wizard/bases_meta.pyi:
--------------------------------------------------------------------------------
1 | """
2 | Ideally should be in the `bases` module, however we'll run into a Circular
3 | Import scenario if we move it there, since the `loaders` and `dumpers` modules
4 | both import directly from `bases`.
5 |
6 | """
7 | from dataclasses import MISSING
8 | from datetime import tzinfo
9 | from typing import Sequence, Callable, Any, Mapping, Literal
10 |
11 | from .bases import AbstractMeta, META, AbstractEnvMeta, V1TypeToHook
12 | from .constants import TAG
13 | from .enums import DateTimeTo, LetterCase, LetterCasePriority
14 | from .v1.enums import KeyAction, KeyCase, DateTimeTo as V1DateTimeTo
15 | from .models import Condition
16 | from .type_def import E, EnvFileType
17 |
18 | _ALLOWED_MODES = Literal['runtime', 'v1_codegen']
19 |
20 | # global flag to determine if debug mode was ever enabled
21 | _debug_was_enabled = False
22 |
23 | V1HookFn = Callable[..., Any]
24 |
25 | def register_type(cls, tp: type, *,
26 | load: 'V1HookFn | None' = None,
27 | dump: 'V1HookFn | None' = None,
28 | mode: str | None = None) -> None: ...
29 |
30 |
31 | def _enable_debug_mode_if_needed(cls_loader, possible_lvl: bool | int | str):
32 | ...
33 |
34 |
35 | def _as_enum_safe(cls: type, name: str, base_type: type[E]) -> E | None:
36 | ...
37 |
38 |
39 | class BaseJSONWizardMeta(AbstractMeta):
40 |
41 | __slots__ = ()
42 |
43 | @classmethod
44 | def _init_subclass(cls):
45 | ...
46 |
47 | @classmethod
48 | def bind_to(cls, dataclass: type, create=True, is_default=True,
49 | base_loader=None, base_dumper=None):
50 | ...
51 |
52 |
53 | class BaseEnvWizardMeta(AbstractEnvMeta):
54 |
55 | __slots__ = ()
56 |
57 | @classmethod
58 | def _init_subclass(cls):
59 | ...
60 |
61 | @classmethod
62 | def bind_to(cls, env_class: type, create=True, is_default=True):
63 | ...
64 |
65 |
66 | # noinspection PyPep8Naming
67 | def LoadMeta(*, debug_enabled: 'bool | int | str' = MISSING,
68 | recursive: bool = True,
69 | recursive_classes: bool = MISSING,
70 | raise_on_unknown_json_key: bool = MISSING,
71 | json_key_to_field: dict[str, str] = MISSING,
72 | key_transform: LetterCase | str = MISSING,
73 | tag: str = MISSING,
74 | tag_key: str = TAG,
75 | auto_assign_tags: bool = MISSING,
76 | v1: bool = MISSING,
77 | v1_debug: bool | int | str = False,
78 | v1_type_to_load_hook: V1TypeToHook = None,
79 | v1_type_to_dump_hook: V1TypeToHook = None,
80 | v1_case: KeyCase | str | None = MISSING,
81 | v1_field_to_alias: dict[str, str | Sequence[str]] = MISSING,
82 | v1_on_unknown_key: KeyAction | str | None = KeyAction.IGNORE,
83 | v1_unsafe_parse_dataclass_in_union: bool = MISSING) -> META:
84 | ...
85 |
86 |
87 | # noinspection PyPep8Naming
88 | def DumpMeta(*, debug_enabled: 'bool | int | str' = MISSING,
89 | recursive: bool = True,
90 | marshal_date_time_as: DateTimeTo | str = MISSING,
91 | key_transform: LetterCase | str = MISSING,
92 | tag: str = MISSING,
93 | skip_defaults: bool = MISSING,
94 | skip_if: Condition = MISSING,
95 | skip_defaults_if: Condition = MISSING,
96 | v1: bool = MISSING,
97 | v1_debug: bool | int | str = False,
98 | v1_case: KeyCase | str | None = MISSING,
99 | v1_field_to_alias: dict[str, str | Sequence[str]] = MISSING,
100 | v1_dump_date_time_as: V1DateTimeTo | str = MISSING,
101 | v1_assume_naive_datetime_tz: tzinfo | None = None,
102 | ) -> META:
103 | ...
104 |
105 |
106 | # noinspection PyPep8Naming
107 | def EnvMeta(*, debug_enabled: 'bool | int | str' = MISSING,
108 | env_file: EnvFileType = MISSING,
109 | env_prefix: str = MISSING,
110 | secrets_dir: 'EnvFileType | Sequence[EnvFileType]' = MISSING,
111 | field_to_env_var: dict[str, str] = MISSING,
112 | key_lookup_with_load: LetterCasePriority | str = LetterCasePriority.SCREAMING_SNAKE,
113 | key_transform_with_dump: LetterCase | str = LetterCase.SNAKE,
114 | # marshal_date_time_as: DateTimeTo | str = MISSING,
115 | skip_defaults: bool = MISSING,
116 | skip_if: Condition = MISSING,
117 | skip_defaults_if: Condition = MISSING,
118 | ) -> META:
119 | ...
120 |
--------------------------------------------------------------------------------
/Makefile:
--------------------------------------------------------------------------------
1 | .PHONY: clean clean-test clean-pyc clean-build docs help bump-patch bump-minor bump-major bump-patch-dry
2 | .DEFAULT_GOAL := help
3 |
4 | define BROWSER_PYSCRIPT
5 | import os, webbrowser, sys
6 |
7 | from urllib.request import pathname2url
8 |
9 | webbrowser.open("file://" + pathname2url(os.path.abspath(sys.argv[1])))
10 | endef
11 | export BROWSER_PYSCRIPT
12 |
13 | define PRINT_HELP_PYSCRIPT
14 | import re, sys
15 |
16 | for line in sys.stdin:
17 | match = re.match(r'^([a-zA-Z_-]+):.*?## (.*)$$', line)
18 | if match:
19 | target, help = match.groups()
20 | print("%-20s %s" % (target, help))
21 | endef
22 | export PRINT_HELP_PYSCRIPT
23 |
24 | BROWSER := python -c "$$BROWSER_PYSCRIPT"
25 |
26 | help:
27 | @python -c "$$PRINT_HELP_PYSCRIPT" < $(MAKEFILE_LIST)
28 |
29 | init: ## install all dev dependencies for this project
30 | pip install -e .[dev]
31 | python -m pip install pre-commit build twine
32 | pre-commit install
33 |
34 | bump-patch:
35 | bump-my-version bump patch
36 |
37 | bump-minor:
38 | bump-my-version bump minor
39 |
40 | bump-major:
41 | bump-my-version bump major
42 |
43 | bump-patch-dry:
44 | bump-my-version bump patch --dry-run --verbose
45 |
46 | clean: clean-build clean-pyc clean-test ## remove all build, test, coverage and Python artifacts
47 |
48 | clean-build: ## remove build artifacts
49 | rm -fr build/
50 | rm -fr dist/
51 | rm -fr .eggs/
52 | find . -name '*.egg-info' -exec rm -fr {} +
53 | find . -name '*.egg' -type f -exec rm -f {} +
54 |
55 | clean-pyc: ## remove Python file artifacts
56 | find . -name '*.pyc' -exec rm -f {} +
57 | find . -name '*.pyo' -exec rm -f {} +
58 | find . -name '*~' -exec rm -f {} +
59 | find . -name '__pycache__' -exec rm -fr {} +
60 |
61 | clean-test: ## remove test and coverage artifacts
62 | rm -fr .tox/
63 | rm -f .coverage
64 | rm -fr htmlcov/
65 | rm -fr .pytest_cache
66 |
67 | lint: ## check style with flake8 and pylint
68 | flake8 dataclass_wizard tests
69 | pylint dataclass_wizard tests
70 |
71 | test: ## run unit tests quickly with the default Python
72 | pytest -v --cov=dataclass_wizard --cov-report=term-missing tests/unit
73 |
74 | test-vb: ## run unit tests (in verbose mode) with the default Python
75 | pytest -vvv --log-cli-level=DEBUG --capture=tee-sys --cov=dataclass_wizard --cov-report=term-missing tests/unit
76 |
77 | test-all: ## run tests on every Python version with tox
78 | tox
79 |
80 | coverage: ## check code coverage with unit tests quickly with the default Python
81 | coverage run --source dataclass_wizard -m pytest tests/unit
82 | coverage report -m
83 | coverage html
84 | $(BROWSER) htmlcov/index.html
85 |
86 | docs: ## generate Sphinx HTML documentation, including API docs
87 | rm -f docs/dataclass_wizard.rst
88 | rm -f docs/modules.rst
89 | sphinx-apidoc -o docs/ dataclass_wizard
90 | $(MAKE) -C docs clean
91 | $(MAKE) -C docs html
92 | $(BROWSER) docs/_build/html/index.html
93 |
94 | servedocs: docs ## compile the docs watching for changes
95 | watchmedo shell-command -p '*.rst' -c '$(MAKE) -C docs html' -R -D .
96 |
97 | release: dist ## package and upload a release
98 | twine upload dist/*
99 |
100 | check-dist:
101 | python -m build
102 | python -m twine check dist/*
103 |
104 | check: dist-local ## verify release before upload to PyPI
105 | twine check dist/*
106 |
107 | dist: clean ## builds source and wheel package
108 | pip install build
109 | python -m build
110 | ls -l dist
111 |
112 | dist-local: clean replace_version ## builds source and wheel package (for local testing)
113 | pip install build
114 | python -m build
115 | ls -l dist
116 | $(MAKE) revert_readme
117 |
118 | replace_version: ## replace |version| in README.rst with the current version
119 | cp README.rst README.rst.bak
120 | python -c "import re; \
121 | from pathlib import Path; \
122 | version = re.search(r\"__version__\\s*=\\s*'(.+?)'\", Path('dataclass_wizard/__version__.py').read_text()).group(1); \
123 | readme_path = Path('README.rst'); \
124 | readme_content = readme_path.read_text(); \
125 | readme_path.write_text(readme_content.replace('|version|', version)); \
126 | print(f'Replaced version in {readme_path}: {version}')"
127 |
128 | revert_readme: ## revert README.rst to its original state
129 | mv README.rst.bak README.rst
130 |
131 | install: clean ## install the package to the active Python's site-packages
132 | pip install .
133 |
134 | dist-conda: clean ## builds source and wheel package for Anaconda
135 | conda build .
136 |
137 | release-conda: dist-conda ## package and upload a release to Anaconda
138 | $(eval DIST_FILE=$(shell conda build . --output))
139 | anaconda upload $(DIST_FILE)
140 |
--------------------------------------------------------------------------------
/dataclass_wizard/utils/dict_helper.py:
--------------------------------------------------------------------------------
1 | """
2 | Dict helper module
3 | """
4 |
5 |
6 | class NestedDict(dict):
7 | """
8 | A dictionary that automatically creates nested dictionaries for missing keys.
9 |
10 | This class extends the built-in `dict` to simplify working with deeply nested structures.
11 | If a key is accessed but does not exist, it will be created automatically with a new `NestedDict` as its value.
12 |
13 | Source: https://stackoverflow.com/a/5369984/10237506
14 |
15 | Example:
16 | >>> nd = NestedDict()
17 | >>> nd['a']['b']['c'] = 42
18 | >>> nd
19 | {'a': {'b': {'c': 42}}}
20 |
21 | >>> nd['x']['y']
22 | {}
23 | """
24 |
25 | __slots__ = ()
26 |
27 | def __getitem__(self, key):
28 | """
29 | Retrieve the value for a key, or create a nested dictionary for missing keys.
30 |
31 | Args:
32 | key (Hashable): The key to retrieve or create.
33 |
34 | Returns:
35 | Any: The value associated with the key, or a new `NestedDict` for missing keys.
36 |
37 | Example:
38 | >>> nd = NestedDict()
39 | >>> nd['foo'] # Creates a new NestedDict for 'foo'
40 | {}
41 |
42 | Note:
43 | If the key exists, its value is returned. Otherwise, a new `NestedDict` is created,
44 | stored, and returned.
45 | """
46 | if key in self: return self.get(key)
47 | return self.setdefault(key, NestedDict())
48 |
49 |
50 | class DictWithLowerStore(dict):
51 | """
52 | A ``dict``-like object with a lower-cased key store.
53 |
54 | All keys are expected to be strings. The structure remembers the
55 | case of the lower-cased key to be set, and methods like ``get()``
56 | and ``get_key()`` will use the lower-cased store. However, querying
57 | and contains testing is case sensitive::
58 |
59 | dls = DictWithLowerStore()
60 | dls['Accept'] = 'application/json'
61 | dls['aCCEPT'] == 'application/json' # False (raises KeyError)
62 | dls['Accept'] == 'application/json' # True
63 | dls.get('aCCEPT') == 'application/json' # True
64 |
65 | dls.get_key('aCCEPT') == 'Accept' # True
66 | list(dls) == ['Accept'] # True
67 |
68 | .. NOTE::
69 | I don't want to use the `CaseInsensitiveDict` from
70 | `request.structures`, because it turns out the lookup via that dict
71 | implementation is rather slow. So this version is somewhat of a
72 | trade-off, where I retain the same speed on lookups as a plain `dict`,
73 | but I also have a lower-cased key store, in case I ever need to use it.
74 |
75 | """
76 | __slots__ = ('_lower_store', )
77 |
78 | def __init__(self, data=None, **kwargs):
79 | super().__init__()
80 | self._lower_store = {}
81 | if data is None:
82 | data = {}
83 | self.update(data, **kwargs)
84 |
85 | def __setitem__(self, key, value):
86 | super().__setitem__(key, value)
87 | # Store the lower-cased key for lookups via `get`. Also store the
88 | # actual key alongside the value.
89 | self._lower_store[key.lower()] = (key, value)
90 |
91 | def get_key(self, key) -> str:
92 | """Return the original cased key"""
93 | return self._lower_store[key.lower()][0]
94 |
95 | def get(self, key):
96 | """
97 | Do a case-insensitive lookup. This lower-cases `key` and looks up
98 | from the lower-cased key store.
99 | """
100 | try:
101 | return self.__getitem__(key)
102 | except KeyError:
103 | return self._lower_store[key.lower()][1]
104 |
105 | def __delitem__(self, key):
106 | lower_key = key.lower()
107 | actual_key, _ = self._lower_store[lower_key]
108 |
109 | del self[actual_key]
110 | del self._lower_store[lower_key]
111 |
112 | def lower_items(self):
113 | """Like iteritems(), but with all lowercase keys."""
114 | return (
115 | (lowerkey, keyval[1])
116 | for (lowerkey, keyval)
117 | in self._lower_store.items()
118 | )
119 |
120 | def __eq__(self, other):
121 | if isinstance(other, dict):
122 | other = DictWithLowerStore(other)
123 | else:
124 | return NotImplemented
125 | # Compare insensitively
126 | return dict(self.lower_items()) == dict(other.lower_items())
127 |
128 | def update(self, *args, **kwargs):
129 | if len(args) > 1:
130 | raise TypeError("update expected at most 1 arguments, got %d" % len(args))
131 | other = dict(*args, **kwargs)
132 | for key in other:
133 | self[key] = other[key]
134 |
135 | def copy(self):
136 | return DictWithLowerStore(self._lower_store.values())
137 |
138 | def __repr__(self):
139 | return str(dict(self.items()))
140 |
--------------------------------------------------------------------------------
/tests/unit/v1/test_hooks.py:
--------------------------------------------------------------------------------
1 | from __future__ import annotations
2 |
3 | import pytest
4 |
5 | from dataclasses import dataclass
6 | from ipaddress import IPv4Address
7 |
8 | from dataclass_wizard import register_type, JSONWizard, LoadMeta, fromdict, asdict
9 | from dataclass_wizard.errors import ParseError
10 | from dataclass_wizard.v1 import DumpMixin, LoadMixin
11 | from dataclass_wizard.v1.models import TypeInfo, Extras
12 |
13 |
14 | def test_v1_register_type_ipv4address_roundtrip():
15 |
16 | @dataclass
17 | class Foo(JSONWizard):
18 | class Meta(JSONWizard.Meta):
19 | v1 = True
20 |
21 | b: bytes = b""
22 | s: str | None = None
23 | c: IPv4Address | None = None
24 |
25 | Foo.register_type(IPv4Address)
26 |
27 | data = {"b": "AAAA", "c": "127.0.0.1", "s": "foobar"}
28 |
29 | foo = Foo.from_dict(data)
30 | assert foo.c == IPv4Address("127.0.0.1")
31 |
32 | assert foo.to_dict() == data
33 | assert Foo.from_dict(foo.to_dict()).to_dict() == data
34 |
35 |
36 | def test_v1_ipv4address_without_hook_raises_parse_error():
37 |
38 | @dataclass
39 | class Foo(JSONWizard):
40 | class Meta(JSONWizard.Meta):
41 | v1 = True
42 |
43 | c: IPv4Address | None = None
44 |
45 | data = {"c": "127.0.0.1"}
46 |
47 | with pytest.raises(ParseError) as e:
48 | Foo.from_dict(data)
49 |
50 | assert e.value.phase == 'load'
51 |
52 | msg = str(e.value)
53 | assert "field `c`" in msg
54 | assert "not currently supported" in msg
55 | assert "IPv4Address" in msg
56 | assert "load" in msg.lower()
57 |
58 |
59 | def test_v1_meta_codegen_hooks_ipv4address_roundtrip():
60 |
61 | def load_to_ipv4_address(tp: TypeInfo, extras: Extras) -> str:
62 | return tp.wrap(tp.v(), extras)
63 |
64 | def dump_from_ipv4_address(tp: TypeInfo, extras: Extras) -> str:
65 | return f"str({tp.v()})"
66 |
67 | @dataclass
68 | class Foo(JSONWizard):
69 | class Meta(JSONWizard.Meta):
70 | v1 = True
71 | v1_type_to_load_hook = {IPv4Address: load_to_ipv4_address}
72 | v1_type_to_dump_hook = {IPv4Address: dump_from_ipv4_address}
73 |
74 | b: bytes = b""
75 | s: str | None = None
76 | c: IPv4Address | None = None
77 |
78 | data = {"b": "AAAA", "c": "127.0.0.1", "s": "foobar"}
79 |
80 | foo = Foo.from_dict(data)
81 | assert foo.c == IPv4Address("127.0.0.1")
82 |
83 | assert foo.to_dict() == data
84 | assert Foo.from_dict(foo.to_dict()).to_dict() == data
85 |
86 |
87 | def test_v1_meta_runtime_hooks_ipv4address_roundtrip():
88 |
89 | @dataclass
90 | class Foo(JSONWizard):
91 | class Meta(JSONWizard.Meta):
92 | v1 = True
93 | v1_type_to_load_hook = {IPv4Address: ('runtime', IPv4Address)}
94 | v1_type_to_dump_hook = {IPv4Address: ('runtime', str)}
95 |
96 | b: bytes = b""
97 | s: str | None = None
98 | c: IPv4Address | None = None
99 |
100 | data = {"b": "AAAA", "c": "127.0.0.1", "s": "foobar"}
101 |
102 | foo = Foo.from_dict(data)
103 | assert foo.c == IPv4Address("127.0.0.1")
104 |
105 | assert foo.to_dict() == data
106 | assert Foo.from_dict(foo.to_dict()).to_dict() == data
107 |
108 | # invalid modes should raise an error
109 | with pytest.raises(ValueError) as e:
110 | meta = LoadMeta(v1_type_to_load_hook={IPv4Address: ('RT', str)})
111 | meta.bind_to(Foo)
112 | assert "mode must be 'runtime' or 'v1_codegen' (got 'RT')" in str(e.value)
113 |
114 |
115 | def test_v1_register_type_no_inheritance_with_functional_api_roundtrip():
116 | @dataclass
117 | class Foo:
118 | b: bytes = b""
119 | s: str | None = None
120 | c: IPv4Address | None = None
121 |
122 | LoadMeta(v1=True).bind_to(Foo)
123 |
124 | register_type(Foo, IPv4Address)
125 |
126 | data = {"b": "AAAA", "c": "127.0.0.1", "s": "foobar"}
127 |
128 | foo = fromdict(Foo, data)
129 | assert foo.c == IPv4Address("127.0.0.1")
130 |
131 | assert asdict(foo) == data
132 | assert asdict(fromdict(Foo, asdict(foo))) == data
133 |
134 |
135 | def test_v1_ipv4address_hooks_with_load_and_dump_mixins_roundtrip():
136 | @dataclass
137 | class Foo(JSONWizard, DumpMixin, LoadMixin):
138 | class Meta(JSONWizard.Meta):
139 | v1 = True
140 |
141 | c: IPv4Address | None = None
142 |
143 | @classmethod
144 | def load_to_ipv4_address(cls, tp: TypeInfo, extras: Extras) -> str:
145 | return tp.wrap(tp.v(), extras)
146 |
147 | @classmethod
148 | def dump_from_ipv4_address(cls, tp: TypeInfo, extras: Extras) -> str:
149 | return f"str({tp.v()})"
150 |
151 | Foo.register_load_hook(IPv4Address, Foo.load_to_ipv4_address)
152 | Foo.register_dump_hook(IPv4Address, Foo.dump_from_ipv4_address)
153 |
154 | data = {"c": "127.0.0.1"}
155 |
156 | foo = Foo.from_dict(data)
157 | assert foo.c == IPv4Address("127.0.0.1")
158 |
159 | assert foo.to_dict() == data
160 | assert Foo.from_dict(foo.to_dict()).to_dict() == data
161 |
--------------------------------------------------------------------------------
/dataclass_wizard/__init__.py:
--------------------------------------------------------------------------------
1 | """
2 | Dataclass Wizard
3 | ~~~~~~~~~~~~~~~~
4 |
5 | Lightning-fast JSON wizardry for Python dataclasses — effortless
6 | serialization right out of the box!
7 |
8 | Sample Usage:
9 |
10 | >>> from dataclasses import dataclass, field
11 | >>> from datetime import datetime
12 | >>> from typing import Optional
13 | >>>
14 | >>> from dataclass_wizard import JSONSerializable, property_wizard
15 | >>>
16 | >>>
17 | >>> @dataclass
18 | >>> class MyClass(JSONSerializable, metaclass=property_wizard):
19 | >>>
20 | >>> my_str: Optional[str]
21 | >>> list_of_int: list[int] = field(default_factory=list)
22 | >>> # You can also define this as `my_dt`, however only the annotation
23 | >>> # will carry over in that case, since the value is re-declared by
24 | >>> # the property below.
25 | >>> _my_dt: datetime = datetime(2000, 1, 1)
26 | >>>
27 | >>> @property
28 | >>> def my_dt(self):
29 | >>> # A sample `getter` which returns the datetime with year set as 2010
30 | >>> if self._my_dt is not None:
31 | >>> return self._my_dt.replace(year=2010)
32 | >>> return self._my_dt
33 | >>>
34 | >>> @my_dt.setter
35 | >>> def my_dt(self, new_dt: datetime):
36 | >>> # A sample `setter` which sets the inverse (roughly) of the `month` and `day`
37 | >>> self._my_dt = new_dt.replace(month=13 - new_dt.month,
38 | >>> day=30 - new_dt.day)
39 | >>>
40 | >>>
41 | >>> string = '''{"myStr": 42, "listOFInt": [1, "2", 3]}'''
42 | >>> c = MyClass.from_json(string)
43 | >>> print(repr(c))
44 | >>> # prints:
45 | >>> # MyClass(
46 | >>> # my_str='42',
47 | >>> # list_of_int=[1, 2, 3],
48 | >>> # my_dt=datetime.datetime(2010, 12, 29, 0, 0)
49 | >>> # )
50 | >>> my_dict = {'My_Str': 'string', 'myDT': '2021-01-20T15:55:30Z'}
51 | >>> c = MyClass.from_dict(my_dict)
52 | >>> print(repr(c))
53 | >>> # prints:
54 | >>> # MyClass(
55 | >>> # my_str='string',
56 | >>> # list_of_int=[],
57 | >>> # my_dt=datetime.datetime(2010, 12, 10, 15, 55, 30,
58 | >>> # tzinfo=datetime.timezone.utc)
59 | >>> # )
60 | >>> print(c.to_json())
61 | >>> # prints:
62 | >>> # {"myStr": "string", "listOfInt": [], "myDt": "2010-12-10T15:55:30Z"}
63 |
64 | For full documentation and more advanced usage, please see
65 | .
66 |
67 | :copyright: (c) 2021-2025 by Ritvik Nag.
68 | :license: Apache 2.0, see LICENSE for more details.
69 | """
70 |
71 | __all__ = [
72 | # Base exports
73 | 'DataclassWizard',
74 | 'JSONSerializable',
75 | 'JSONPyWizard',
76 | 'JSONWizard',
77 | 'register_type',
78 | 'LoadMixin',
79 | 'DumpMixin',
80 | 'property_wizard',
81 | # Wizard Mixins
82 | 'EnvWizard',
83 | 'JSONListWizard',
84 | 'JSONFileWizard',
85 | 'TOMLWizard',
86 | 'YAMLWizard',
87 | # Helper serializer functions + meta config
88 | 'fromlist',
89 | 'fromdict',
90 | 'asdict',
91 | 'LoadMeta',
92 | 'DumpMeta',
93 | 'EnvMeta',
94 | # Models
95 | 'env_field',
96 | 'json_field',
97 | 'json_key',
98 | 'path_field',
99 | 'skip_if_field',
100 | 'KeyPath',
101 | 'Container',
102 | 'Pattern',
103 | 'DatePattern',
104 | 'TimePattern',
105 | 'DateTimePattern',
106 | 'CatchAll',
107 | 'SkipIf',
108 | 'SkipIfNone',
109 | 'EQ',
110 | 'NE',
111 | 'LT',
112 | 'LE',
113 | 'GT',
114 | 'GE',
115 | 'IS',
116 | 'IS_NOT',
117 | 'IS_TRUTHY',
118 | 'IS_FALSY',
119 | ]
120 |
121 | import logging
122 |
123 | from .bases_meta import LoadMeta, DumpMeta, EnvMeta, register_type
124 | from .constants import PACKAGE_NAME
125 | from .dumpers import DumpMixin, setup_default_dumper
126 | from .loaders import LoadMixin, setup_default_loader
127 | from .loader_selection import asdict, fromlist, fromdict
128 | from .models import (env_field, json_field, json_key, path_field, skip_if_field,
129 | KeyPath, Container,
130 | Pattern, DatePattern, TimePattern, DateTimePattern,
131 | CatchAll, SkipIf, SkipIfNone,
132 | EQ, NE, LT, LE, GT, GE, IS, IS_NOT, IS_TRUTHY, IS_FALSY)
133 | from .environ.wizard import EnvWizard
134 | from .property_wizard import property_wizard
135 | from .serial_json import DataclassWizard, JSONWizard, JSONPyWizard, JSONSerializable
136 | from .wizard_mixins import JSONListWizard, JSONFileWizard, TOMLWizard, YAMLWizard
137 |
138 |
139 | # Set up logging to ``/dev/null`` like a library is supposed to.
140 | # http://docs.python.org/3.3/howto/logging.html#configuring-logging-for-a-library
141 | logging.getLogger(PACKAGE_NAME).addHandler(logging.NullHandler())
142 |
143 | # Setup the default type hooks to use when converting `str` (json) or a Python
144 | # `dict` object to a `dataclass` instance.
145 | setup_default_loader()
146 |
147 | # Setup the default type hooks to use when converting `dataclass` instances to
148 | # a JSON `string` or a Python `dict` object.
149 | setup_default_dumper()
150 |
--------------------------------------------------------------------------------
/docs/common_use_cases/handling_unknown_json_keys.rst:
--------------------------------------------------------------------------------
1 | Handling Unknown JSON Keys
2 | ###########################
3 |
4 | When working with JSON data, you may encounter unknown or extraneous keys -- those that do not map to any defined dataclass fields.
5 | This guide explains the default behavior, how to raise errors for unknown keys, and how to capture them using a ``CatchAll`` field.
6 |
7 | Default Behavior
8 | ================
9 |
10 | By default, when unknown JSON keys are encountered during the de-serialization process
11 | (using ``from_dict`` or ``from_json``), the library emits a warning if *debug* mode is enabled
12 | and logging is properly configured. These keys are ignored and not included in the resulting object.
13 |
14 | However, you can customize this behavior to raise an error or capture unknown data.
15 |
16 | Raising Errors on Unknown Keys
17 | ==============================
18 |
19 | To enforce strict validation, you can configure the library to raise an error when
20 | unknown keys are encountered. This is useful when you need to ensure that all JSON
21 | data adheres to a specific schema.
22 |
23 | Example: Raising an Error
24 | --------------------------
25 |
26 | The example below demonstrates how to configure the library to raise a
27 | ``UnknownJSONKey`` error when unknown keys are encountered.
28 |
29 | .. code:: python3
30 |
31 | import logging
32 | from dataclasses import dataclass
33 |
34 | from dataclass_wizard import JSONWizard
35 | from dataclass_wizard.errors import UnknownJSONKey
36 |
37 | # Sets up application logging if we haven't already done so
38 | logging.basicConfig(level='INFO')
39 |
40 |
41 | @dataclass
42 | class Container(JSONWizard):
43 | class _(JSONWizard.Meta):
44 | debug_enabled = 'INFO'
45 | raise_on_unknown_json_key = True
46 |
47 | element: 'MyElement'
48 |
49 |
50 | @dataclass
51 | class MyElement:
52 | my_str: str
53 | my_float: float
54 |
55 |
56 | d = {
57 | 'element': {
58 | 'myStr': 'string',
59 | 'my_float': '1.23',
60 | 'my_bool': 'Testing' # This key is not mapped to a known dataclass field!
61 | }
62 | }
63 |
64 | try:
65 | c = Container.from_dict(d)
66 | except UnknownJSONKey as e:
67 | print('Error:', e)
68 |
69 | # Expected Output:
70 | # > Error: A JSON key is missing from the dataclass schema for class `MyElement`.
71 | # unknown key: 'my_bool'
72 | # dataclass fields: ['my_str', 'my_float']
73 | # input JSON object: {"myStr": "string", "my_float": "1.23", "my_bool": "Testing"}
74 |
75 | Capturing Unknown Keys with ``CatchAll``
76 | ========================================
77 |
78 | Starting from version **v0.29**, unknown JSON keys can be captured into a designated field
79 | using the ``CatchAll`` type. This allows you to store all unmapped key-value pairs for
80 | later use, without discarding them.
81 |
82 | Example: Capturing Unknown Keys
83 | -------------------------------
84 |
85 | The following example demonstrates how to use a ``CatchAll`` field to capture
86 | unknown JSON keys during de-serialization.
87 |
88 | .. code:: python
89 |
90 | from dataclasses import dataclass
91 | from dataclass_wizard import CatchAll, JSONWizard
92 |
93 |
94 | @dataclass
95 | class MyData(JSONWizard):
96 | class _(JSONWizard.Meta):
97 | skip_defaults = True
98 |
99 | my_str: str
100 | my_float: float
101 | extra_data: CatchAll = False # Initialize with a default value.
102 |
103 |
104 | # Case 1: JSON object with extra data
105 | input_dict = {
106 | 'my_str': "test",
107 | 'my_float': 3.14,
108 | 'my_other_str': "test!",
109 | 'my_bool': True
110 | }
111 |
112 | data = MyData.from_dict(input_dict)
113 |
114 | print(data.extra_data)
115 | # > {'my_other_str': 'test!', 'my_bool': True}
116 |
117 | # Save back to JSON
118 | output_dict = data.to_dict()
119 |
120 | print(output_dict)
121 | # > {'myStr': 'test', 'myFloat': 3.14, 'my_other_str': 'test!', 'my_bool': True}
122 |
123 | # Case 2: JSON object without extra data
124 | input_dict = {
125 | 'my_str': "test",
126 | 'my_float': 3.14,
127 | }
128 |
129 | data = MyData.from_dict(input_dict)
130 |
131 | print(data.extra_data)
132 | # > False
133 |
134 | Key Points:
135 | -----------
136 |
137 | - The ``extra_data`` field automatically captures all unknown JSON keys.
138 | - If no extra data is present, the field defaults to ``False`` in this example.
139 | - When serialized back to JSON, the extra data is retained.
140 |
141 | Best Practices
142 | ==============
143 |
144 | - Use ``raise_on_unknown_json_key`` when strict validation of JSON data is required.
145 | - Use ``CatchAll`` to gracefully handle dynamic or extensible JSON data structures.
146 | - Combine both features for advanced use cases, such as logging unknown keys
147 | while capturing them into a designated field.
148 |
149 | ---
150 |
151 | This guide offers a comprehensive overview of handling unknown JSON keys.
152 | By customizing the behavior, you can ensure your application works seamlessly
153 | with various JSON structures, whether strict or dynamic.
154 |
--------------------------------------------------------------------------------
/docs/python_compatibility.rst:
--------------------------------------------------------------------------------
1 | .. highlight:: shell
2 |
3 | ================
4 | Py Compatibility
5 | ================
6 |
7 | Python 3.9+
8 | -----------
9 |
10 | Just a quick note that even though this library supports Python 3.9+,
11 | some of the new features introduced in the latest Python
12 | versions might not be available from the ``typing`` module, depending on
13 | the Python version installed.
14 |
15 | To work around that, there's a great library called ``typing-extensions`` (you can
16 | find it on PyPI `here`_) that backports all the new
17 | ``typing`` features introduced so that earlier Python versions can also
18 | benefit from them. Note that the ``dataclass-wizard`` package already requires
19 | this dependency for **Python version 3.10 or earlier**, so there's no need
20 | to install this library separately.
21 |
22 | With the ``typing-extensions`` module, you can take advantage of the
23 | following new types from the ``typing`` module for Python 3.9+. Most of them are currently
24 | supported by the ``JSONSerializable`` class, however the ones that are *not*
25 | are marked with an asterisk (``*``) below.
26 |
27 | Introduced in *Python 3.10*:
28 | * `is_typeddict`_
29 | * `Concatenate`_
30 | * `ParamSpec`_
31 | * `TypeAlias`_
32 | * `TypeGuard`_
33 |
34 | Introduced in *Python 3.9*:
35 | * `Annotated`_ (added by `PEP 593`_)
36 |
37 | Introduced in *Python 3.8*:
38 | * `Literal`_
39 | * `TypedDict`_
40 | * `Final`_ ``*``
41 |
42 |
43 | ``*`` - Currently not supported by ``JSONSerializable`` at this time, though this
44 | may change in a future release.
45 |
46 | .. _here: https://pypi.org/project/typing-extensions/
47 | .. _Annotated: https://docs.python.org/3.9/library/typing.html#typing.Annotated
48 | .. _PEP 593: https://www.python.org/dev/peps/pep-0593/
49 | .. _Final: https://docs.python.org/3.8/library/typing.html#typing.Final
50 | .. _Literal: https://docs.python.org/3.8/library/typing.html#typing.Literal
51 | .. _TypedDict: https://docs.python.org/3.8/library/typing.html#typing.TypedDict
52 | .. _TypeAlias: https://docs.python.org/3/library/typing.html#typing.TypeAlias
53 | .. _Concatenate: https://docs.python.org/3/library/typing.html#typing.Concatenate
54 | .. _TypeGuard: https://docs.python.org/3/library/typing.html#typing.TypeGuard
55 | .. _ParamSpec: https://docs.python.org/3/library/typing.html#typing.ParamSpec
56 | .. _is_typeddict: https://docs.python.org/3/library/typing.html#typing.is_typeddict
57 |
58 | Importing the New Types
59 | ~~~~~~~~~~~~~~~~~~~~~~~
60 |
61 | You can import the new types (for example, the ones mentioned above) using the below
62 | syntax:
63 |
64 | .. code-block:: python3
65 |
66 | from typing_extensions import Literal, TypedDict, Annotated
67 |
68 |
69 | Python 3.7+
70 | -----------
71 |
72 | The Dataclass Wizard library supports the parsing of *future annotations* (also
73 | known as forward-declared annotations) which are enabled via a
74 | ``from __future__ import annotations`` import added at the top of a module; this
75 | declaration allows `PEP 585`_ and `PEP 604`_- style annotations to be used in
76 | Python 3.7 and higher. The one main benefit, is that static type checkers and
77 | IDEs such as PyCharm appear to have solid support for using new-style
78 | annotations in this way.
79 |
80 | The following Python code illustrates the paradigm of future annotations in
81 | Python 3.7+ code; notice that a ``__future__`` import is added at the top, for
82 | compatibility with versions earlier than 3.10. In the annotations, we also prefer
83 | to use parameterized standard collections, and the new pipe ``|`` syntax to
84 | represent ``Union`` and ``Optional`` types.
85 |
86 | .. code:: python3
87 |
88 | from __future__ import annotations
89 |
90 | import datetime
91 | from dataclasses import dataclass
92 | from decimal import Decimal
93 |
94 | from dataclass_wizard import JSONWizard
95 |
96 |
97 | @dataclass
98 | class A(JSONWizard):
99 | field_1: str | int | bool
100 | field_2: int | tuple[str | int] | bool
101 | field_3: Decimal | datetime.date | str
102 | field_4: str | int | None
103 | field_6: dict[str | int, list[B | C | D | None]]
104 |
105 |
106 | @dataclass
107 | class B:
108 | ...
109 |
110 |
111 | @dataclass
112 | class C:
113 | ...
114 |
115 |
116 | @dataclass
117 | class D:
118 | ...
119 |
120 | The Latest and Greatest
121 | -----------------------
122 |
123 | If you already have Python 3.10 or higher, you can leverage the new support for parameterized
124 | standard collections that was added as part of `PEP 585`_, as well as the ability to write
125 | Union types as ``X | Y`` which is introduced in `PEP 604`_, and avoid these imports from
126 | the ``typing`` module altogether:
127 |
128 | .. code:: python3
129 |
130 | from collections import defaultdict
131 | from dataclasses import dataclass
132 |
133 | from dataclass_wizard import JSONWizard
134 |
135 |
136 | @dataclass
137 | class MyClass(JSONWizard):
138 | my_list: list[str]
139 | my_dict: defaultdict[str, list[int]]
140 | my_tuple: tuple[int | str, ...]
141 |
142 |
143 | if __name__ == '__main__':
144 | data = {'my_list': ['testing'], 'my_dict': {'key': [1, 2, '3']}, 'my_tuple': (1, '2')}
145 |
146 | c = MyClass.from_dict(data)
147 |
148 | print(repr(c))
149 | # prints:
150 | # MyClass(my_list=['testing'], my_dict=defaultdict(, {'key': [1, 2, 3]}), my_tuple=(1, '2'))
151 |
152 |
153 | .. _PEP 585: https://www.python.org/dev/peps/pep-0585/
154 | .. _PEP 604: https://www.python.org/dev/peps/pep-0604/
155 |
--------------------------------------------------------------------------------
/CONTRIBUTING.rst:
--------------------------------------------------------------------------------
1 | .. highlight:: shell
2 |
3 | ============
4 | Contributing
5 | ============
6 |
7 | Contributions are welcome, and they are greatly appreciated! Every little bit
8 | helps, and credit will always be given.
9 |
10 | You can contribute in many ways:
11 |
12 | Types of Contributions
13 | ----------------------
14 |
15 | Report Bugs
16 | ~~~~~~~~~~~
17 |
18 | Report bugs at https://github.com/rnag/dataclass-wizard/issues.
19 |
20 | If you are reporting a bug, please include:
21 |
22 | * Your operating system name and version.
23 | * Any details about your local setup that might be helpful in troubleshooting.
24 | * Detailed steps to reproduce the bug.
25 |
26 | Fix Bugs
27 | ~~~~~~~~
28 |
29 | Look through the GitHub issues for bugs. Anything tagged with "bug" and "help
30 | wanted" is open to whoever wants to implement it.
31 |
32 | Implement Features
33 | ~~~~~~~~~~~~~~~~~~
34 |
35 | Look through the GitHub issues for features. Anything tagged with "enhancement"
36 | and "help wanted" is open to whoever wants to implement it.
37 |
38 | Write Documentation
39 | ~~~~~~~~~~~~~~~~~~~
40 |
41 | Dataclass Wizard could always use more documentation, whether as part of the
42 | official Dataclass Wizard docs, in docstrings, or even on the web in blog posts,
43 | articles, and such.
44 |
45 | Submit Feedback
46 | ~~~~~~~~~~~~~~~
47 |
48 | The best way to send feedback is to file an issue at https://github.com/rnag/dataclass-wizard/issues.
49 |
50 | If you are proposing a feature:
51 |
52 | * Explain in detail how it would work.
53 | * Keep the scope as narrow as possible, to make it easier to implement.
54 | * Remember that this is a volunteer-driven project, and that contributions
55 | are welcome :)
56 |
57 | Get Started!
58 | ------------
59 |
60 | Ready to contribute? Here's how to set up `dataclass-wizard` for local development.
61 |
62 | 1. Fork the `dataclass-wizard` repo on GitHub.
63 | 2. Clone your fork locally::
64 |
65 | $ git clone git@github.com:your_name_here/dataclass-wizard.git
66 |
67 | 3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development::
68 |
69 | $ mkvirtualenv dataclass-wizard
70 | $ cd dataclass-wizard/
71 | $ make init
72 |
73 | 4. Create a branch for local development::
74 |
75 | $ git checkout -b name-of-your-bugfix-or-feature
76 |
77 | Now you can make your changes locally.
78 |
79 | 5. When you're done making changes, check that your changes pass flake8 and the
80 | tests, including testing other Python versions with tox::
81 |
82 | $ make lint
83 | $ make test # or: see debug output with `make test-vb`
84 | $ tox
85 |
86 | To get flake8 and tox, just pip install them into your virtualenv.
87 |
88 | To instead run pytest in verbose mode `-vvv` and also show
89 | log output in terminal for debugging purposes, use::
90 |
91 | $ make test-vb
92 |
93 | 6. Commit your changes and push your branch to GitHub::
94 |
95 | $ git add .
96 | $ git commit -m "Your detailed description of your changes."
97 | $ git push origin name-of-your-bugfix-or-feature
98 |
99 | 7. Submit a pull request through the GitHub website.
100 |
101 | Pre-commit Hooks
102 | ----------------
103 |
104 | This project uses ``pre-commit`` to catch formatting, packaging, and
105 | documentation issues *before* they reach CI or PyPI.
106 |
107 | Setup (one-time)
108 | ~~~~~~~~~~~~~~~~
109 |
110 | Install the required tools and enable the git hooks:
111 |
112 | .. code-block:: bash
113 |
114 | python -m pip install pre-commit build twine
115 | pre-commit install
116 |
117 | After this, the hooks will run automatically on every commit.
118 |
119 | Running manually
120 | ~~~~~~~~~~~~~~~~
121 |
122 | To run all hooks against the entire repository (recommended after
123 | changing documentation or release metadata):
124 |
125 | .. code-block:: bash
126 |
127 | pre-commit run --all-files
128 |
129 | Pull Request Guidelines
130 | -----------------------
131 |
132 | Before you submit a pull request, check that it meets these guidelines:
133 |
134 | 1. The pull request should include tests.
135 | 2. If the pull request adds functionality, the docs should be updated. Put
136 | your new functionality into a function with a docstring, and add the
137 | feature to the list in README.rst.
138 | 3. The pull request should work for Python 3.9, 3.10, 3.11, 3.12, 3.13 and 3.14, and for PyPy. Check
139 | https://github.com/rnag/dataclass-wizard/actions/workflows/dev.yml
140 | and make sure that the tests pass for all supported Python versions.
141 |
142 | Tips
143 | ----
144 |
145 | To run a subset of tests::
146 |
147 | $ pytest tests/unit/test_dataclass_wizard.py::test_my_func
148 |
149 |
150 | Deploying
151 | ---------
152 |
153 | .. note:: **Tip:** The last command below is used to push both the commit and
154 | the new tag to the remote branch simultaneously. There is also a simpler
155 | alternative as mentioned in `this post`_, which involves running the following
156 | command::
157 |
158 | $ git config --global push.followTags true
159 |
160 | After that, you should be able to simply run the below command to push *both
161 | the commits and tags* simultaneously::
162 |
163 | $ git push
164 |
165 | A reminder for the maintainers on how to deploy.
166 | Make sure all your changes are committed (including an entry in HISTORY.rst).
167 | Then run::
168 |
169 | $ bump2version patch # possible: major / minor / patch
170 | $ git push && git push --tags
171 |
172 | GitHub Actions will then `deploy to PyPI`_ if tests pass.
173 |
174 | .. _`deploy to PyPI`: https://github.com/rnag/dataclass-wizard/actions/workflows/release.yml
175 | .. _`this post`: https://stackoverflow.com/questions/3745135/push-git-commits-tags-simultaneously
176 |
--------------------------------------------------------------------------------
/dataclass_wizard/environ/loaders.py:
--------------------------------------------------------------------------------
1 | from datetime import datetime, date, timezone
2 | from typing import (
3 | Type, Dict, List, Tuple, Iterable, Sequence,
4 | Union, AnyStr, Optional, Callable,
5 | )
6 |
7 | from ..abstractions import AbstractParser
8 | from ..bases import META
9 | from ..decorators import _single_arg_alias
10 | from ..loaders import LoadMixin, load_func_for_dataclass
11 | from ..type_def import (
12 | FrozenKeys, DefFactory, M, N, U, DD, LSQ, NT, T, JSONObject
13 | )
14 | from ..utils.type_conv import (
15 | as_datetime, as_date, as_list, as_dict
16 | )
17 |
18 |
19 | class EnvLoader(LoadMixin):
20 | """
21 | This Mixin class derives its name from the eponymous `json.loads`
22 | function. Essentially it contains helper methods to convert JSON strings
23 | (or a Python dictionary object) to a `dataclass` which can often contain
24 | complex types such as lists, dicts, or even other dataclasses nested
25 | within it.
26 |
27 | Refer to the :class:`AbstractLoader` class for documentation on any of the
28 | implemented methods.
29 |
30 | """
31 | __slots__ = ()
32 |
33 | def __init_subclass__(cls, **kwargs):
34 | super().__init_subclass__()
35 |
36 | cls.register_load_hook(bytes, cls.load_to_bytes)
37 | cls.register_load_hook(bytearray, cls.load_to_byte_array)
38 |
39 | @staticmethod
40 | def load_to_bytes(
41 | o: AnyStr, base_type: Type[bytes], encoding='utf-8') -> bytes:
42 |
43 | return base_type(o, encoding)
44 |
45 | @staticmethod
46 | def load_to_byte_array(
47 | o: AnyStr, base_type: Type[bytearray],
48 | encoding='utf-8') -> bytearray:
49 |
50 | return base_type(o, encoding) if isinstance(o, str) else base_type(o)
51 |
52 | @staticmethod
53 | @_single_arg_alias('base_type')
54 | def load_to_uuid(o: Union[AnyStr, U], base_type: Type[U]) -> U:
55 | # alias: base_type(o)
56 | ...
57 |
58 | @staticmethod
59 | def load_to_iterable(
60 | o: Iterable, base_type: Type[LSQ],
61 | elem_parser: AbstractParser) -> LSQ:
62 |
63 | return super(EnvLoader, EnvLoader).load_to_iterable(
64 | as_list(o), base_type, elem_parser)
65 |
66 | @staticmethod
67 | def load_to_tuple(
68 | o: Union[List, Tuple], base_type: Type[Tuple],
69 | elem_parsers: Sequence[AbstractParser]) -> Tuple:
70 |
71 | return super(EnvLoader, EnvLoader).load_to_tuple(
72 | as_list(o), base_type, elem_parsers)
73 |
74 | @staticmethod
75 | def load_to_named_tuple(
76 | o: Union[Dict, List, Tuple], base_type: Type[NT],
77 | field_to_parser: 'FieldToParser',
78 | field_parsers: List[AbstractParser]) -> NT:
79 |
80 | # TODO check for both list and dict
81 |
82 | return super(EnvLoader, EnvLoader).load_to_named_tuple(
83 | as_list(o), base_type, field_to_parser, field_parsers)
84 |
85 | @staticmethod
86 | def load_to_named_tuple_untyped(
87 | o: Union[Dict, List, Tuple], base_type: Type[NT],
88 | dict_parser: AbstractParser, list_parser: AbstractParser) -> NT:
89 |
90 | return super(EnvLoader, EnvLoader).load_to_named_tuple_untyped(
91 | as_list(o), base_type, dict_parser, list_parser)
92 |
93 | @staticmethod
94 | def load_to_dict(
95 | o: Dict, base_type: Type[M],
96 | key_parser: AbstractParser,
97 | val_parser: AbstractParser) -> M:
98 |
99 | return super(EnvLoader, EnvLoader).load_to_dict(
100 | as_dict(o), base_type, key_parser, val_parser)
101 |
102 | @staticmethod
103 | def load_to_defaultdict(
104 | o: Dict, base_type: Type[DD],
105 | default_factory: DefFactory,
106 | key_parser: AbstractParser,
107 | val_parser: AbstractParser) -> DD:
108 |
109 | return super(EnvLoader, EnvLoader).load_to_defaultdict(
110 | as_dict(o), base_type, default_factory, key_parser, val_parser)
111 |
112 | @staticmethod
113 | def load_to_typed_dict(
114 | o: Dict, base_type: Type[M],
115 | key_to_parser: 'FieldToParser',
116 | required_keys: FrozenKeys,
117 | optional_keys: FrozenKeys) -> M:
118 |
119 | return super(EnvLoader, EnvLoader).load_to_typed_dict(
120 | as_dict(o), base_type, key_to_parser, required_keys, optional_keys)
121 |
122 | @staticmethod
123 | def load_to_datetime(
124 | o: Union[str, N], base_type: Type[datetime]) -> datetime:
125 | if isinstance(o, str):
126 | # Check if it's a string in numeric format, like '1.23'
127 | if o.replace('.', '', 1).isdigit():
128 | return base_type.fromtimestamp(float(o), tz=timezone.utc)
129 |
130 | return base_type.fromisoformat(o.replace('Z', '+00:00', 1))
131 |
132 | # default: as_datetime
133 | return as_datetime(o, base_type)
134 |
135 | @staticmethod
136 | def load_to_date(o: Union[str, N], base_type: Type[date]) -> date:
137 | if isinstance(o, str):
138 | # Check if it's a string in numeric format, like '1.23'
139 | if o.replace('.', '', 1).isdigit():
140 | return base_type.fromtimestamp(float(o))
141 |
142 | return base_type.fromisoformat(o)
143 |
144 | # default: as_date
145 | return as_date(o, base_type)
146 |
147 | @staticmethod
148 | def load_func_for_dataclass(
149 | cls: Type[T],
150 | config: Optional[META],
151 | is_main_class: bool = False,
152 | ) -> Callable[['str | JSONObject | T', Type[T]], T]:
153 |
154 | load = load_func_for_dataclass(
155 | cls,
156 | is_main_class=False,
157 | config=config,
158 | # override the loader class
159 | loader_cls=EnvLoader,
160 | )
161 |
162 | def load_to_dataclass(o: 'str | JSONObject | T', *_) -> T:
163 | """
164 | Receives either a string or a `dict` as an input, and return a
165 | dataclass instance of type `cls`.
166 | """
167 | if type(o) is cls:
168 | return o
169 |
170 | return load(as_dict(o))
171 |
172 | return load_to_dataclass
173 |
--------------------------------------------------------------------------------
/docs/wiz_cli.rst:
--------------------------------------------------------------------------------
1 | .. highlight:: shell
2 |
3 | The CLI Tool
4 | ============
5 |
6 | The ``wiz`` command provides a companion CLI tool for the Dataclass Wizard,
7 | which further simplifies interaction with the Python ``dataclasses`` module.
8 |
9 | Getting help::
10 |
11 | $ wiz -h
12 | usage: wiz [-h] [-V] {gen-schema,gs} ...
13 |
14 | A companion CLI tool for the Dataclass Wizard, which simplifies interaction with the Python `dataclasses` module.
15 |
16 | positional arguments:
17 | {gen-schema,gs} Supported sub-commands
18 | gen-schema (gs)
19 | Generates a Python dataclass schema, given a JSON input.
20 |
21 | optional arguments:
22 | -h, --help show this help message and exit
23 | -V, --version Display the version of this tool.
24 |
25 | Checking the version of the CLI tool should display the currently installed
26 | version of the ``dataclass-wizard`` library::
27 |
28 | $ wiz -V
29 |
30 | To get help on a subcommand, simply use ``wiz -h``. For example::
31 |
32 | $ wiz gs -h
33 |
34 | JSON To Dataclass Generation Tool
35 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
36 |
37 | The subcommand ``gen-schema`` (aliased to ``gs``) provides a JSON to Python
38 | schema generation tool. This utility takes a JSON file or string as an input,
39 | and outputs the corresponding dataclass schema. The main purpose is to easily
40 | create dataclasses that can be used with API output, without resorting to
41 | ``dict``'s or ``NamedTuple``'s.
42 |
43 | This scheme generation tool is inspired by the following projects:
44 |
45 | - https://github.com/mischareitsma/json2dataclass
46 | - https://russbiggs.github.io/json2dataclass
47 | - https://github.com/mholt/json-to-go
48 | - https://github.com/bermi/Python-Inflector
49 |
50 | .. note:: A few things to consider:
51 |
52 | - The script sometimes has to make some assumptions, so give the output a once-over.
53 | - In an array of objects (i.e. dictionaries), all key names and type definitions get merged into a single
54 | model ``dataclass``, as the objects are considered homogenous in this case.
55 | - Deeply nested lists within objects (e.g. *list* -> *dict* -> *list*) should
56 | similarly merge all list elements with the other lists under that key in
57 | each sibling `dict` object.
58 | - The output is properly formatted, including additional spacing where needed.
59 | Please consider `opening an issue`_ if there are any potential improvements
60 | to be made.
61 |
62 | Example usage::
63 |
64 | echo '{
65 | "name": "Yavin IV",
66 | "rotation_period": "24",
67 | "orbital_period": "4818",
68 | "diameter": "10200",
69 | "climate": "temperate, tropical",
70 | "gravity": "1 standard",
71 | "terrain": "jungle, rainforests",
72 | "surface_water": "8",
73 | "population": "1000",
74 | "residents": [],
75 | "films": [
76 | "https://swapi.co/api/films/1/"
77 | ],
78 | "created": "2014-12-10T11:37:19.144000Z",
79 | "edited": "2014-12-20T20:58:18.421000Z",
80 | "url": "https://swapi.co/api/planets/3/"
81 | }' | wiz gs
82 |
83 | Generates the following Python code::
84 |
85 | from dataclasses import dataclass
86 | from datetime import datetime
87 | from typing import List, Union
88 |
89 |
90 | @dataclass
91 | class Data:
92 | """
93 | Data dataclass
94 |
95 | """
96 | name: str
97 | rotation_period: Union[int, str]
98 | orbital_period: Union[int, str]
99 | diameter: Union[int, str]
100 | climate: str
101 | gravity: str
102 | terrain: str
103 | surface_water: Union[int, str]
104 | population: Union[int, str]
105 | residents: List
106 | films: List[str]
107 | created: datetime
108 | edited: datetime
109 | url: str
110 |
111 |
112 | Note: to write the output to a Python file instead of displaying the
113 | output in the terminal, pass the name of the output file. If the file
114 | has no extension, a default ``.py`` extension will be added.
115 |
116 | For example::
117 |
118 | # Note: the following command writes to a new file 'out.py'
119 |
120 | echo '' | wiz gs - out
121 |
122 | Future Annotations
123 | ------------------
124 |
125 | Passing in the ``-x/--experimental`` flag will enable experimental features via
126 | a ``__future__`` import, which allows `PEP 585`_ and `PEP 604`_- style
127 | annotations to be used in Python 3.7+
128 |
129 | For example, assume your ``input.json`` file contains the following contents:
130 |
131 | .. code:: json
132 |
133 | {
134 | "myField": null,
135 | "My_List": [],
136 | "Objects": [
137 | {
138 | "key1": false
139 | },
140 | {
141 | "key1": 1.2,
142 | "key2": "string"
143 | },
144 | {
145 | "key1": "val",
146 | "key2": null
147 | }
148 | ]
149 | }
150 |
151 | Then we could run the following command::
152 |
153 | $ wiz gs -x input.json
154 |
155 | The generated Python code is slightly different, as shown below. You might notice
156 | that a ``__future__`` import is added at the top, for compatibility with versions
157 | earlier than Python 3.10. In the annotations, we also prefer to use parameterized
158 | standard collections, and use the new pipe ``|`` syntax to represent ``Union``
159 | and ``Optional`` types.
160 |
161 | .. code:: python3
162 |
163 | from __future__ import annotations
164 |
165 | from dataclasses import dataclass
166 | from typing import Any
167 |
168 | from dataclass_wizard import JSONWizard
169 |
170 |
171 | @dataclass
172 | class Data(JSONWizard):
173 | """
174 | Data dataclass
175 |
176 | """
177 | my_field: Any
178 | my_list: list
179 | objects: list[Object]
180 |
181 |
182 | @dataclass
183 | class Object:
184 | """
185 | Object dataclass
186 |
187 | """
188 | key1: bool | float | str
189 | key2: str | None
190 |
191 |
192 | .. _`opening an issue`: https://github.com/rnag/dataclass-wizard/issues
193 | .. _`PEP 585`: https://www.python.org/dev/peps/pep-0585/
194 | .. _`PEP 604`: https://www.python.org/dev/peps/pep-0604/
195 |
--------------------------------------------------------------------------------
/docs/common_use_cases/nested_key_paths.rst:
--------------------------------------------------------------------------------
1 | Map a Nested JSON Key Path to a Field
2 | =====================================
3 |
4 | .. note::
5 | **Important:** The current "nested path" functionality is being re-imagined.
6 | Please refer to the new docs for **V1 Opt-in** features, which introduces enhanced support for these use
7 | cases. For more details, see the `Field Guide to V1 Opt‐in`_ and the `V1 Alias`_ documentation.
8 |
9 | This change is part of the ongoing improvements in version ``v0.35.0+``, and the old functionality will no longer be maintained in future releases.
10 |
11 | .. _Field Guide to V1 Opt‐in: https://github.com/rnag/dataclass-wizard/wiki/Field-Guide-to-V1-Opt%E2%80%90in
12 | .. _V1 Alias: https://dcw.ritviknag.com/en/latest/common_use_cases/v1_alias.html
13 |
14 | The ``dataclass-wizard`` library allows mapping deeply nested JSON paths to individual dataclass fields using a custom object path notation. This feature supports both :type:`Annotated` types and :class:`dataclasses.Field` for flexible and precise JSON deserialization.
15 |
16 | .. role:: bc
17 | :class: bold-code
18 |
19 | Basic Usage Example
20 | -------------------
21 |
22 | Define and use nested key paths for JSON deserialization with the :type:`Annotated` type and :func:`path_field`:
23 |
24 | .. code:: python3
25 |
26 | from dataclasses import dataclass
27 | from dataclass_wizard import JSONWizard, KeyPath, path_field
28 | from typing import Annotated
29 |
30 | @dataclass
31 | class Example(JSONWizard):
32 | # Map using Annotated with KeyPath
33 | an_int: Annotated[int, KeyPath('data.nested.int')]
34 | # Map using path_field with a default value
35 | my_str: str = path_field(['metadata', 'info', 'name'], default='unknown')
36 |
37 | - The field ``an_int`` maps to the nested JSON path ``data.nested.int``.
38 | - The field ``my_str`` maps to the path ``metadata.info.name`` and defaults to ``'unknown'`` if the key is missing.
39 |
40 | Expanded Example with JSON
41 | ---------------------------
42 |
43 | Given the following JSON data:
44 |
45 | .. code-block:: json
46 |
47 | {
48 | "data": {
49 | "nested": {
50 | "int": 42
51 | }
52 | },
53 | "metadata": {
54 | "info": {
55 | "name": "John Doe"
56 | }
57 | }
58 | }
59 |
60 | Deserializing with the :meth:`from_dict` method:
61 |
62 | .. code:: python3
63 |
64 | example = Example.from_dict({
65 | "data": {
66 | "nested": {
67 | "int": 42
68 | }
69 | },
70 | "metadata": {
71 | "info": {
72 | "name": "John Doe"
73 | }
74 | }
75 | })
76 | print(example.an_int) # 42
77 | print(example.my_str) # 'John Doe'
78 |
79 | This example shows how JSON data is mapped to dataclass fields using the custom key paths.
80 |
81 | Object Path Notation
82 | --------------------
83 |
84 | The object path notation used in :func:`KeyPath` and :func:`path_field` follows these rules:
85 |
86 | - **Dot** (:bc:`.`) separates nested object keys.
87 | - **Square brackets** (:bc:`[]`) access array elements or special keys.
88 | - **Quotes** (:bc:`"`:bc:`'`) are required for keys with spaces, special characters, or reserved names.
89 |
90 | .. |dot| raw:: html
91 |
92 | .
93 |
94 | Examples:
95 |
96 | 1. **Simple Path**
97 | ``data.info.name``
98 | Accesses the ``name`` key inside the ``info`` object within ``data``.
99 |
100 | 2. **Array Indexing**
101 | ``data[0].value``
102 | Accesses the ``value`` field in the first element of the ``data`` array.
103 |
104 | 3. **Keys with Spaces or Special Characters**
105 | ``metadata["user name"].details``
106 | Accesses the ``details`` key inside ``metadata["user name"]``.
107 |
108 | 4. **Mixed Types**
109 | ``data[0]["user name"].info.age``
110 | Accesses ``age`` within ``info``, nested under ``"user name"`` in the first item of ``data``.
111 |
112 | Path Parsing Examples
113 | ---------------------
114 |
115 | These examples illustrate how the path is interpreted by ``KeyPath`` or ``path_field``:
116 |
117 | - **Example 1: Boolean Path**
118 |
119 | .. code:: python3
120 |
121 | split_object_path('user[true]')
122 |
123 | Output: ``['user', True]``
124 | Accesses the ``True`` key in the ``user`` object. Booleans like ``True`` and ``False`` are automatically recognized.
125 |
126 | - **Example 2: Integer Path**
127 |
128 | .. code:: python3
129 |
130 | split_object_path('data[5].value')
131 |
132 | Output: ``['data', 5, 'value']``
133 | Accesses ``value`` in the 6th element (index 5) of the ``data`` array.
134 |
135 | - **Example 3: Floats in Paths**
136 |
137 | .. code:: python3
138 |
139 | split_object_path('data[0.25]')
140 |
141 | Output: ``['data', 0.25]``
142 | Floats are parsed correctly, although array indices are typically integers.
143 |
144 | - **Example 4: Strings Without Quotes**
145 |
146 | .. code:: python3
147 |
148 | split_object_path('data[user_name]')
149 |
150 | Output: ``['data', 'user_name']``
151 | Valid identifiers are treated as strings even without quotes.
152 |
153 | - **Example 5: Strings With Quotes**
154 |
155 | .. code:: python3
156 |
157 | split_object_path('data["user name"]')
158 |
159 | Output: ``['data', 'user name']``
160 | Quotes are required for keys with spaces or special characters.
161 |
162 | - **Example 6: Mixed Types**
163 |
164 | .. code:: python3
165 |
166 | split_object_path('data[0]["user name"].info[age]')
167 |
168 | Output: ``['data', 0, 'user name', 'info', 'age']``
169 | Accesses ``age`` within ``info``, under ``user name``, in the first item of ``data``.
170 |
171 | Handling Quotes
172 | ---------------
173 |
174 | When keys or indices are wrapped in quotes, they are interpreted as strings. This is necessary for:
175 |
176 | - Keys with spaces or special characters.
177 | - Reserved words or identifiers that could otherwise cause parsing errors.
178 |
179 | Example:
180 |
181 | .. code:: python3
182 |
183 | split_object_path('data["123"].info')
184 |
185 | Output: ``['data', '123', 'info']``
186 | Here, ``"123"`` is treated as a string because of the quotes.
187 |
188 | Best Practices
189 | --------------
190 |
191 | - Use :type:`Annotated` with :func:`KeyPath` for complex, deeply nested paths.
192 | - Use :func:`path_field` for flexibility, defaults, or custom serialization.
193 | - Keep paths concise and use quotes judiciously for clarity and correctness.
194 |
--------------------------------------------------------------------------------
/docs/examples.rst:
--------------------------------------------------------------------------------
1 | Examples
2 | ========
3 |
4 | Simple
5 | ~~~~~~
6 |
7 | The following example has been tested on **Python 3.9+**.
8 |
9 | .. code:: python3
10 |
11 | # Note: in Python 3.10+, this import can be removed
12 | from __future__ import annotations
13 |
14 | from dataclasses import dataclass, field
15 |
16 | from dataclass_wizard import JSONWizard
17 |
18 |
19 | @dataclass
20 | class MyClass(JSONWizard):
21 | my_str: str | None
22 | is_active_tuple: tuple[bool, ...]
23 | list_of_int: list[int] = field(default_factory=list)
24 |
25 |
26 | string = """
27 | {
28 | "my_str": 20,
29 | "ListOfInt": ["1", "2", 3],
30 | "isActiveTuple": ["true", "false", 1, false]
31 | }
32 | """
33 |
34 | # De-serialize the JSON string into a `MyClass` object.
35 | c = MyClass.from_json(string)
36 |
37 | print(repr(c))
38 | # prints:
39 | # MyClass(my_str='20', is_active_tuple=(True, False, True, False), list_of_int=[1, 2, 3])
40 |
41 | print(c.to_json())
42 | # prints:
43 | # {"myStr": "20", "isActiveTuple": [true, false, true, false], "listOfInt": [1, 2, 3]}
44 |
45 | # True
46 | assert c == c.from_dict(c.to_dict())
47 |
48 | Using Typing Imports (Deprecated)
49 | ---------------------------------
50 |
51 | This approach is supported in **Python 3.6**. Usage is the same as above.
52 |
53 | .. code:: python3
54 |
55 | from dataclasses import dataclass, field
56 | from typing import Optional, List, Tuple
57 |
58 | from dataclass_wizard import JSONWizard
59 |
60 |
61 | @dataclass
62 | class MyClass(JSONWizard):
63 | my_str: Optional[str]
64 | is_active_tuple: Tuple[bool, ...]
65 | list_of_int: List[int] = field(default_factory=list)
66 |
67 |
68 | A (More) Complete Example
69 | ~~~~~~~~~~~~~~~~~~~~~~~~~
70 |
71 | .. code:: python3
72 |
73 | from collections import defaultdict
74 | from dataclasses import dataclass, field
75 | from datetime import datetime
76 | from typing import Optional, Literal, Union, Any, NamedTuple
77 |
78 | from dataclass_wizard import JSONSerializable
79 |
80 |
81 | @dataclass
82 | class MyTestClass(JSONSerializable):
83 | my_ledger: dict[str, Any]
84 | the_answer_to_life: Optional[int]
85 | people: list['Person']
86 | is_enabled: bool = True
87 |
88 |
89 | @dataclass
90 | class Person:
91 | name: 'Name'
92 | age: int
93 | birthdate: datetime
94 | gender: Literal['M', 'F', 'N/A']
95 | occupation: Union[str, list[str]]
96 | hobbies: defaultdict[str, list[str]] = field(
97 | default_factory=lambda: defaultdict(list))
98 |
99 |
100 | class Name(NamedTuple):
101 | """A person's name"""
102 | first: str
103 | last: str
104 | salutation: Optional[Literal['Mr.', 'Mrs.', 'Ms.', 'Dr.']] = 'Mr.'
105 |
106 |
107 | data = {
108 | 'myLedger': {
109 | 'Day 1': 'some details',
110 | 'Day 17': ['a', 'sample', 'list']
111 | },
112 | 'theAnswerTOLife': '42',
113 | 'People': [
114 | {
115 | 'name': ('Roberto', 'Fuirron'),
116 | 'age': 21,
117 | 'birthdate': '1950-02-28T17:35:20Z',
118 | 'gender': 'M',
119 | 'occupation': ['sailor', 'fisher'],
120 | 'Hobbies': {'M-F': ('chess', 123, 'reading'), 'Sat-Sun': ['parasailing']}
121 | },
122 | {
123 | 'name': ('Janice', 'Darr', 'Dr.'),
124 | 'age': 45,
125 | 'birthdate': '1971-11-05 05:10:59',
126 | 'gender': 'F',
127 | 'occupation': 'Dentist'
128 | }
129 | ]
130 | }
131 |
132 | c = MyTestClass.from_dict(data)
133 |
134 | print(repr(c))
135 | # prints the following result on a single line:
136 | # MyTestClass(
137 | # my_ledger={'Day 1': 'some details', 'Day 17': ['a', 'sample', 'list']},
138 | # the_answer_to_life=42,
139 | # people=[
140 | # Person(
141 | # name=Name(first='Roberto', last='Fuirron', salutation='Mr.'),
142 | # age=21, birthdate=datetime.datetime(1950, 2, 28, 17, 35, 20, tzinfo=datetime.timezone.utc),
143 | # gender='M', occupation=['sailor', 'fisher'],
144 | # hobbies=defaultdict(, {'M-F': ['chess', '123', 'reading'], 'Sat-Sun': ['parasailing']})
145 | # ),
146 | # Person(
147 | # name=Name(first='Janice', last='Darr', salutation='Dr.'),
148 | # age=45, birthdate=datetime.datetime(1971, 11, 5, 5, 10, 59),
149 | # gender='F', occupation='Dentist',
150 | # hobbies=defaultdict(, {})
151 | # )
152 | # ], is_enabled=True)
153 |
154 | # calling `print` on the object invokes the `__str__` method, which will
155 | # pretty-print the JSON representation of the object by default. You can
156 | # also call the `to_json` method to print the JSON string on a single line.
157 |
158 | print(c)
159 | # prints:
160 | # {
161 | # "myLedger": {
162 | # "Day 1": "some details",
163 | # "Day 17": [
164 | # "a",
165 | # "sample",
166 | # "list"
167 | # ]
168 | # },
169 | # "theAnswerToLife": 42,
170 | # "people": [
171 | # {
172 | # "name": [
173 | # "Roberto",
174 | # "Fuirron",
175 | # "Mr."
176 | # ],
177 | # "age": 21,
178 | # "birthdate": "1950-02-28T17:35:20Z",
179 | # "gender": "M",
180 | # "occupation": [
181 | # "sailor",
182 | # "fisher"
183 | # ],
184 | # "hobbies": {
185 | # "M-F": [
186 | # "chess",
187 | # "123",
188 | # "reading"
189 | # ],
190 | # "Sat-Sun": [
191 | # "parasailing"
192 | # ]
193 | # }
194 | # },
195 | # {
196 | # "name": [
197 | # "Janice",
198 | # "Darr",
199 | # "Dr."
200 | # ],
201 | # "age": 45,
202 | # "birthdate": "1971-11-05T05:10:59",
203 | # "gender": "F",
204 | # "occupation": "Dentist",
205 | # "hobbies": {}
206 | # }
207 | # ],
208 | # "isEnabled": true
209 | # }
210 |
--------------------------------------------------------------------------------
/dataclass_wizard/utils/object_path.py:
--------------------------------------------------------------------------------
1 | from dataclasses import MISSING
2 |
3 | from ..errors import ParseError
4 |
5 |
6 | def safe_get(data, path, default=MISSING, raise_=True):
7 | current_data = data
8 | p = path # to avoid "unbound local variable" warnings
9 |
10 | try:
11 | for p in path:
12 | current_data = current_data[p]
13 |
14 | return current_data
15 |
16 | # IndexError -
17 | # raised when `data` is a `list`, and we access an index that is "out of bounds"
18 | # KeyError -
19 | # raised when `data` is a `dict`, and we access a key that is not present
20 | # AttributeError -
21 | # raised when `data` is an invalid type, such as a `None`
22 | except (IndexError, KeyError, AttributeError) as e:
23 | if raise_ and default is MISSING:
24 | raise _format_err(e, current_data, path, p) from None
25 | return default
26 |
27 | # TypeError -
28 | # raised when `data` is a `list`, but we try to use it like a `dict`
29 | except TypeError:
30 | e = TypeError('Invalid path')
31 | raise _format_err(e, current_data, path, p, True) from None
32 |
33 |
34 | def v1_safe_get(data, path, raise_):
35 | current_data = data
36 |
37 | try:
38 | for p in path:
39 | current_data = current_data[p]
40 |
41 | return current_data
42 |
43 | # IndexError -
44 | # raised when `data` is a `list`, and we access an index that is "out of bounds"
45 | # KeyError -
46 | # raised when `data` is a `dict`, and we access a key that is not present
47 | # AttributeError -
48 | # raised when `data` is an invalid type, such as a `None`
49 | except (IndexError, KeyError, AttributeError) as e:
50 | if raise_:
51 | p = locals().get('p', path) # to suppress "unbound local variable"
52 | raise _format_err(e, current_data, path, p, True) from None
53 |
54 | return MISSING
55 |
56 | # TypeError -
57 | # raised when `data` is a `list`, but we try to use it like a `dict`
58 | except TypeError:
59 | e = TypeError('Invalid path')
60 | p = locals().get('p', path) # to suppress "unbound local variable"
61 | raise _format_err(e, current_data, path, p, True) from None
62 |
63 |
64 | def _format_err(e, current_data, path, current_path, invalid_path=False):
65 | return ParseError(
66 | e, current_data, dict if invalid_path else None, 'load',
67 | path=' => '.join(repr(p) for p in path),
68 | current_path=repr(current_path),
69 | )
70 |
71 |
72 | # What values are considered "truthy" when converting to a boolean type.
73 | # noinspection SpellCheckingInspection
74 | _TRUTHY_VALUES = frozenset(("True", "true"))
75 |
76 | # What values are considered "falsy" when converting to a boolean type.
77 | # noinspection SpellCheckingInspection
78 | _FALSY_VALUES = frozenset(("False", "false"))
79 |
80 |
81 | # Valid starting separators in our custom "object path",
82 | # for example `a.b[c].d.[-1]` has 5 start separators.
83 | _START_SEP = frozenset(('.', '['))
84 |
85 |
86 | def split_object_path(_input):
87 | res = []
88 | s = ""
89 | start_new = True
90 | in_literal = False
91 |
92 | parsed_string_literal = False
93 |
94 | in_braces = False
95 |
96 | escape_next_quote = False
97 | quote_char = None
98 | possible_number = False
99 |
100 | for c in _input:
101 | if c in _START_SEP:
102 | if in_literal:
103 | s += c
104 | else:
105 | if c == '.':
106 | # A period within braces [xxx] OR within a string "xxx",
107 | # should be captured.
108 | if in_braces:
109 | s += c
110 | continue
111 | in_braces = False
112 | else:
113 | in_braces = True
114 |
115 | start_new = True
116 | if s:
117 | if possible_number:
118 | possible_number = False
119 | try:
120 | num = int(s)
121 | res.append(num)
122 | except ValueError:
123 | try:
124 | num = float(s)
125 | res.append(num)
126 | except ValueError:
127 | res.append(s)
128 | elif parsed_string_literal:
129 | parsed_string_literal = False
130 | res.append(s)
131 | else:
132 | if s in _TRUTHY_VALUES:
133 | res.append(True)
134 | elif s in _FALSY_VALUES:
135 | res.append(False)
136 | else:
137 | res.append(s)
138 |
139 | s = ""
140 | elif c == '\\' and in_literal:
141 | escape_next_quote = True
142 | elif escape_next_quote:
143 | if c != quote_char:
144 | # It was not an escape character after all!
145 | s += '\\'
146 | # Capture escaped character
147 | s += c
148 | escape_next_quote = False
149 | elif c == quote_char:
150 | in_literal = False
151 | quote_char = None
152 | parsed_string_literal = True
153 | elif c in {'"', "'"} and start_new:
154 | start_new = False
155 | in_literal = True
156 | quote_char = c
157 | elif (c in {'+', '-'} or c.isdigit()) and start_new:
158 | start_new = False
159 | possible_number = True
160 | s += c
161 | elif start_new:
162 | start_new = False
163 | s += c
164 | elif c == ']':
165 | if in_literal:
166 | s += c
167 | else:
168 | in_braces = False
169 | else:
170 | s += c
171 |
172 | if s:
173 | if possible_number:
174 | try:
175 | num = int(s)
176 | res.append(num)
177 | except ValueError:
178 | try:
179 | num = float(s)
180 | res.append(num)
181 | except ValueError:
182 | res.append(s)
183 | elif parsed_string_literal:
184 | res.append(s)
185 | else:
186 | if s in _TRUTHY_VALUES:
187 | res.append(True)
188 | elif s in _FALSY_VALUES:
189 | res.append(False)
190 | else:
191 | res.append(s)
192 |
193 | return res
194 |
--------------------------------------------------------------------------------
/dataclass_wizard/type_def.py:
--------------------------------------------------------------------------------
1 | __all__ = [
2 | 'Buffer',
3 | 'PyForwardRef',
4 | 'PyProtocol',
5 | 'PyDeque',
6 | 'PyTypedDict',
7 | 'PyRequired',
8 | 'PyNotRequired',
9 | 'PyReadOnly',
10 | 'PyLiteralString',
11 | 'FrozenKeys',
12 | 'DefFactory',
13 | 'NoneType',
14 | 'ExplicitNullType',
15 | 'ExplicitNull',
16 | 'JSONList',
17 | 'JSONObject',
18 | 'ListOfJSONObject',
19 | 'JSONValue',
20 | 'FileType',
21 | 'EnvFileType',
22 | 'StrCollection',
23 | 'ParseFloat',
24 | 'Encoder',
25 | 'FileEncoder',
26 | 'Decoder',
27 | 'FileDecoder',
28 | 'NUMBERS',
29 | 'T',
30 | 'E',
31 | 'U',
32 | 'M',
33 | 'NT',
34 | 'DT',
35 | 'DD',
36 | 'N',
37 | 'S',
38 | 'LT',
39 | 'LSQ',
40 | 'FREF',
41 | 'dataclass_transform',
42 | ]
43 |
44 | from collections import deque, defaultdict
45 | from datetime import date, time, datetime
46 | from enum import Enum
47 | from os import PathLike
48 | from typing import (
49 | Any, TypeVar, Sequence, Mapping,
50 | Union, NamedTuple, Callable, AnyStr, TextIO, BinaryIO,
51 | Deque as PyDeque,
52 | ForwardRef as PyForwardRef,
53 | Protocol as PyProtocol,
54 | TypedDict as PyTypedDict, Iterable, Collection,
55 | )
56 | from uuid import UUID
57 |
58 | from .constants import PY310_OR_ABOVE, PY311_OR_ABOVE, PY313_OR_ABOVE, PY312_OR_ABOVE
59 |
60 | # The class of the `None` singleton, cached for re-usability
61 | if PY310_OR_ABOVE:
62 | # https://docs.python.org/3/library/types.html#types.NoneType
63 | from types import NoneType
64 | else:
65 | # "Cannot assign to a type"
66 | NoneType = type(None) # type: ignore[misc]
67 |
68 | # Type check for numeric types - needed because `bool` is technically
69 | # a Number.
70 | NUMBERS = int, float
71 |
72 | # Generic type
73 | T = TypeVar('T')
74 | TT = TypeVar('TT')
75 |
76 | # Enum subclass type
77 | E = TypeVar('E', bound=Enum)
78 |
79 | # UUID subclass type
80 | U = TypeVar('U', bound=UUID)
81 |
82 | # Mapping type
83 | M = TypeVar('M', bound=Mapping)
84 |
85 | # NamedTuple type
86 | NT = TypeVar('NT', bound=NamedTuple)
87 |
88 | # Date, time, or datetime type
89 | DT = TypeVar('DT', date, time, datetime)
90 |
91 | # DefaultDict type
92 | DD = TypeVar('DD', bound=defaultdict)
93 |
94 | # Numeric type
95 | N = Union[int, float]
96 |
97 | # Sequence type
98 | S = TypeVar('S', bound=Sequence)
99 |
100 | # List or Tuple type
101 | LT = TypeVar('LT', list, tuple)
102 |
103 | # List, Set, or Deque (Double ended queue) type
104 | LSQ = TypeVar('LSQ', list, set, frozenset, deque)
105 |
106 | # A fixed set of key names
107 | FrozenKeys = frozenset[str]
108 |
109 | # Default factory type, assuming a no-args constructor
110 | DefFactory = Callable[[], T]
111 |
112 | # Valid collection types in JSON.
113 | JSONList = list[Any]
114 | JSONObject = dict[str, Any]
115 | ListOfJSONObject = list[JSONObject]
116 |
117 | # Valid value types in JSON.
118 | JSONValue = Union[None, str, bool, int, float, JSONList, JSONObject]
119 |
120 | # File-type argument, compatible with the type of `file` for `open`
121 | FileType = Union[str, bytes, PathLike, int]
122 |
123 | # DotEnv file-type argument (string, tuple of string, boolean, or None)
124 | EnvFileType = Union[bool, FileType, Iterable[FileType], None]
125 |
126 | # Type for a string or a collection of strings.
127 | StrCollection = Union[str, Collection[str]]
128 |
129 | # Python 3.11 introduced `Required` and `NotRequired` wrappers for
130 | # `TypedDict` fields (PEP 655). Python 3.9+ users can import the
131 | # wrappers from `typing_extensions`.
132 |
133 | if PY313_OR_ABOVE: # pragma: no cover
134 | from collections.abc import Buffer
135 |
136 | from typing import (Required as PyRequired,
137 | NotRequired as PyNotRequired,
138 | ReadOnly as PyReadOnly,
139 | LiteralString as PyLiteralString,
140 | dataclass_transform)
141 | elif PY311_OR_ABOVE: # pragma: no cover
142 | if PY312_OR_ABOVE:
143 | from collections.abc import Buffer
144 | else:
145 | from typing_extensions import Buffer
146 |
147 | from typing import (Required as PyRequired,
148 | NotRequired as PyNotRequired,
149 | LiteralString as PyLiteralString,
150 | dataclass_transform)
151 | from typing_extensions import ReadOnly as PyReadOnly
152 | else:
153 | from typing_extensions import (Buffer,
154 | Required as PyRequired,
155 | NotRequired as PyNotRequired,
156 | ReadOnly as PyReadOnly,
157 | LiteralString as PyLiteralString,
158 | dataclass_transform)
159 |
160 | # Forward references can be either strings or explicit `ForwardRef` objects.
161 | # noinspection SpellCheckingInspection
162 | FREF = TypeVar('FREF', str, PyForwardRef)
163 |
164 |
165 | class ExplicitNullType:
166 | __slots__ = () # Saves memory by preventing the creation of instance dictionaries
167 |
168 | # Class-level instance variable for singleton control
169 | _instance: "ExplicitNullType | None" = None
170 |
171 | def __new__(cls):
172 | if cls._instance is None:
173 | cls._instance = super(ExplicitNullType, cls).__new__(cls)
174 | return cls._instance
175 |
176 | def __bool__(self):
177 | return False
178 |
179 | def __repr__(self):
180 | return ''
181 |
182 |
183 | # Create the singleton instance
184 | ExplicitNull = ExplicitNullType()
185 |
186 | # Type annotations
187 | ParseFloat = Callable[[str], Any]
188 |
189 |
190 | class Encoder(PyProtocol):
191 | """
192 | Represents an encoder for Python object -> JSON, e.g. analogous to
193 | `json.dumps`
194 | """
195 |
196 | def __call__(self, obj: Union[JSONObject, JSONList],
197 | /,
198 | *args,
199 | **kwargs) -> AnyStr:
200 | ...
201 |
202 |
203 | class FileEncoder(PyProtocol):
204 | """
205 | Represents an encoder for Python object -> JSON file, e.g. analogous to
206 | `json.dump`
207 | """
208 |
209 | def __call__(self, obj: Union[JSONObject, JSONList],
210 | file: Union[TextIO, BinaryIO],
211 | **kwargs) -> AnyStr:
212 | ...
213 |
214 |
215 | class Decoder(PyProtocol):
216 | """
217 | Represents a decoder for JSON -> Python object, e.g. analogous to
218 | `json.loads`
219 | """
220 |
221 | def __call__(self, s: AnyStr,
222 | **kwargs) -> Union[JSONObject, ListOfJSONObject]:
223 | ...
224 |
225 |
226 | class FileDecoder(PyProtocol):
227 | """
228 | Represents a decoder for JSON file -> Python object, e.g. analogous to
229 | `json.load`
230 | """
231 | def __call__(self, file: Union[TextIO, BinaryIO],
232 | **kwargs) -> Union[JSONObject, ListOfJSONObject]:
233 | ...
234 |
--------------------------------------------------------------------------------
/dataclass_wizard/serial_json.py:
--------------------------------------------------------------------------------
1 | import json
2 | import logging
3 | from dataclasses import is_dataclass, dataclass
4 |
5 | from .abstractions import AbstractJSONWizard
6 | from .bases_meta import BaseJSONWizardMeta, LoadMeta, DumpMeta, register_type
7 | from .constants import PACKAGE_NAME, SINGLE_ARG_ALIAS
8 | from .class_helper import call_meta_initializer_if_needed, get_meta
9 | from .decorators import _single_arg_alias
10 | from .type_def import dataclass_transform
11 | from .loader_selection import asdict, fromdict, fromlist, get_loader, get_dumper
12 | # noinspection PyProtectedMember
13 | from .utils.dataclass_compat import _create_fn, _set_new_attribute
14 | from .type_def import dataclass_transform
15 |
16 |
17 | def _str_fn():
18 | return _create_fn('__str__',
19 | ('self',),
20 | ['return self.to_json(indent=2)'])
21 |
22 |
23 | def _configure_wizard_class(cls,
24 | str=True,
25 | debug=False,
26 | case=None,
27 | dump_case=None,
28 | load_case=None,
29 | _key_transform=None,
30 | _v1_default=False):
31 | load_meta_kwargs = {}
32 |
33 | if case is not None:
34 | _v1_default = True
35 | load_meta_kwargs['v1_case'] = case
36 |
37 | if dump_case is not None:
38 | _v1_default = True
39 | load_meta_kwargs['v1_dump_case'] = dump_case
40 |
41 | if load_case is not None:
42 | _v1_default = True
43 | load_meta_kwargs['v1_load_case'] = load_case
44 |
45 | if _v1_default:
46 | load_meta_kwargs['v1'] = True
47 |
48 | if _key_transform is not None:
49 | DumpMeta(key_transform=_key_transform).bind_to(cls)
50 |
51 | if debug:
52 | default_lvl = logging.DEBUG
53 | logging.basicConfig(level=default_lvl)
54 | # minimum logging level for logs by this library
55 | min_level = default_lvl if isinstance(debug, bool) else debug
56 | # set `v1_debug` flag for the class's Meta
57 | load_meta_kwargs['v1_debug'] = min_level
58 |
59 | # Calls the Meta initializer when inner :class:`Meta` is sub-classed.
60 | call_meta_initializer_if_needed(cls)
61 |
62 | if load_meta_kwargs:
63 | LoadMeta(**load_meta_kwargs).bind_to(cls)
64 |
65 | # Add a `__str__` method to the subclass, if needed
66 | if str:
67 | _set_new_attribute(cls, '__str__', _str_fn())
68 |
69 |
70 | @dataclass_transform()
71 | class DataclassWizard(AbstractJSONWizard):
72 |
73 | __slots__ = ()
74 |
75 | class Meta(BaseJSONWizardMeta):
76 |
77 | __slots__ = ()
78 |
79 | __is_inner_meta__ = True
80 |
81 | def __init_subclass__(cls):
82 | return cls._init_subclass()
83 |
84 | register_type = classmethod(register_type)
85 |
86 | @classmethod
87 | def from_json(cls, string, *,
88 | decoder=json.loads,
89 | **decoder_kwargs):
90 |
91 | o = decoder(string, **decoder_kwargs)
92 |
93 | return fromdict(cls, o) if isinstance(o, dict) else fromlist(cls, o)
94 |
95 | from_list = classmethod(fromlist)
96 |
97 | from_dict = classmethod(fromdict)
98 |
99 | to_dict = asdict
100 |
101 | def to_json(self, *,
102 | encoder=json.dumps,
103 | **encoder_kwargs):
104 |
105 | return encoder(asdict(self), **encoder_kwargs)
106 |
107 | @classmethod
108 | def list_to_json(cls,
109 | instances,
110 | encoder=json.dumps,
111 | **encoder_kwargs):
112 |
113 | list_of_dict = [asdict(o, cls=cls) for o in instances]
114 |
115 | return encoder(list_of_dict, **encoder_kwargs)
116 |
117 | # noinspection PyShadowingBuiltins
118 | def __init_subclass__(cls,
119 | str=False,
120 | debug=False,
121 | case=None,
122 | dump_case=None,
123 | load_case=None,
124 | _key_transform=None,
125 | _v1_default=True,
126 | _apply_dataclass=True,
127 | **dc_kwargs):
128 |
129 | super().__init_subclass__()
130 |
131 | # skip classes provided by this library
132 | if cls.__module__.startswith(f'{PACKAGE_NAME}.'):
133 | return
134 |
135 | # Apply the @dataclass decorator.
136 | if _apply_dataclass and not is_dataclass(cls):
137 | # noinspection PyArgumentList
138 | dataclass(cls, **dc_kwargs)
139 |
140 | _configure_wizard_class(cls, str, debug, case, dump_case, load_case,
141 | _key_transform, _v1_default)
142 |
143 |
144 | # noinspection PyAbstractClass
145 | @dataclass_transform()
146 | class JSONSerializable(DataclassWizard):
147 |
148 | __slots__ = ()
149 |
150 | # noinspection PyShadowingBuiltins
151 | def __init_subclass__(cls,
152 | str=True,
153 | debug=False,
154 | case=None,
155 | dump_case=None,
156 | load_case=None,
157 | _key_transform=None,
158 | _v1_default=False,
159 | _apply_dataclass=False,
160 | **_):
161 |
162 | super().__init_subclass__(str, debug, case, dump_case, load_case,
163 | _key_transform, _v1_default, _apply_dataclass)
164 |
165 |
166 | def _str_pprint_fn():
167 | from pprint import pformat
168 |
169 | def __str__(self):
170 | return pformat(self, width=70)
171 |
172 | return __str__
173 |
174 |
175 | # A handy alias in case it comes in useful to anyone :)
176 | JSONWizard = JSONSerializable
177 |
178 |
179 | class JSONPyWizard(JSONWizard):
180 | """Helper for JSONWizard that ensures dumping to JSON keeps keys as-is."""
181 |
182 | # noinspection PyShadowingBuiltins
183 | def __init_subclass__(cls,
184 | str=True,
185 | debug=False,
186 | case=None,
187 | dump_case=None,
188 | load_case=None,
189 | _key_transform=None,
190 | _v1_default=False,
191 | _apply_dataclass=False,
192 | **_):
193 | """Bind child class to DumpMeta with no key transformation."""
194 |
195 | # Call JSONSerializable.__init_subclass__()
196 | # set `key_transform_with_dump` for the class's Meta
197 | super().__init_subclass__(False, debug, case, dump_case, load_case, 'NONE',
198 | _v1_default, _apply_dataclass)
199 |
200 | # Add a `__str__` method to the subclass, if needed
201 | if str:
202 | _set_new_attribute(cls, '__str__', _str_pprint_fn())
203 |
--------------------------------------------------------------------------------