0
# simplejson
1

2
A simple, fast, and extensible JSON encoder and decoder for Python. simplejson is the externally maintained development version of Python's built-in json library, offering backward compatibility with older Python versions and significant performance advantages, especially with the optional C extension.
3

4
## Package Information
5

6
- **Package Name**: simplejson
7
- **Language**: Python
8
- **Installation**: `pip install simplejson`
9
- **Version**: 3.20.1
10
- **Python Compatibility**: Python 2.5+ and Python 3.3+
11

12
## Core Imports
13

14
```python
15
import simplejson as json
16
```
17

18
Alternative import (for compatibility with stdlib json):
19

20
```python
21
import simplejson
22
```
23

24
Access to specific classes and functions:
25

26
```python  
27
from simplejson import (
28
    dump, dumps, load, loads,
29
    JSONDecoder, JSONDecodeError, JSONEncoder,
30
    OrderedDict, simple_first, RawJSON
31
)
32
```
33

34
## Basic Usage
35

36
```python
37
import simplejson as json
38

39
# Encoding basic Python objects
40
data = {"name": "Alice", "age": 30, "scores": [85, 92, 78]}
41
json_string = json.dumps(data)
42
print(json_string)  # {"name": "Alice", "age": 30, "scores": [85, 92, 78]}
43

44
# Decoding JSON
45
original_data = json.loads(json_string)
46
print(original_data)  # {'name': 'Alice', 'age': 30, 'scores': [85, 92, 78]}
47

48
# File operations
49
with open('data.json', 'w') as f:
50
    json.dump(data, f)
51

52
with open('data.json', 'r') as f:
53
    loaded_data = json.load(f)
54
```
55

56
## Architecture
57

58
simplejson follows the same design patterns as Python's built-in json module with additional features:
59

60
- **Core Functions**: `dump`, `dumps`, `load`, `loads` for basic JSON operations
61
- **Encoder Classes**: `JSONEncoder` for serialization with extensive customization options
62
- **Decoder Classes**: `JSONDecoder` for deserialization with parsing hooks
63
- **Error Handling**: `JSONDecodeError` for detailed error reporting
64
- **Performance**: Optional C extension (`_speedups`) for high-performance operations
65
- **Compatibility**: Pure Python fallback ensures wide platform support
66

67
## Capabilities
68

69
### Core JSON Operations
70

71
Basic JSON encoding and decoding operations for converting between Python objects and JSON strings or files.
72

73
```python { .api }
74
def dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True,
75
         allow_nan=False, cls=None, indent=None, separators=None,
76
         encoding='utf-8', default=None, use_decimal=True,
77
         namedtuple_as_object=True, tuple_as_array=True,
78
         bigint_as_string=False, sort_keys=False, item_sort_key=None,
79
         for_json=False, ignore_nan=False, int_as_string_bitcount=None,
80
         iterable_as_array=False, **kw):
81
    """
82
    Serialize obj as a JSON formatted stream to fp (a .write()-supporting file-like object).
83
    
84
    Parameters:
85
    - obj: Object to serialize
86
    - fp: File-like object with .write() method
87
    - skipkeys (bool): Skip non-basic type dict keys instead of raising TypeError
88
    - ensure_ascii (bool): Escape non-ASCII characters (default: True)
89
    - check_circular (bool): Check for circular references (default: True)
90
    - allow_nan (bool): Allow NaN, Infinity, -Infinity (default: False)
91
    - cls: Custom JSONEncoder subclass
92
    - indent: String or int for pretty-printing indentation
93
    - separators: (item_separator, key_separator) tuple
94
    - encoding (str): Character encoding for str instances (default: 'utf-8')
95
    - default: Function to serialize additional types
96
    - use_decimal (bool): Natively serialize Decimal objects (default: True)
97
    - namedtuple_as_object (bool): Encode namedtuples as JSON objects (default: True)
98
    - tuple_as_array (bool): Encode tuples as JSON arrays (default: True)
99
    - bigint_as_string (bool): Encode large ints as strings (default: False)
100
    - sort_keys (bool): Sort dictionary keys (default: False)
101
    - item_sort_key: Callable for custom key sorting
102
    - for_json (bool): Use for_json() method if available (default: False)
103
    - ignore_nan (bool): Serialize NaN as null (default: False)
104
    - int_as_string_bitcount: Bit count threshold for string encoding
105
    - iterable_as_array (bool): Encode iterables as arrays (default: False)
106
    
107
    Returns:
108
    None
109
    """
110

111
def dumps(obj, skipkeys=False, ensure_ascii=True, check_circular=True,
112
          allow_nan=False, cls=None, indent=None, separators=None,
113
          encoding='utf-8', default=None, use_decimal=True,
114
          namedtuple_as_object=True, tuple_as_array=True,
115
          bigint_as_string=False, sort_keys=False, item_sort_key=None,
116
          for_json=False, ignore_nan=False, int_as_string_bitcount=None,
117
          iterable_as_array=False, **kw):
118
    """
119
    Serialize obj to a JSON formatted string.
120
    
121
    Parameters: Same as dump()
122
    
123
    Returns:
124
    str: JSON formatted string
125
    """
126

127
def load(fp, encoding=None, cls=None, object_hook=None, parse_float=None,
128
        parse_int=None, parse_constant=None, object_pairs_hook=None,
129
        use_decimal=False, allow_nan=False, **kw):
130
    """
131
    Deserialize fp (a .read()-supporting file-like object) to a Python object.
132
    
133
    Parameters:
134
    - fp: File-like object with .read() method containing JSON document
135
    - encoding (str): Character encoding (default: 'utf-8')
136
    - cls: Custom JSONDecoder subclass
137
    - object_hook: Function called with result of every JSON object decoded
138
    - parse_float: Function to parse JSON floats
139
    - parse_int: Function to parse JSON integers
140
    - parse_constant: Function to parse -Infinity, Infinity, NaN
141
    - object_pairs_hook: Function called with ordered list of pairs
142
    - use_decimal (bool): Use Decimal for parsing floats (default: False)
143
    - allow_nan (bool): Allow NaN, Infinity, -Infinity (default: False)
144
    
145
    Returns:
146
    Python object
147
    """
148

149
def loads(s, encoding=None, cls=None, object_hook=None, parse_float=None,
150
        parse_int=None, parse_constant=None, object_pairs_hook=None,
151
        use_decimal=False, allow_nan=False, **kw):
152
    """
153
    Deserialize s (str or bytes containing JSON document) to a Python object.
154
    
155
    Parameters: Same as load()
156
    
157
    Returns:
158
    Python object
159
    """
160
```
161

162
### Encoder Classes
163

164
Advanced JSON encoding with extensive customization options for specialized serialization requirements.
165

166
```python { .api }
167
class JSONEncoder:
168
    """
169
    Extensible JSON encoder for Python data structures.
170
    """
171
    
172
    def __init__(self, skipkeys=False, ensure_ascii=True,
173
                 check_circular=True, allow_nan=False, sort_keys=False,
174
                 indent=None, separators=None, encoding='utf-8', default=None,
175
                 use_decimal=True, namedtuple_as_object=True,
176
                 tuple_as_array=True, bigint_as_string=False,
177
                 item_sort_key=None, for_json=False, ignore_nan=False,
178
                 int_as_string_bitcount=None, iterable_as_array=False):
179
        """
180
        Initialize JSONEncoder with configuration options.
181
        
182
        Parameters: Same as dump() function
183
        """
184
    
185
    def default(self, o):
186
        """
187
        Implement this method to serialize additional types.
188
        Should return a serializable object or raise TypeError.
189
        
190
        Parameters:
191
        - o: Object to serialize
192
        
193
        Returns:
194
        Serializable object
195
        
196
        Raises:
197
        TypeError: If object cannot be serialized
198
        """
199
    
200
    def encode(self, o):
201
        """
202
        Return JSON string representation of Python object.
203
        
204
        Parameters:
205
        - o: Object to encode
206
        
207
        Returns:
208
        str: JSON representation
209
        """
210
    
211
    def iterencode(self, o):
212
        """
213
        Encode object and yield each string representation as available.
214
        
215
        Parameters:
216
        - o: Object to encode
217
        
218
        Yields:
219
        str: JSON string chunks
220
        """
221
222
```
223

224
### Decoder Classes
225

226
Advanced JSON decoding with parsing hooks and customization options for specialized deserialization requirements.
227

228
```python { .api }
229
class JSONDecoder:
230
    """
231
    Simple JSON decoder with customizable parsing behavior.
232
    """
233
    
234
    def __init__(self, encoding=None, object_hook=None, parse_float=None,
235
            parse_int=None, parse_constant=None, strict=True,
236
            object_pairs_hook=None, allow_nan=False):
237
        """
238
        Initialize JSONDecoder with parsing options.
239
        
240
        Parameters:
241
        - encoding (str): Character encoding for bytes objects (default: 'utf-8')
242
        - object_hook: Function called with every decoded JSON object
243
        - parse_float: Function to parse JSON floats (default: float)
244
        - parse_int: Function to parse JSON integers (default: int)
245
        - parse_constant: Function to parse -Infinity, Infinity, NaN
246
        - strict (bool): Whether to allow control characters in strings (default: True)
247
        - object_pairs_hook: Function called with ordered list of object pairs
248
        - allow_nan (bool): Allow parsing of NaN, Infinity, -Infinity (default: False)
249
        """
250
    
251
    def decode(self, s):
252
        """
253
        Return Python representation of JSON string.
254
        
255
        Parameters:
256
        - s (str): JSON string to decode
257
        
258
        Returns:
259
        Python object
260
        
261
        Raises:
262
        JSONDecodeError: If JSON is invalid
263
        """
264
    
265
    def raw_decode(self, s, idx=0):
266
        """
267
        Decode JSON document from string starting at idx.
268
        
269
        Parameters:
270
        - s (str): JSON string
271
        - idx (int): Starting index (default: 0)
272
        
273
        Returns:
274
        tuple: (decoded_object, end_index)
275
        
276
        Raises:
277
        JSONDecodeError: If JSON is invalid
278
        """
279
```
280

281
### Error Handling
282

283
Detailed error reporting for JSON parsing failures with precise location information.
284

285
```python { .api }
286
class JSONDecodeError(ValueError):
287
    """
288
    Subclass of ValueError for JSON decode errors with detailed location information.
289
    """
290
    
291
    def __init__(self, msg, doc, pos, end=None):
292
        """
293
        Initialize JSONDecodeError with error details.
294
        
295
        Parameters:
296
        - msg (str): Error message
297
        - doc (str): JSON document being parsed
298
        - pos (int): Character position where error occurred
299
        - end (int): End position of error (optional)
300
        """
301
    
302
    # Attributes available on instances:
303
    # msg: str - The unformatted error message
304
    # doc: str - The JSON document being parsed
305
    # pos: int - The start index where parsing failed
306
    # end: int - The end index where parsing failed (may be None)
307
    # lineno: int - The line number corresponding to pos
308
    # colno: int - The column number corresponding to pos
309
    # endlineno: int - The line number corresponding to end (may be None)
310
    # endcolno: int - The column number corresponding to end (may be None)
311
```
312

313
### Utility Classes and Functions
314

315
Additional utilities for specialized JSON handling scenarios.
316

317
```python { .api }
318
class RawJSON:
319
    """
320
    Wrapper for pre-encoded JSON strings to embed directly in output.
321
    """
322
    
323
    def __init__(self, encoded_json):
324
        """
325
        Initialize with pre-encoded JSON string.
326
        
327
        Parameters:
328
        - encoded_json (str): Pre-encoded JSON string
329
        """
330
    
331
    # Attributes:
332
    # encoded_json: str - The pre-encoded JSON string
333

334
def simple_first(kv):
335
    """
336
    Helper function to pass to item_sort_key to sort simple elements to the top, then container elements.
337
    
338
    Parameters:
339
    - kv: (key, value) tuple from dictionary items
340
    
341
    Returns:
342
    tuple: Sort key tuple (isinstance(value, (list, dict, tuple)), key)
343
    """
344

345
# Type alias for OrderedDict (collections.OrderedDict or fallback implementation)
346
OrderedDict = collections.OrderedDict  # or fallback implementation for older Python versions
347
```
348

349
### Command Line Tool
350

351
JSON validation and pretty-printing functionality accessible via command line.
352

353
```bash { .api }
354
# Usage: python -m simplejson.tool [infile [outfile]]
355
# Validates and pretty-prints JSON from stdin/file to stdout/file
356
# 
357
# Examples:
358
# echo '{"json":"obj"}' | python -m simplejson.tool
359
# python -m simplejson.tool input.json
360
# python -m simplejson.tool input.json output.json
361
#
362
# Features:
363
# - Validates JSON syntax and reports errors with line/column information
364
# - Pretty-prints with 4-space indentation
365
# - Uses OrderedDict to preserve object key order
366
# - Uses Decimal for high-precision numbers
367
# - Sorts object keys alphabetically
368
```
369

370
## Advanced Usage Examples
371

372
### Custom Serialization
373

374
```python
375
import simplejson as json
376
from decimal import Decimal
377
from datetime import datetime
378

379
def custom_serializer(obj):
380
    if isinstance(obj, datetime):
381
        return obj.isoformat()
382
    elif isinstance(obj, Decimal):
383
        return float(obj)
384
    raise TypeError(f"Object of type {type(obj)} is not JSON serializable")
385

386
data = {
387
    "timestamp": datetime.now(),
388
    "price": Decimal("19.99"),
389
    "items": ["apple", "banana"]
390
}
391

392
json_string = json.dumps(data, default=custom_serializer, indent=2)
393
```
394

395
### Custom Deserialization
396

397
```python
398
import simplejson as json
399
from decimal import Decimal
400

401
def parse_decimal(s):
402
    return Decimal(s)
403

404
def object_hook(dct):
405
    if 'price' in dct:
406
        dct['price'] = Decimal(str(dct['price']))
407
    return dct
408

409
json_string = '{"price": "19.99", "quantity": 5}'
410
data = json.loads(json_string, parse_float=parse_decimal, object_hook=object_hook)
411
```
412

413
### High-Precision Numbers
414

415
```python
416
import simplejson as json
417

418
# Avoid JavaScript precision loss for large integers
419
large_number = 9007199254740993  # Exceeds JavaScript safe integer limit
420
json_string = json.dumps({"id": large_number}, bigint_as_string=True)
421
# Result: {"id": "9007199254740993"}
422

423
# Use Decimal for financial precision
424
from decimal import Decimal
425
price = Decimal("123.456789")
426
json_string = json.dumps({"price": price}, use_decimal=True)
427
```
428

429
### Streaming Large Objects
430

431
```python
432
import simplejson as json
433

434
large_data = {"items": list(range(1000000))}
435

436
# Stream encoding to avoid loading entire JSON string in memory
437
with open('large_file.json', 'w') as f:
438
    encoder = json.JSONEncoder()
439
    for chunk in encoder.iterencode(large_data):
440
        f.write(chunk)
441
```
442

443
## Error Handling Examples
444

445
```python
446
import simplejson as json
447

448
try:
449
    invalid_json = '{"name": "Alice", "age":}'
450
    data = json.loads(invalid_json)
451
except json.JSONDecodeError as e:
452
    print(f"JSON decode error: {e.msg}")
453
    print(f"Error at line {e.lineno}, column {e.colno}")
454
    print(f"Near: {e.doc[e.pos-10:e.pos+10]}")
455
```
456

457
## Performance Considerations
458

459
- simplejson automatically uses C extensions when available for maximum performance
460
- For high-frequency encoding/decoding, consider reusing JSONEncoder/JSONDecoder instances
461
- Use streaming operations (iterencode) for large objects to reduce memory usage
462
- Enable specific optimizations: `use_decimal=False`, `check_circular=False`, `sort_keys=False` when not needed