0
# jsons
1

2
A comprehensive Python library for serializing and deserializing Python objects to and from JSON (dictionaries) with minimal code changes required. The jsons package provides automatic conversion of complex Python objects including dataclasses, attrs classes, and Plain Old Python Objects (POPOs) to JSON-compatible dictionaries and back, with intelligent type inference and customizable serialization/deserialization behavior. It handles complex nested structures, generic types from the typing module, and provides extensive support for built-in Python types including datetime objects, pathlib.Path, Decimal, Enum, Union types, and various collections.
3

4
## Package Information
5

6
- **Package Name**: jsons
7
- **Language**: Python  
8
- **Installation**: `pip install jsons`
9

10
## Core Imports
11

12
```python { .api }
13
import jsons
14
from jsons import JsonSerializable
15
```
16

17
The primary import provides access to all core serialization functions (`dump`, `load`), while `JsonSerializable` offers a class-based approach for objects that need built-in JSON capabilities.
18

19
## Basic Usage
20

21
```python
22
import jsons
23
from dataclasses import dataclass
24

25
# Define a dataclass
26
@dataclass
27
class Car:
28
    color: str
29
    model: str
30

31
@dataclass  
32
class Person:
33
    name: str
34
    car: Car
35

36
# Create objects
37
car = Car("red", "Toyota")
38
person = Person("John", car)
39

40
# Serialize to JSON-compatible dict
41
person_dict = jsons.dump(person)
42
print(person_dict)
43
# {'name': 'John', 'car': {'color': 'red', 'model': 'Toyota'}}
44

45
# Deserialize back to object
46
person_restored = jsons.load(person_dict, Person)
47
print(person_restored.name)  # "John"
48
print(person_restored.car.color)  # "red"
49
```
50

51
For classes without dataclass decorators, use type hints for custom types:
52

53
```python
54
import jsons
55

56
class Car:
57
    def __init__(self, color: str):
58
        self.color = color
59

60
class Person:
61
    def __init__(self, car: Car, name: str):
62
        self.car = car
63
        self.name = name
64

65
# Usage is identical
66
car = Car("blue")  
67
person = Person(car, "Jane")
68
person_dict = jsons.dump(person)
69
person_restored = jsons.load(person_dict, Person)
70
```
71

72
Alternative class-based approach using `JsonSerializable`:
73

74
```python
75
import jsons
76
from jsons import JsonSerializable
77

78
class Person(JsonSerializable):
79
    def __init__(self, name: str, age: int):
80
        self.name = name
81
        self.age = age
82

83
person = Person("Alice", 30)
84

85
# Serialize using property
86
person_dict = person.json
87
print(person_dict)  # {'name': 'Alice', 'age': 30}
88

89
# Deserialize using class method
90
person_restored = Person.from_json(person_dict)
91
print(person_restored.name)  # "Alice"
92
```
93

94
## Capabilities
95

96
### [Core Serialization](./core-serialization.md)
97
Primary functions for converting Python objects to JSON-compatible formats and back. Handles automatic type detection, nested objects, and custom serialization logic.
98

99
```python { .api }
100
def dump(obj, cls=None, *, strict=False, **kwargs): ...
101
def dumps(obj, cls=None, *, strict=False, **kwargs): ...  
102
def dumpb(obj, cls=None, *, strict=False, **kwargs): ...
103
def load(json_obj, cls=None, *, strict=False, **kwargs): ...
104
def loads(s, cls=None, *, strict=False, **kwargs): ...
105
def loadb(b, cls=None, *, strict=False, **kwargs): ...
106
```
107

108
### [Class Integration](./class-integration.md)
109
Base classes and utilities for integrating JSON serialization directly into your Python classes. Provides `JsonSerializable` base class with built-in `json` property and `from_json` class method.
110

111
```python { .api }
112
class JsonSerializable:
113
    @property
114
    def json(self): ...
115
    @classmethod  
116
    def from_json(cls, json_obj, **kwargs): ...
117
    @classmethod
118
    def fork(cls, name=None): ...
119
    @classmethod
120
    def with_dump(cls, fork=False, **kwargs): ...
121
    @classmethod
122
    def with_load(cls, fork=False, **kwargs): ...
123
```
124

125
### [Type System](./type-system.md)
126
Comprehensive support for Python's type system including built-in types, collections, datetime objects, Enum types, Union types, and custom objects. Provides default serializers and deserializers for all common Python types.
127

128
```python { .api }
129
# Built-in type support for:
130
# - Primitives: str, int, float, bool, None
131
# - Collections: list, tuple, dict, set, frozenset  
132
# - Date/Time: datetime, date, time, timezone, timedelta
133
# - Other: Decimal, UUID, complex, Enum, pathlib.Path
134
```
135

136
### [Customization](./customization.md)
137
Extensible serializer and deserializer system for handling custom types and modifying default behavior. Includes serializer registration, validation, and key transformation utilities.
138

139
```python { .api }
140
def set_serializer(func, cls, high_prio=True, **kwargs): ...
141
def get_serializer(cls, **kwargs): ...
142
def set_deserializer(func, cls, high_prio=True, **kwargs): ...
143
def get_deserializer(cls, **kwargs): ...
144
def set_validator(func, cls, **kwargs): ...
145
def get_validator(cls, **kwargs): ...
146
```
147

148
### [Key Transformation](./key-transformation.md)
149
Utilities for transforming dictionary keys between different naming conventions (camelCase, snake_case, PascalCase, lisp-case).
150

151
```python { .api }
152
def camelcase(str_): ...
153
def snakecase(str_): ...  
154
def pascalcase(str_): ...
155
def lispcase(str_): ...
156
```
157

158
### [Configuration & Control](./configuration.md)
159
Advanced configuration options including fork management for separate serializer configurations, warning control, verbosity settings, and object transformation.
160

161
```python { .api }
162
def fork(fork_inst=StateHolder, name=None): ...
163
def transform(obj, cls, *, mapper=None, **kwargs): ...
164
def suppress_warnings(do_suppress=True, **kwargs): ...
165
def suppress_warning(code, **kwargs): ...
166
def validate(obj, cls, **kwargs): ...
167
```