sprelf-json 2025.5.5.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- sprelf_json-2025.5.5.0/PKG-INFO +449 -0
- sprelf_json-2025.5.5.0/README.md +436 -0
- sprelf_json-2025.5.5.0/pyproject.toml +25 -0
- sprelf_json-2025.5.5.0/setup.cfg +4 -0
- sprelf_json-2025.5.5.0/src/SprelfJSON/Helpers/ClassHelpers.py +189 -0
- sprelf_json-2025.5.5.0/src/SprelfJSON/Helpers/Decorators.py +20 -0
- sprelf_json-2025.5.5.0/src/SprelfJSON/Helpers/TimeHelpers.py +97 -0
- sprelf_json-2025.5.5.0/src/SprelfJSON/Helpers/__init__.py +1 -0
- sprelf_json-2025.5.5.0/src/SprelfJSON/JSONDefinitions.py +52 -0
- sprelf_json-2025.5.5.0/src/SprelfJSON/JSONModel/JSONModel.py +275 -0
- sprelf_json-2025.5.5.0/src/SprelfJSON/JSONModel/JSONModelError.py +6 -0
- sprelf_json-2025.5.5.0/src/SprelfJSON/JSONModel/ModelElem.py +941 -0
- sprelf_json-2025.5.5.0/src/SprelfJSON/JSONModel/__init__.py +3 -0
- sprelf_json-2025.5.5.0/src/SprelfJSON/JSONUtils.py +39 -0
- sprelf_json-2025.5.5.0/src/SprelfJSON/__init__.py +5 -0
- sprelf_json-2025.5.5.0/src/sprelf_json.egg-info/PKG-INFO +449 -0
- sprelf_json-2025.5.5.0/src/sprelf_json.egg-info/SOURCES.txt +18 -0
- sprelf_json-2025.5.5.0/src/sprelf_json.egg-info/dependency_links.txt +1 -0
- sprelf_json-2025.5.5.0/src/sprelf_json.egg-info/requires.txt +1 -0
- sprelf_json-2025.5.5.0/src/sprelf_json.egg-info/top_level.txt +1 -0
|
@@ -0,0 +1,449 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: sprelf-json
|
|
3
|
+
Version: 2025.5.5.0
|
|
4
|
+
Summary: Simplifies defining schema for and managing JSON objects with non-JSON types
|
|
5
|
+
Author-email: Christopher Dilley <christopher@cabuu.de>
|
|
6
|
+
License-Expression: GPL-3.0-or-later
|
|
7
|
+
Project-URL: repository, https://github.com/cgdilley/SprelfJSON
|
|
8
|
+
Classifier: Programming Language :: Python :: 3
|
|
9
|
+
Classifier: Operating System :: OS Independent
|
|
10
|
+
Requires-Python: >=3.11
|
|
11
|
+
Description-Content-Type: text/markdown
|
|
12
|
+
Requires-Dist: typing-inspect
|
|
13
|
+
|
|
14
|
+
# SprelfJSON - `JSONModel`
|
|
15
|
+
|
|
16
|
+
**JSONModel** simplifies the process of working with JSON data in Python by allowing you to define the structure of your
|
|
17
|
+
JSON objects using class annotations. It provides robust parsing (`from_json()`) and dumping (`to_json()`) capabilities,
|
|
18
|
+
handling a variety of data types and supporting nested and polymorphic JSON structures.
|
|
19
|
+
|
|
20
|
+
## Features:
|
|
21
|
+
|
|
22
|
+
- Define JSON structure using Python class annotations.
|
|
23
|
+
- Automatic parsing of JSON data into Python objects.
|
|
24
|
+
- Automatic dumping of Python objects into JSON-compatible dictionaries.
|
|
25
|
+
- Support for standard Python types (`string`, `int`, `float`, `bool`, `list`, `dict`, etc.).
|
|
26
|
+
- Handling of additional types like `datetime`, `date`, `time`, `timedelta`, `bytes`, `re.Pattern`, `Enum`,`IntEnum`, `StrEnum`, and `IntFlag`.
|
|
27
|
+
- Flexibility to add support for additional data types by subclassing `ModelType`.
|
|
28
|
+
- Seamless handling of nested `JSONModel` objects.
|
|
29
|
+
- Dynamic parsing of `JSONModel` subclasses based on a designated field.
|
|
30
|
+
- Ability to define alternate parsing and dumping logic.
|
|
31
|
+
- Clear error reporting for validation and parsing issues.
|
|
32
|
+
|
|
33
|
+
## Installation
|
|
34
|
+
|
|
35
|
+
`pip install sprelf-json`
|
|
36
|
+
|
|
37
|
+
## Basic Usage
|
|
38
|
+
Define a simple JSON structure:
|
|
39
|
+
|
|
40
|
+
```python
|
|
41
|
+
from SprelfJSON import JSONModel
|
|
42
|
+
|
|
43
|
+
class User(JSONModel):
|
|
44
|
+
name: str
|
|
45
|
+
age: int
|
|
46
|
+
is_active: bool = True # Field with a default value
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Parse JSON data into a User object:
|
|
50
|
+
|
|
51
|
+
```python
|
|
52
|
+
json_data = {"name": "Alice", "age": 30}
|
|
53
|
+
user = User.from_json(json_data)
|
|
54
|
+
|
|
55
|
+
print(user.name) # Output: Alice
|
|
56
|
+
print(user.age) # Output: 30
|
|
57
|
+
print(user.is_active) # Output: True (default value)
|
|
58
|
+
|
|
59
|
+
# JSON data can include the default value explicitly
|
|
60
|
+
json_data_with_default = {"name": "Bob", "age": 25, "is_active": False}
|
|
61
|
+
user_explicit = User.from_json(json_data_with_default)
|
|
62
|
+
print(user_explicit.is_active) # Output: False
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Dump a User object back into JSON data:
|
|
66
|
+
|
|
67
|
+
```python
|
|
68
|
+
user_to_dump = User(name="Charlie", age=40, is_active=False)
|
|
69
|
+
dumped_data = User.to_json()
|
|
70
|
+
|
|
71
|
+
print(dumped_data) # Output: {'name': 'Charlie', 'age': 40, 'is_active': False}
|
|
72
|
+
|
|
73
|
+
# Default values are not included by default unless specified in the class
|
|
74
|
+
user_with_default = User(name="David", age=35)
|
|
75
|
+
dumped_data_default = user_with_default.to_json()
|
|
76
|
+
print(dumped_data_default) # Output: {'name': 'David', 'age': 35} (is_active is omitted)
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
## Defining Models
|
|
80
|
+
Define a JSON model by creating a class that inherits from `JSONModel` and using type annotations for the expected fields.
|
|
81
|
+
|
|
82
|
+
```python
|
|
83
|
+
from __future__ import annotations
|
|
84
|
+
|
|
85
|
+
from typing import Optional, Union
|
|
86
|
+
from SprelfJSON import JSONModel, ModelElem
|
|
87
|
+
import datetime
|
|
88
|
+
|
|
89
|
+
class Product(JSONModel):
|
|
90
|
+
id: int
|
|
91
|
+
name: str
|
|
92
|
+
price: float
|
|
93
|
+
tags: list[str] # List of strings
|
|
94
|
+
attributes: dict[str, str] # Dictionary with string keys and string values
|
|
95
|
+
description: Optional[str] = None # Optional field, can be None
|
|
96
|
+
created_at: datetime.datetime # Using a complex type
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
## Fields with Default Values
|
|
100
|
+
Provide any default values directly in the class definition:
|
|
101
|
+
|
|
102
|
+
```python
|
|
103
|
+
class Settings(JSONModel):
|
|
104
|
+
theme: str = "dark"
|
|
105
|
+
notifications_enabled: bool = True
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
For mutable default values (like lists or dictionaries), use `ModelElem` with `default_factory`:
|
|
109
|
+
|
|
110
|
+
```python
|
|
111
|
+
class UserProfile(JSONModel):
|
|
112
|
+
username: str
|
|
113
|
+
favorite_numbers: ModelElem(list[int], default_factory=list) # Use default_factory for mutable defaults
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
## Handling Different Types
|
|
117
|
+
This library handles a variety of common datatypes, converting them to and from native JSON types when dumping and parsing.
|
|
118
|
+
|
|
119
|
+
### JSON Native Types
|
|
120
|
+
`str`, `int`, `float`, `bool`, `None` are parsed and dumped directly.
|
|
121
|
+
|
|
122
|
+
### Complex Types
|
|
123
|
+
`datetime.datetime`, `datetime.date`, `datetime.time`, `datetime.timedelta`, `bytes`, `re.Pattern` are automatically
|
|
124
|
+
parsed and dumped to/from appropriate JSON representations (e.g., strings for dates/times, base64 for bytes, string for patterns).
|
|
125
|
+
|
|
126
|
+
```python
|
|
127
|
+
import datetime
|
|
128
|
+
import re
|
|
129
|
+
|
|
130
|
+
class Event(JSONModel):
|
|
131
|
+
start_time: datetime.datetime
|
|
132
|
+
duration: datetime.timedelta
|
|
133
|
+
event_id: bytes
|
|
134
|
+
pattern: re.Pattern
|
|
135
|
+
|
|
136
|
+
# Example usage
|
|
137
|
+
json_event = {
|
|
138
|
+
"start_time": "2023-10-27T14:00:00.000Z",
|
|
139
|
+
"duration": 3600000, # timedelta in milliseconds
|
|
140
|
+
"event_id": "YWJjMTIz", # base64 encoded bytes
|
|
141
|
+
"pattern": "^[A-Z]+$"
|
|
142
|
+
}
|
|
143
|
+
event = Event.from_json(json_event)
|
|
144
|
+
|
|
145
|
+
print(type(event.start_time).__name__) # Output: "datetime"
|
|
146
|
+
print(type(event.duration).__name__) # Output: "timedelta"
|
|
147
|
+
print(type(event.event_id).__name__) # Output: "bytes"
|
|
148
|
+
print(type(event.pattern).__name__) # Output: "Pattern"
|
|
149
|
+
|
|
150
|
+
dumped_event = event.to_json()
|
|
151
|
+
print(dumped_event) # Output: The original JSON
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
### Enums
|
|
155
|
+
`enum.Enum`, `enum.IntEnum`, `enum.StrEnum`, and `enum.IntFlag` are supported. Plain Enums are dumped by name, the others by value. They can be parsed as either.
|
|
156
|
+
|
|
157
|
+
```python
|
|
158
|
+
import enum
|
|
159
|
+
|
|
160
|
+
class Status(enum.Enum):
|
|
161
|
+
PENDING = "pending"
|
|
162
|
+
PROCESSING = "processing"
|
|
163
|
+
COMPLETED = "completed"
|
|
164
|
+
|
|
165
|
+
class ErrorCode(enum.IntEnum):
|
|
166
|
+
NOT_FOUND = 404
|
|
167
|
+
INTERNAL_ERROR = 500
|
|
168
|
+
|
|
169
|
+
class Flags(enum.IntFlag):
|
|
170
|
+
FLAG_A = 1
|
|
171
|
+
FLAG_B = 2
|
|
172
|
+
FLAG_C = 4
|
|
173
|
+
|
|
174
|
+
class Task(JSONModel):
|
|
175
|
+
status: Status
|
|
176
|
+
error_code: Optional[ErrorCode] = None
|
|
177
|
+
flags: Flags
|
|
178
|
+
|
|
179
|
+
# Example usage
|
|
180
|
+
json_task = {
|
|
181
|
+
"status": "PROCESSING",
|
|
182
|
+
"flags": 3 # FLAG_A | FLAG_B
|
|
183
|
+
}
|
|
184
|
+
task = Task.from_json(json_task)
|
|
185
|
+
|
|
186
|
+
print(task.status) # Output: Status.PROCESSING
|
|
187
|
+
print(task.flags) # Output: Flags.FLAG_A | Flags.FLAG_B
|
|
188
|
+
|
|
189
|
+
dumped_task = task.to_json()
|
|
190
|
+
print(dumped_task) # Output: {'status': 'PROCESSING', 'flags': 3}
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
### Generic Types
|
|
194
|
+
`list`, `dict`, `set`, `frozenset`, `tuple`, `type`, `Iterable`, `Iterator`, `Generator`, `Sequence`, `MutableSequence`, `Set`, `MutableSet`, `Mapping`, `MutableMapping`, `Collection`, `Union`, and `Optional` are supported.
|
|
195
|
+
|
|
196
|
+
The following classes maintain any lazy properties when parsing (deferring validation until iterated): `Iterable`, `Iterator`, `Generator`
|
|
197
|
+
|
|
198
|
+
```python
|
|
199
|
+
from __future__ import annotations
|
|
200
|
+
from typing import Union, Optional
|
|
201
|
+
from SprelfJSON import JSONModel
|
|
202
|
+
|
|
203
|
+
class DataContainer(JSONModel):
|
|
204
|
+
items: list[int]
|
|
205
|
+
settings: dict[str, bool]
|
|
206
|
+
value: Union[str, int]
|
|
207
|
+
optional_items: Optional[list[float]]
|
|
208
|
+
a_type: type[JSONModel]
|
|
209
|
+
coords: tuple[float, float]
|
|
210
|
+
tags: set[str]
|
|
211
|
+
|
|
212
|
+
# Example usage
|
|
213
|
+
json_data = {
|
|
214
|
+
"items": [1, 2, 3],
|
|
215
|
+
"settings": {"enabled": True, "visible": False},
|
|
216
|
+
"value": "hello",
|
|
217
|
+
"optional_items": [1.1, 2.2],
|
|
218
|
+
"a_type": "SomeJSONModelType",
|
|
219
|
+
"coords": [10.5, 20.1], # JSON array is parsed as tuple
|
|
220
|
+
"tags": ["tag1", "tag2", "tag1"] # JSON array is parsed as set
|
|
221
|
+
}
|
|
222
|
+
container = DataContainer.from_json(json_data)
|
|
223
|
+
|
|
224
|
+
print(type(container.items).__name__) # Output: "list"
|
|
225
|
+
print(type(container.settings).__name__) # Output: "dict"
|
|
226
|
+
print(type(container.value).__name__) # Output: "str"
|
|
227
|
+
print(type(container.optional_items).__name__) # Output: "list"
|
|
228
|
+
print(type(container.a_type).__name__) # Output: "type"
|
|
229
|
+
print(type(container.coords).__name__) # Output: "tuple"
|
|
230
|
+
print(type(container.tags).__name__) # Output: "set"
|
|
231
|
+
|
|
232
|
+
dumped_data = container.to_json()
|
|
233
|
+
print(dumped_data) # Note: sets and tuples are dumped as JSON arrays (lists)
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
### Nested Models
|
|
237
|
+
You can nest `JSONModel` definitions within other `JSONModel`s.
|
|
238
|
+
|
|
239
|
+
```python
|
|
240
|
+
class Address(JSONModel):
|
|
241
|
+
street: str
|
|
242
|
+
city: str
|
|
243
|
+
zip_code: str
|
|
244
|
+
|
|
245
|
+
class Order(JSONModel):
|
|
246
|
+
order_num: int
|
|
247
|
+
|
|
248
|
+
class Customer(JSONModel):
|
|
249
|
+
customer_id: int
|
|
250
|
+
name: str
|
|
251
|
+
shipping_address: Address
|
|
252
|
+
past_orders: list[Order]
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
### Dynamic Subclass Parsing
|
|
256
|
+
`JSONModel` can automatically determine and instantiate the correct subclass based on a specified field in the JSON data.
|
|
257
|
+
|
|
258
|
+
Define a base class and subclasses:
|
|
259
|
+
|
|
260
|
+
```python
|
|
261
|
+
class Shape(JSONModel):
|
|
262
|
+
# Base class - often abstract, but can have common fields
|
|
263
|
+
__name_field__ = "type" # Field to check for subclass name
|
|
264
|
+
__name_field_required__ = True # Require the type field
|
|
265
|
+
|
|
266
|
+
color: str
|
|
267
|
+
|
|
268
|
+
class Circle(Shape):
|
|
269
|
+
radius: float
|
|
270
|
+
|
|
271
|
+
@classmethod
|
|
272
|
+
def model_identity(cls) -> str:
|
|
273
|
+
return "circle" # Value in the 'type' field for this subclass
|
|
274
|
+
|
|
275
|
+
class Square(Shape):
|
|
276
|
+
side_length: float
|
|
277
|
+
# Use default identity for this class (class's name, 'Square')
|
|
278
|
+
|
|
279
|
+
# You can then have a model containing a list of shapes
|
|
280
|
+
class Drawing(JSONModel):
|
|
281
|
+
shapes: list[Shape] # List can contain Circle or Square objects
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
Parse JSON containing different shape types:
|
|
285
|
+
|
|
286
|
+
```python
|
|
287
|
+
json_drawing = {
|
|
288
|
+
"shapes": [
|
|
289
|
+
{"type": "circle", "color": "red", "radius": 10.0},
|
|
290
|
+
{"type": "Square", "color": "blue", "side_length": 5.0},
|
|
291
|
+
{"type": "circle", "color": "green", "radius": 2.5}
|
|
292
|
+
]
|
|
293
|
+
}
|
|
294
|
+
|
|
295
|
+
drawing = Drawing.from_json(json_drawing)
|
|
296
|
+
|
|
297
|
+
for shape in drawing.shapes:
|
|
298
|
+
print(f"Shape color: {shape.color}")
|
|
299
|
+
if isinstance(shape, Circle):
|
|
300
|
+
print(f"Circle radius: {shape.radius}")
|
|
301
|
+
elif isinstance(shape, Square):
|
|
302
|
+
print(f"Square side length: {shape.side_length}")
|
|
303
|
+
|
|
304
|
+
# Output -
|
|
305
|
+
# Shape color: red
|
|
306
|
+
# Circle radius: 10.0
|
|
307
|
+
# Shape color: blue
|
|
308
|
+
# Square side length: 5.0
|
|
309
|
+
# Shape color: green
|
|
310
|
+
# Circle radius: 2.5
|
|
311
|
+
```
|
|
312
|
+
|
|
313
|
+
By default:
|
|
314
|
+
- The name field (specified by `__name_field__`) is `"__name"`
|
|
315
|
+
- The name field is required
|
|
316
|
+
- The model identity for a class (the matching value to find in this name field) is the name of the class (ie. `cls.__name__`)
|
|
317
|
+
|
|
318
|
+
See "Extra Options" section for more details.
|
|
319
|
+
|
|
320
|
+
### Support for Additional Types
|
|
321
|
+
|
|
322
|
+
To extend the supported types, create a new class that is a subclass of `ModelType`, implementing
|
|
323
|
+
the required methods.
|
|
324
|
+
|
|
325
|
+
```python
|
|
326
|
+
class ModelType_PatternExample(ModelType):
|
|
327
|
+
|
|
328
|
+
# This is used to test whether this model type applies to the given model element.
|
|
329
|
+
# The first ModelType to return True here is the one used.
|
|
330
|
+
@classmethod
|
|
331
|
+
def test_origin(cls, elem: _BaseModelElem, **kwargs) -> bool:
|
|
332
|
+
return elem.origin == re.Pattern
|
|
333
|
+
|
|
334
|
+
# This is used for validating if a value in a particular field meets the criteria for this type
|
|
335
|
+
@classmethod
|
|
336
|
+
def is_valid(cls, val: Any, elem: _BaseModelElem, **kwargs) -> bool:
|
|
337
|
+
return isinstance(val, elem.origin)
|
|
338
|
+
|
|
339
|
+
# This is used for parsing a value to the desired type; usually is given a JSON value
|
|
340
|
+
@classmethod
|
|
341
|
+
def parse(cls, val: Any, elem: _BaseModelElem, **kwargs) -> type[SupportedUnion]:
|
|
342
|
+
if isinstance(val, re.Pattern):
|
|
343
|
+
return val
|
|
344
|
+
if isinstance(val, str):
|
|
345
|
+
return re.compile(val)
|
|
346
|
+
raise ModelElemError(elem, "Woops, can't parse this!")
|
|
347
|
+
|
|
348
|
+
# This is used to dump the value into a JSON-compatible type
|
|
349
|
+
@classmethod
|
|
350
|
+
def dump(cls, val: Any, elem: _BaseModelElem, **kwargs) -> JSONType:
|
|
351
|
+
definitely_a_pattern_now = elem.parse_value(val, **kwargs)
|
|
352
|
+
return definitely_a_pattern_now.pattern # This is a str
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
> **Note:**
|
|
356
|
+
>
|
|
357
|
+
>A list of all `ModelType` subclasses is cached the first time any `JSONModel` object is
|
|
358
|
+
>dumped, parsed, or validated. As long as your subclass is defined before this, it will be automatically included.
|
|
359
|
+
>If you need further manipulation of the allowed types, see `_AliasedModelTypes` and `_ConcreteModelTypes` on `ModelElem`
|
|
360
|
+
|
|
361
|
+
|
|
362
|
+
### Alternate Parsing and Dumping
|
|
363
|
+
Use `AlternateModelElem` within a `ModelElem` definition to specify alternative ways to parse incoming data or dump outgoing data.
|
|
364
|
+
These objects are defined like `ModelElem`, but expect to find a different type, and define a function to convert
|
|
365
|
+
from that type to the original type that the `ModelElem` expects.
|
|
366
|
+
|
|
367
|
+
When parsing or dumping, it will first attempt to operate in its native type. Only if that fails, it will then attempt
|
|
368
|
+
doing so with each of the defined alternate definitions. To override this behavior and forcibly use these alternates, you
|
|
369
|
+
may provide the `use_alternates_only` parameter.
|
|
370
|
+
|
|
371
|
+
```python
|
|
372
|
+
from SprelfJSON import JSONModel, ModelElem, AlternateModelElem
|
|
373
|
+
|
|
374
|
+
class DataItem(JSONModel):
|
|
375
|
+
# Can parse an integer from a string
|
|
376
|
+
count: ModelElem(int, alternates=[AlternateModelElem(str, int)])
|
|
377
|
+
|
|
378
|
+
# Can dump a boolean as a string "true" or "false"
|
|
379
|
+
is_valid: ModelElem(bool, alternates=[AlternateModelElem(str, lambda s: s.lower() == "true", jsonifier=lambda b: str(b).lower())],
|
|
380
|
+
use_alternates_only=True)
|
|
381
|
+
|
|
382
|
+
# Example usage
|
|
383
|
+
json_data = {
|
|
384
|
+
"count": "50", # Input is string
|
|
385
|
+
"is_valid": "True" # Input is string
|
|
386
|
+
}
|
|
387
|
+
item = DataItem.from_json(json_data)
|
|
388
|
+
|
|
389
|
+
print(item.count) # Output: 50 (parsed as int)
|
|
390
|
+
print(item.is_valid) # Output: True (parsed as bool)
|
|
391
|
+
|
|
392
|
+
dumped_data = item.to_json()
|
|
393
|
+
print(dumped_data) # Output: {'count': 50, 'is_valid': "true"} # 'count' dumped as int, 'is_valid' dumped as string
|
|
394
|
+
```
|
|
395
|
+
|
|
396
|
+
## Error Handling
|
|
397
|
+
`JSONModel` uses `JSONModelError` and a subclass `ModelElemError` to indicate issues during parsing,
|
|
398
|
+
validation, or dumping.
|
|
399
|
+
|
|
400
|
+
```python
|
|
401
|
+
from SprelfJSON import JSONModel, JSONModelError
|
|
402
|
+
|
|
403
|
+
class StrictModel(JSONModel):
|
|
404
|
+
required_field: str
|
|
405
|
+
int_field: int
|
|
406
|
+
|
|
407
|
+
# Example of missing required field error
|
|
408
|
+
json_missing = {"int_field": 123}
|
|
409
|
+
try:
|
|
410
|
+
StrictModel.from_json(json_missing)
|
|
411
|
+
except JSONModelError as e:
|
|
412
|
+
print(f"Caught expected error: {e}") # Output: Caught expected error: Missing required key 'required_field' on 'StrictModel'.
|
|
413
|
+
|
|
414
|
+
# Example of invalid type error
|
|
415
|
+
json_invalid_type = {"required_field": "hello", "int_field": "not an int"}
|
|
416
|
+
try:
|
|
417
|
+
StrictModel.from_json(json_invalid_type)
|
|
418
|
+
except JSONModelError as e:
|
|
419
|
+
print(f"Caught expected error: {e}") # Output: Caught expected error: Model error on key 'int_field' of 'StrictModel': Schema mismatch: Expected type '<class 'int'>', but got 'str' instead
|
|
420
|
+
|
|
421
|
+
# Example of extra field error (by default)
|
|
422
|
+
json_extra_field = {"required_field": "hello", "int_field": 123, "extra": "data"}
|
|
423
|
+
try:
|
|
424
|
+
StrictModel.from_json(json_extra_field)
|
|
425
|
+
except JSONModelError as e:
|
|
426
|
+
print(f"Caught expected error: {e}") # Output: Caught expected error: The following keys are not found in the model for 'StrictModel': extra
|
|
427
|
+
```
|
|
428
|
+
|
|
429
|
+
|
|
430
|
+
## Extra Options
|
|
431
|
+
|
|
432
|
+
There are some class-level options in `JSONModel` to define certain types of behavior by the class it's applied to and all subclasses.
|
|
433
|
+
|
|
434
|
+
- `__name_field__: str`: When parsing, the name of the JSON field that stores the name of the `JSONModel` object to dynamically parse. Defaults as `"__name"`
|
|
435
|
+
- `__name_field_required__: bool`: When parsing, will reject any JSON objects that do not have the name field defined. Defaults as `True`
|
|
436
|
+
- `__allow_null_json_output__: bool`: When dumping, whether to include the name field in the output. Defaults as `True`
|
|
437
|
+
- `__allow_null_json_output__: bool`: When dumping, whether to allow null JSON values. Defaults as `False`
|
|
438
|
+
- `__include_defaults_in_json_output__: bool`: When dumping, whether to include fields whose values are equal to the default value. Defaults as `False`.
|
|
439
|
+
- `__allow_extra_fields__: bool`: When parsing, whether to ignore extra fields that don't belong to the model. If `False`, then an error is raised if extra fields are found. Defaults as `False`
|
|
440
|
+
- `__exclusions__: list[str]`: A list of fields that are defined, but should be ignored for the purposes of parsing/dumping.
|
|
441
|
+
- `__eval_context__: dict[str, ...]`: A map of modules and classes to include when evaluating the annotations (which are read as strings) into actual types.
|
|
442
|
+
|
|
443
|
+
There are additional class-level options in `ModelElem`:
|
|
444
|
+
- `__base64_altchars__: tuple[bytes, ...]`: A list of 2-character byte strings that define the allowable base64 alternate characters when parsing a string to `bytes`.
|
|
445
|
+
The parser will try each one in order until one succeeds. The dumper will always use the first byte string here. By default, is defined as `(b"-_", b"+/")`, preferring URL-safe altchars.
|
|
446
|
+
|
|
447
|
+
## Known issues
|
|
448
|
+
|
|
449
|
+
- When subclassing a `JSONModel` subclass that has a default value in a field, IDEs may provide a warning related to "non-default arguments following default arguments". When actually running the code, there is no issue here, so it's safe to ignore or suppress such warnings.
|