0
# UltraJSON (ujson)
1

2
UltraJSON is an ultra-fast JSON encoder and decoder written in pure C with Python bindings. It provides drop-in compatibility with Python's standard json module while delivering significantly better performance for both encoding and decoding operations.
3

4
## Package Information
5

6
- **Package Name**: ujson
7
- **Language**: Python (C extension)
8
- **Installation**: `pip install ujson`
9
- **Python Support**: 3.9+
10

11
## Core Imports
12

13
```python
14
import ujson
15
```
16

17
## Basic Usage
18

19
```python
20
import ujson
21

22
# Basic encoding (Python object to JSON string)
23
data = {"name": "John", "age": 30, "items": [1, 2, 3]}
24
json_string = ujson.dumps(data)
25
print(json_string)  # '{"name":"John","age":30,"items":[1,2,3]}'
26

27
# Basic decoding (JSON string to Python object)
28
parsed_data = ujson.loads(json_string)
29
print(parsed_data)  # {'name': 'John', 'age': 30, 'items': [1, 2, 3]}
30

31
# File operations
32
with open('data.json', 'w') as f:
33
    ujson.dump(data, f)
34

35
with open('data.json', 'r') as f:
36
    loaded_data = ujson.load(f)
37

38
# Advanced encoding options
39
safe_html = ujson.dumps("<script>alert('hi')</script>", encode_html_chars=True)
40
pretty_json = ujson.dumps(data, indent=4)
41
ascii_only = ujson.dumps("café", ensure_ascii=True)
42
```
43

44
## Architecture
45

46
UltraJSON is implemented as a Python C extension module, providing exceptional performance through:
47

48
- **C Implementation Core**: The encoding and decoding engines are written in pure C, bypassing Python's interpreter overhead for JSON processing operations
49
- **Memory-Optimized Parsing**: Direct memory manipulation and efficient buffer management eliminate unnecessary Python object allocations during parsing
50
- **Drop-in Compatibility**: Python module interface mirrors the standard `json` module exactly, allowing seamless replacement without code changes
51
- **Extension Module Structure**: Built as a compiled extension (`ujson.c`, `objToJSON.c`, `JSONtoObj.c`) that integrates with Python's C API
52
- **Double-conversion Integration**: Uses the Google double-conversion library for high-performance floating-point number serialization
53

54
This architecture delivers significant performance gains over pure Python implementations while maintaining full compatibility with Python's standard JSON interface and data types.
55

56
## Capabilities
57

58
### JSON Encoding Functions
59

60
Converts Python objects to JSON strings with various formatting and safety options.
61

62
```python { .api }
63
def encode(
64
    obj,
65
    ensure_ascii=True,
66
    encode_html_chars=False,
67
    escape_forward_slashes=True,
68
    sort_keys=False,
69
    indent=0,
70
    allow_nan=True,
71
    reject_bytes=False,
72
    default=None,
73
    separators=None
74
):
75
    """
76
    Convert Python object to JSON string.
77
    
78
    Args:
79
        obj: Any Python object to serialize
80
        ensure_ascii (bool): Limit output to ASCII and escape extended characters (default: True)
81
        encode_html_chars (bool): Encode unsafe HTML characters as Unicode escapes (default: False)
82
        escape_forward_slashes (bool): Control forward slash escaping (default: True)
83
        sort_keys (bool): Sort dictionary keys in output (default: False)
84
        indent (int): Pretty print indentation, 0 = disabled (default: 0)
85
        allow_nan (bool): Allow NaN/Infinity values (default: True)
86
        reject_bytes (bool): Raise TypeError on bytes objects (default: False)
87
        default (callable, optional): Function to serialize arbitrary types
88
        separators (tuple, optional): (item_separator, key_separator) tuple
89
    
90
    Returns:
91
        str: JSON string representation
92
    """
93

94
def dumps(
95
    obj,
96
    ensure_ascii=True,
97
    encode_html_chars=False,
98
    escape_forward_slashes=True,
99
    sort_keys=False,
100
    indent=0,
101
    allow_nan=True,
102
    reject_bytes=False,
103
    default=None,
104
    separators=None
105
):
106
    """
107
    Alias for encode(). Convert Python object to JSON string.
108
    
109
    Args: Identical to encode()
110
    
111
    Returns:
112
        str: JSON string representation
113
    """
114

115
def dump(
116
    obj,
117
    fp,
118
    *,
119
    ensure_ascii=True,
120
    encode_html_chars=False,
121
    escape_forward_slashes=True,
122
    sort_keys=False,
123
    indent=0,
124
    allow_nan=True,
125
    reject_bytes=False,
126
    default=None,
127
    separators=None
128
):
129
    """
130
    Serialize object to file-like object.
131
    
132
    Args:
133
        obj: Any Python object to serialize
134
        fp: File-like object with write() method that accepts strings (SupportsWrite[str])
135
        ensure_ascii (bool): Limit output to ASCII and escape extended characters (default: True)
136
        encode_html_chars (bool): Encode unsafe HTML characters as Unicode escapes (default: False)
137
        escape_forward_slashes (bool): Control forward slash escaping (default: True)
138
        sort_keys (bool): Sort dictionary keys in output (default: False)
139
        indent (int): Pretty print indentation, 0 = disabled (default: 0)
140
        allow_nan (bool): Allow NaN/Infinity values (default: True)
141
        reject_bytes (bool): Raise TypeError on bytes objects (default: False)
142
        default (callable | None): Function to serialize arbitrary types (default: None)
143
        separators (tuple[str, str] | None): (item_separator, key_separator) tuple (default: None)
144
    
145
    Returns:
146
        None
147
    """
148
```
149

150
### JSON Decoding Functions
151

152
Parses JSON strings and files back into Python objects.
153

154
```python { .api }
155
def decode(s):
156
    """
157
    Parse JSON string to Python object.
158
    
159
    Args:
160
        s (str | bytes | bytearray): JSON string to parse
161
    
162
    Returns:
163
        Any: Python object (dict, list, str, int, float, bool, None)
164
    
165
    Raises:
166
        JSONDecodeError: If JSON string is invalid
167
    """
168

169
def loads(s):
170
    """
171
    Alias for decode(). Parse JSON string to Python object.
172
    
173
    Args:
174
        s (str | bytes | bytearray): JSON string to parse
175
    
176
    Returns:
177
        Any: Python object (dict, list, str, int, float, bool, None)
178
    
179
    Raises:
180
        JSONDecodeError: If JSON string is invalid
181
    """
182

183
def load(fp):
184
    """
185
    Parse JSON from file-like object.
186
    
187
    Args:
188
        fp: File-like object with read() method that returns strings, bytes, or bytearrays (SupportsRead[str | bytes | bytearray])
189
    
190
    Returns:
191
        Any: Python object (dict, list, str, int, float, bool, None)
192
    
193
    Raises:
194
        JSONDecodeError: If JSON content is invalid
195
    """
196
```
197

198
### Error Handling
199

200
Exception raised when JSON parsing fails.
201

202
```python { .api }
203
class JSONDecodeError(ValueError):
204
    """
205
    Exception raised when JSON decoding fails.
206
    
207
    Inherits from ValueError for compatibility with standard json module.
208
    Raised by decode(), loads(), and load() functions on invalid JSON.
209
    """
210
```
211

212
### Module Information
213

214
Version information for the ujson package.
215

216
```python { .api }
217
__version__: str
218
"""Version string of the ujson package (e.g., '5.11.0')"""
219
```
220

221
## Performance Features
222

223
UltraJSON provides significant performance improvements over Python's standard json module:
224

225
- **Ultra-fast C implementation**: Written in pure C for maximum speed
226
- **Drop-in compatibility**: Direct replacement for standard json module functions
227
- **Memory efficient**: Optimized memory usage for large data structures
228
- **Wide type support**: Handles all standard Python types plus decimal.Decimal
229

230
## Encoding Options Usage
231

232
### HTML Safety
233
```python
234
# Encode unsafe HTML characters for safe embedding
235
html_safe = ujson.dumps("<script>alert('xss')</script>", encode_html_chars=True)
236
# Result: '"\\u003cscript\\u003ealert(\\u0027xss\\u0027)\\u003c\\/script\\u003e"'
237
```
238

239
### ASCII Control
240
```python
241
# Force ASCII-only output (default behavior)
242
ascii_json = ujson.dumps("café", ensure_ascii=True)
243
# Result: '"caf\\u00e9"'
244

245
# Allow UTF-8 characters (smaller output)
246
utf8_json = ujson.dumps("café", ensure_ascii=False)
247
# Result: '"café"'
248
```
249

250
### Pretty Printing
251
```python
252
data = {"users": [{"name": "Alice", "age": 25}, {"name": "Bob", "age": 30}]}
253
pretty = ujson.dumps(data, indent=2)
254
# Results in formatted JSON with 2-space indentation
255
```
256

257
### Custom Serialization
258
```python
259
import datetime
260

261
def date_handler(obj):
262
    if isinstance(obj, datetime.datetime):
263
        return obj.isoformat()
264
    raise TypeError(f"Object {obj} is not JSON serializable")
265

266
data = {"timestamp": datetime.datetime.now()}
267
json_str = ujson.dumps(data, default=date_handler)
268
```
269

270
## Error Handling Patterns
271

272
```python
273
import ujson
274

275
# Handle decoding errors
276
try:
277
    data = ujson.loads('{"invalid": json}')
278
except ujson.JSONDecodeError as e:
279
    print(f"JSON decode error: {e}")
280

281
# Handle encoding errors with custom types
282
try:
283
    result = ujson.dumps({"obj": object()})
284
except TypeError as e:
285
    print(f"Cannot serialize object: {e}")
286
```