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.
@@ -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.