0
# JSON Processing
1

2
High-performance JSON parsing and serialization functions with extensive configuration options for handling edge cases, infinity/NaN values, and custom serialization formats. These functions provide fast JSON operations that significantly outperform Python's standard library.
3

4
## Capabilities
5

6
### JSON Parsing
7

8
Fast JSON parsing with support for various parsing options and edge case handling.
9

10
```python { .api }
11
def from_json(data, *, allow_inf_nan=True, cache_strings='all', allow_partial='off'):
12
    """
13
    Parse JSON data into Python objects with high performance.
14
    
15
    Args:
16
        data: JSON string, bytes, or bytearray to parse
17
        allow_inf_nan: Whether to allow parsing of Infinity and NaN values
18
        cache_strings: String caching mode ('all', 'keys', 'none')
19
        allow_partial: Partial parsing mode ('off', 'on', 'trailing-strings')
20
        
21
    Returns:
22
        Parsed Python object (dict, list, str, int, float, bool, or None)
23
        
24
    Raises:
25
        ValueError: If JSON is invalid or parsing fails
26
    """
27
```
28

29
### JSON Serialization
30

31
Fast JSON serialization with extensive formatting and filtering options.
32

33
```python { .api }
34
def to_json(obj, *, indent=None, include=None, exclude=None, by_alias=False, exclude_unset=False, exclude_defaults=False, exclude_none=False, round_trip=False, warnings=True, fallback=None, serialize_as_any=False) -> bytes:
35
    """
36
    Serialize Python objects to JSON bytes with high performance.
37
    
38
    Args:
39
        obj: Python object to serialize
40
        indent: JSON indentation (None for compact, int for spaces, str for custom)
41
        include: Set/dict of fields to include (None for all)
42
        exclude: Set/dict of fields to exclude (None for none)
43
        by_alias: Whether to use field aliases during serialization
44
        exclude_unset: Whether to exclude fields that were not explicitly set
45
        exclude_defaults: Whether to exclude fields with default values
46
        exclude_none: Whether to exclude fields with None values
47
        round_trip: Whether to preserve exact types for round-trip compatibility
48
        warnings: Whether to show serialization warnings
49
        fallback: Function to handle non-serializable values
50
        serialize_as_any: Whether to serialize unknown types as Any
51
        
52
    Returns:
53
        JSON as bytes
54
        
55
    Raises:
56
        PydanticSerializationError: If serialization fails
57
    """
58
```
59

60
### Python Object Serialization
61

62
Convert data to JSON-serializable Python objects without actually serializing to JSON.
63

64
```python { .api }
65
def to_jsonable_python(obj, *, fallback=None, serialize_as_any=False, when_used='json'):
66
    """
67
    Convert Python objects to JSON-serializable Python objects.
68
    
69
    Args:
70
        obj: Python object to convert
71
        fallback: Function to handle non-serializable values
72
        serialize_as_any: Whether to serialize unknown types as Any
73
        when_used: Context hint for serialization ('json' or 'python')
74
        
75
    Returns:
76
        JSON-serializable Python object (dict, list, str, int, float, bool, or None)
77
        
78
    Raises:
79
        PydanticSerializationError: If conversion fails
80
    """
81
```
82

83
### Utility Functions
84

85
Additional utility functions for error handling and build information.
86

87
```python { .api }
88
def list_all_errors() -> list[ErrorTypeInfo]:
89
    """
90
    Get information about all available error types.
91
    
92
    Returns:
93
        List of ErrorTypeInfo dictionaries containing error type metadata
94
    """
95

96
# Build and version information
97
__version__: str  # Current version of pydantic-core
98
build_profile: str  # Build profile used (debug/release/etc.)
99
build_info: str  # Build information and compilation details
100
_recursion_limit: int  # Maximum recursion limit for validation
101
```
102

103
## Usage Examples
104

105
### Basic JSON Parsing
106

107
```python
108
from pydantic_core import from_json
109

110
# Parse simple JSON
111
json_str = '{"name": "Alice", "age": 30, "active": true}'
112
result = from_json(json_str)
113
print(result)  # {'name': 'Alice', 'age': 30, 'active': True}
114

115
# Parse JSON from bytes
116
json_bytes = b'[1, 2, 3, "hello", null]'
117
result = from_json(json_bytes)
118
print(result)  # [1, 2, 3, 'hello', None]
119

120
# Parse with special values
121
json_with_inf = '{"value": Infinity, "nan_value": NaN}'
122
result = from_json(json_with_inf, allow_inf_nan=True)
123
print(result)  # {'value': inf, 'nan_value': nan}
124

125
# Disable special value parsing
126
try:
127
    from_json(json_with_inf, allow_inf_nan=False)
128
except ValueError as e:
129
    print(f"Error: {e}")  # Error: Invalid JSON
130
```
131

132
### String Caching Options
133

134
```python
135
from pydantic_core import from_json
136

137
# Different string caching modes
138
large_json = '{"key1": "value1", "key2": "value2", "key1": "value3"}'
139

140
# Cache all strings (default, fastest for repeated strings)
141
result1 = from_json(large_json, cache_strings='all')
142

143
# Cache only keys (good balance for objects with unique values)
144
result2 = from_json(large_json, cache_strings='keys')
145

146
# No caching (lowest memory usage)
147
result3 = from_json(large_json, cache_strings='none')
148
```
149

150
### Basic JSON Serialization
151

152
```python
153
from pydantic_core import to_json
154

155
# Serialize simple data
156
data = {'name': 'Bob', 'age': 25, 'scores': [95, 87, 92]}
157
json_bytes = to_json(data)
158
print(json_bytes.decode())  # {"name":"Bob","age":25,"scores":[95,87,92]}
159

160
# Serialize with formatting
161
formatted = to_json(data, indent=2)
162
print(formatted.decode())
163
# {
164
#   "name": "Bob",
165
#   "age": 25,
166
#   "scores": [
167
#     95,
168
#     87,
169
#     92
170
#   ]
171
# }
172

173
# Serialize with custom indentation
174
custom_indent = to_json(data, indent='    ')  # 4 spaces
175
print(custom_indent.decode())
176
```
177

178
### Filtering During Serialization
179

180
```python
181
from pydantic_core import to_json
182

183
data = {
184
    'id': 123,
185
    'name': 'Charlie',
186
    'email': 'charlie@example.com',
187
    'password': 'secret123',
188
    'active': True,
189
    'metadata': None
190
}
191

192
# Include only specific fields
193
public_json = to_json(data, include={'id', 'name', 'active'})
194
print(public_json.decode())  # {"id":123,"name":"Charlie","active":true}
195

196
# Exclude sensitive fields
197
safe_json = to_json(data, exclude={'password'})
198
print(safe_json.decode())  # {"id":123,"name":"Charlie","email":"charlie@example.com","active":true,"metadata":null}
199

200
# Exclude None values
201
no_nulls = to_json(data, exclude_none=True)
202
print(no_nulls.decode())  # {"id":123,"name":"Charlie","email":"charlie@example.com","password":"secret123","active":true}
203
```
204

205
### Handling Non-Serializable Values
206

207
```python
208
from pydantic_core import to_json
209
from datetime import datetime, date
210
import uuid
211

212
# Data with non-JSON-native types
213
data = {
214
    'timestamp': datetime.now(),
215
    'date': date.today(),
216
    'id': uuid.uuid4(),
217
    'custom_object': object()
218
}
219

220
# Define fallback function
221
def serialize_fallback(obj):
222
    if isinstance(obj, datetime):
223
        return obj.isoformat()
224
    elif isinstance(obj, date):
225
        return obj.isoformat()
226
    elif isinstance(obj, uuid.UUID):
227
        return str(obj)
228
    else:
229
        return f"<{type(obj).__name__} object>"
230

231
# Serialize with fallback
232
result = to_json(data, fallback=serialize_fallback)
233
print(result.decode())
234
# {"timestamp":"2023-10-15T10:30:45.123456","date":"2023-10-15","id":"123e4567-e89b-12d3-a456-426614174000","custom_object":"<object object>"}
235

236
# Without fallback, non-serializable values cause errors
237
try:
238
    to_json(data)
239
except Exception as e:
240
    print(f"Serialization error: {e}")
241
```
242

243
### Python Object Conversion
244

245
```python
246
from pydantic_core import to_jsonable_python
247
from datetime import datetime
248
from decimal import Decimal
249

250
# Convert complex data to JSON-serializable Python objects
251
data = {
252
    'name': 'Dave',
253
    'balance': Decimal('123.45'),
254
    'created': datetime(2023, 10, 15, 10, 30, 45),
255
    'settings': {'theme': 'dark', 'notifications': True}
256
}
257

258
# Convert to JSON-serializable objects
259
json_safe = to_jsonable_python(data)
260
print(json_safe)
261
# Output will convert Decimal and datetime to appropriate JSON-safe types
262

263
# Use with standard json module
264
import json
265
json_str = json.dumps(json_safe)
266
print(json_str)
267
```
268

269
### Round-Trip Serialization
270

271
```python
272
from pydantic_core import to_json, from_json
273
from datetime import datetime
274

275
# Data that needs to preserve exact types
276
original_data = {
277
    'timestamp': datetime(2023, 10, 15, 10, 30, 45),
278
    'precision_number': 123.456789012345
279
}
280

281
# Serialize with round-trip preservation
282
json_bytes = to_json(original_data, round_trip=True)
283

284
# Parse back - types should be preserved
285
restored_data = from_json(json_bytes)
286

287
# Verify round-trip integrity
288
print(f"Original: {original_data}")
289
print(f"Restored: {restored_data}")
290
print(f"Types match: {type(original_data['timestamp']) == type(restored_data['timestamp'])}")
291
```
292

293
### Performance Comparison
294

295
```python
296
import json
297
from pydantic_core import from_json, to_json
298
import time
299

300
# Large data for performance testing
301
large_data = {
302
    'users': [
303
        {'id': i, 'name': f'User{i}', 'email': f'user{i}@example.com'}
304
        for i in range(10000)
305
    ]
306
}
307

308
# Serialize with pydantic-core
309
start = time.time()
310
pydantic_json = to_json(large_data)
311
pydantic_serialize_time = time.time() - start
312

313
# Serialize with standard library
314
start = time.time()
315
stdlib_json = json.dumps(large_data).encode()
316
stdlib_serialize_time = time.time() - start
317

318
print(f"pydantic-core serialization: {pydantic_serialize_time:.4f}s")
319
print(f"stdlib serialization: {stdlib_serialize_time:.4f}s")
320
print(f"pydantic-core is {stdlib_serialize_time/pydantic_serialize_time:.1f}x faster")
321

322
# Parse with pydantic-core
323
start = time.time()
324
pydantic_parsed = from_json(pydantic_json)
325
pydantic_parse_time = time.time() - start
326

327
# Parse with standard library
328
start = time.time()
329
stdlib_parsed = json.loads(stdlib_json.decode())
330
stdlib_parse_time = time.time() - start
331

332
print(f"pydantic-core parsing: {pydantic_parse_time:.4f}s")
333
print(f"stdlib parsing: {stdlib_parse_time:.4f}s")
334
print(f"pydantic-core is {stdlib_parse_time/pydantic_parse_time:.1f}x faster")
335
```