0
# Ultra-fast JSON (ujson)
1

2
Low-level, high-performance JSON serialization implemented in C, providing the fastest possible JSON encoding and decoding operations. This module serves as the underlying engine for srsly's main JSON API functions.
3

4
## Capabilities
5

6
### JSON String Serialization
7

8
Convert Python objects to JSON strings with high performance and fine-grained control over output formatting.
9

10
```python { .api }
11
def dumps(obj, indent=0, ensure_ascii=True, double_precision=9, encode_html_chars=False, escape_forward_slashes=True):
12
    """
13
    Serialize Python object to JSON string with high performance.
14

15
    Parameters:
16
    - obj: Python object to serialize
17
    - indent (int): Number of spaces for indentation (0 for compact)
18
    - ensure_ascii (bool): Escape non-ASCII characters as Unicode escapes
19
    - double_precision (int): Maximum number of decimal places for floats
20
    - encode_html_chars (bool): Encode HTML characters (< > &) as Unicode escapes
21
    - escape_forward_slashes (bool): Escape forward slash characters
22

23
    Returns:
24
    str: JSON string representation
25
    """
26

27
def encode(obj, indent=0, ensure_ascii=True, double_precision=9, encode_html_chars=False, escape_forward_slashes=True):
28
    """
29
    Alias for dumps() - serialize Python object to JSON string.
30

31
    Parameters:
32
    - obj: Python object to serialize
33
    - indent (int): Number of spaces for indentation (0 for compact)
34
    - ensure_ascii (bool): Escape non-ASCII characters as Unicode escapes
35
    - double_precision (int): Maximum number of decimal places for floats
36
    - encode_html_chars (bool): Encode HTML characters (< > &) as Unicode escapes
37
    - escape_forward_slashes (bool): Escape forward slash characters
38

39
    Returns:
40
    str: JSON string representation
41
    """
42
```
43

44
### JSON String Deserialization
45

46
Parse JSON strings into Python objects with high performance and precision control.
47

48
```python { .api }
49
def loads(data, precise_float=False):
50
    """
51
    Deserialize JSON string to Python object with high performance.
52

53
    Parameters:
54
    - data (str | bytes): JSON string or bytes to deserialize
55
    - precise_float (bool): Use high-precision float decoder for exact decimal representation
56

57
    Returns:
58
    Any: Deserialized Python object
59
    """
60

61
def decode(data, precise_float=False):
62
    """
63
    Alias for loads() - deserialize JSON string to Python object.
64

65
    Parameters:
66
    - data (str | bytes): JSON string or bytes to deserialize
67
    - precise_float (bool): Use high-precision float decoder for exact decimal representation
68

69
    Returns:
70
    Any: Deserialized Python object
71
    """
72
```
73

74
### JSON File Operations
75

76
Direct file I/O operations for JSON data with optimal performance.
77

78
```python { .api }
79
def dump(obj, fp, indent=0, ensure_ascii=True, double_precision=9, encode_html_chars=False, escape_forward_slashes=True):
80
    """
81
    Serialize Python object directly to file with high performance.
82

83
    Parameters:
84
    - obj: Python object to serialize
85
    - fp: File-like object to write to
86
    - indent (int): Number of spaces for indentation (0 for compact)
87
    - ensure_ascii (bool): Escape non-ASCII characters as Unicode escapes
88
    - double_precision (int): Maximum number of decimal places for floats
89
    - encode_html_chars (bool): Encode HTML characters (< > &) as Unicode escapes
90
    - escape_forward_slashes (bool): Escape forward slash characters
91

92
    Returns:
93
    None
94
    """
95

96
def load(fp, precise_float=False):
97
    """
98
    Deserialize JSON directly from file with high performance.
99

100
    Parameters:
101
    - fp: File-like object to read from
102
    - precise_float (bool): Use high-precision float decoder for exact decimal representation
103

104
    Returns:
105
    Any: Deserialized Python object
106
    """
107
```
108

109
## Usage Examples
110

111
### High-Performance JSON Operations
112

113
```python
114
import srsly.ujson as ujson
115

116
# Ultra-fast serialization
117
data = {
118
    "name": "Performance Test",
119
    "scores": [95.7, 87.3, 92.8],
120
    "metadata": {"version": 1.0, "optimized": True}
121
}
122

123
# Compact JSON with maximum performance
124
json_compact = ujson.dumps(data)
125
print(json_compact)
126

127
# Formatted JSON with custom precision
128
json_formatted = ujson.dumps(data, indent=2, double_precision=2)
129
print(json_formatted)
130
```
131

132
### Precision Control for Financial Data
133

134
```python
135
import srsly.ujson as ujson
136

137
# Financial data requiring high precision
138
financial_data = {
139
    "account": "12345",
140
    "balance": 12345.67890123456,  # High precision decimal
141
    "transactions": [
142
        {"amount": 100.12345, "date": "2023-01-01"},
143
        {"amount": -50.98765, "date": "2023-01-02"}
144
    ]
145
}
146

147
# Use precise_float for exact decimal handling
148
json_str = ujson.dumps(financial_data, double_precision=15)
149
restored_data = ujson.loads(json_str, precise_float=True)
150

151
print(f"Original balance: {financial_data['balance']}")
152
print(f"Restored balance: {restored_data['balance']}")
153
```
154

155
### HTML-Safe JSON Output
156

157
```python
158
import srsly.ujson as ujson
159

160
# Data containing HTML characters
161
html_data = {
162
    "content": "<div>Hello & welcome to our site!</div>",
163
    "script": "if (x < 5 && y > 10) { return true; }",
164
    "url": "https://example.com/path"
165
}
166

167
# Encode HTML characters for safe embedding
168
html_safe = ujson.dumps(html_data, encode_html_chars=True)
169
print("HTML-safe JSON:", html_safe)
170

171
# Control forward slash escaping
172
no_slash_escape = ujson.dumps(html_data, escape_forward_slashes=False)
173
print("No slash escaping:", no_slash_escape)
174
```
175

176
### Direct File I/O for Large Datasets
177

178
```python
179
import srsly.ujson as ujson
180

181
# Large dataset
182
large_dataset = {
183
    "version": "1.0",
184
    "data": [{"id": i, "value": i * 1.5, "label": f"item_{i}"} for i in range(10000)]
185
}
186

187
# Direct file writing for optimal performance
188
with open("large_dataset.json", "w") as f:
189
    ujson.dump(large_dataset, f, indent=2)
190

191
# Direct file reading
192
with open("large_dataset.json", "r") as f:
193
    loaded_dataset = ujson.load(f, precise_float=True)
194

195
print(f"Dataset version: {loaded_dataset['version']}")
196
print(f"Data points: {len(loaded_dataset['data'])}")
197
```
198

199
### Unicode and ASCII Control
200

201
```python
202
import srsly.ujson as ujson
203

204
# Data with Unicode characters
205
unicode_data = {
206
    "name": "José García",
207
    "city": "São Paulo",
208
    "greeting": "Hello 世界",
209
    "emoji": "🌟⭐✨"
210
}
211

212
# Keep Unicode characters (faster, smaller output)
213
unicode_json = ujson.dumps(unicode_data, ensure_ascii=False)
214
print("Unicode preserved:", unicode_json)
215

216
# Escape to ASCII (safer for legacy systems)
217
ascii_json = ujson.dumps(unicode_data, ensure_ascii=True)
218
print("ASCII escaped:", ascii_json)
219
```