1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
|
Map a Nested JSON Key Path to a Field
=====================================
.. note::
**Important:** The current "nested path" functionality is being re-imagined.
Please refer to the new docs for **V1 Opt-in** features, which introduces enhanced support for these use
cases. For more details, see the `Field Guide to V1 Opt‐in`_ and the `V1 Alias`_ documentation.
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.
.. _Field Guide to V1 Opt‐in: https://github.com/rnag/dataclass-wizard/wiki/Field-Guide-to-V1-Opt%E2%80%90in
.. _V1 Alias: https://dataclass-wizard.readthedocs.io/en/latest/common_use_cases/v1_alias.html
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.
.. role:: bc
:class: bold-code
Basic Usage Example
-------------------
Define and use nested key paths for JSON deserialization with the :type:`Annotated` type and :func:`path_field`:
.. code:: python3
from dataclasses import dataclass
from dataclass_wizard import JSONWizard, KeyPath, path_field
from typing import Annotated
@dataclass
class Example(JSONWizard):
# Map using Annotated with KeyPath
an_int: Annotated[int, KeyPath('data.nested.int')]
# Map using path_field with a default value
my_str: str = path_field(['metadata', 'info', 'name'], default='unknown')
- The field ``an_int`` maps to the nested JSON path ``data.nested.int``.
- The field ``my_str`` maps to the path ``metadata.info.name`` and defaults to ``'unknown'`` if the key is missing.
Expanded Example with JSON
---------------------------
Given the following JSON data:
.. code-block:: json
{
"data": {
"nested": {
"int": 42
}
},
"metadata": {
"info": {
"name": "John Doe"
}
}
}
Deserializing with the :meth:`from_dict` method:
.. code:: python3
example = Example.from_dict({
"data": {
"nested": {
"int": 42
}
},
"metadata": {
"info": {
"name": "John Doe"
}
}
})
print(example.an_int) # 42
print(example.my_str) # 'John Doe'
This example shows how JSON data is mapped to dataclass fields using the custom key paths.
Object Path Notation
--------------------
The object path notation used in :func:`KeyPath` and :func:`path_field` follows these rules:
- **Dot** (:bc:`.`) separates nested object keys.
- **Square brackets** (:bc:`[]`) access array elements or special keys.
- **Quotes** (:bc:`"`:bc:`'`) are required for keys with spaces, special characters, or reserved names.
.. |dot| raw:: html
<code class="code docutils literal notranslate">.</code>
Examples:
1. **Simple Path**
``data.info.name``
Accesses the ``name`` key inside the ``info`` object within ``data``.
2. **Array Indexing**
``data[0].value``
Accesses the ``value`` field in the first element of the ``data`` array.
3. **Keys with Spaces or Special Characters**
``metadata["user name"].details``
Accesses the ``details`` key inside ``metadata["user name"]``.
4. **Mixed Types**
``data[0]["user name"].info.age``
Accesses ``age`` within ``info``, nested under ``"user name"`` in the first item of ``data``.
Path Parsing Examples
---------------------
These examples illustrate how the path is interpreted by ``KeyPath`` or ``path_field``:
- **Example 1: Boolean Path**
.. code:: python3
split_object_path('user[true]')
Output: ``['user', True]``
Accesses the ``True`` key in the ``user`` object. Booleans like ``True`` and ``False`` are automatically recognized.
- **Example 2: Integer Path**
.. code:: python3
split_object_path('data[5].value')
Output: ``['data', 5, 'value']``
Accesses ``value`` in the 6th element (index 5) of the ``data`` array.
- **Example 3: Floats in Paths**
.. code:: python3
split_object_path('data[0.25]')
Output: ``['data', 0.25]``
Floats are parsed correctly, although array indices are typically integers.
- **Example 4: Strings Without Quotes**
.. code:: python3
split_object_path('data[user_name]')
Output: ``['data', 'user_name']``
Valid identifiers are treated as strings even without quotes.
- **Example 5: Strings With Quotes**
.. code:: python3
split_object_path('data["user name"]')
Output: ``['data', 'user name']``
Quotes are required for keys with spaces or special characters.
- **Example 6: Mixed Types**
.. code:: python3
split_object_path('data[0]["user name"].info[age]')
Output: ``['data', 0, 'user name', 'info', 'age']``
Accesses ``age`` within ``info``, under ``user name``, in the first item of ``data``.
Handling Quotes
---------------
When keys or indices are wrapped in quotes, they are interpreted as strings. This is necessary for:
- Keys with spaces or special characters.
- Reserved words or identifiers that could otherwise cause parsing errors.
Example:
.. code:: python3
split_object_path('data["123"].info')
Output: ``['data', '123', 'info']``
Here, ``"123"`` is treated as a string because of the quotes.
Best Practices
--------------
- Use :type:`Annotated` with :func:`KeyPath` for complex, deeply nested paths.
- Use :func:`path_field` for flexibility, defaults, or custom serialization.
- Keep paths concise and use quotes judiciously for clarity and correctness.
|
