Simple, fast, extensible JSON encoder/decoder for Python
npx @tessl/cli install tessl/pypi-simplejson@3.20.0A 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.
pip install simplejsonimport simplejson as jsonAlternative import (for compatibility with stdlib json):
import simplejsonAccess to specific classes and functions:
from simplejson import (
dump, dumps, load, loads,
JSONDecoder, JSONDecodeError, JSONEncoder,
OrderedDict, simple_first, RawJSON
)import simplejson as json
# Encoding basic Python objects
data = {"name": "Alice", "age": 30, "scores": [85, 92, 78]}
json_string = json.dumps(data)
print(json_string) # {"name": "Alice", "age": 30, "scores": [85, 92, 78]}
# Decoding JSON
original_data = json.loads(json_string)
print(original_data) # {'name': 'Alice', 'age': 30, 'scores': [85, 92, 78]}
# File operations
with open('data.json', 'w') as f:
json.dump(data, f)
with open('data.json', 'r') as f:
loaded_data = json.load(f)simplejson follows the same design patterns as Python's built-in json module with additional features:
dump, dumps, load, loads for basic JSON operationsJSONEncoder for serialization with extensive customization optionsJSONDecoder for deserialization with parsing hooksJSONDecodeError for detailed error reporting_speedups) for high-performance operationsBasic JSON encoding and decoding operations for converting between Python objects and JSON strings or files.
def dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True,
allow_nan=False, cls=None, indent=None, separators=None,
encoding='utf-8', default=None, use_decimal=True,
namedtuple_as_object=True, tuple_as_array=True,
bigint_as_string=False, sort_keys=False, item_sort_key=None,
for_json=False, ignore_nan=False, int_as_string_bitcount=None,
iterable_as_array=False, **kw):
"""
Serialize obj as a JSON formatted stream to fp (a .write()-supporting file-like object).
Parameters:
- obj: Object to serialize
- fp: File-like object with .write() method
- skipkeys (bool): Skip non-basic type dict keys instead of raising TypeError
- ensure_ascii (bool): Escape non-ASCII characters (default: True)
- check_circular (bool): Check for circular references (default: True)
- allow_nan (bool): Allow NaN, Infinity, -Infinity (default: False)
- cls: Custom JSONEncoder subclass
- indent: String or int for pretty-printing indentation
- separators: (item_separator, key_separator) tuple
- encoding (str): Character encoding for str instances (default: 'utf-8')
- default: Function to serialize additional types
- use_decimal (bool): Natively serialize Decimal objects (default: True)
- namedtuple_as_object (bool): Encode namedtuples as JSON objects (default: True)
- tuple_as_array (bool): Encode tuples as JSON arrays (default: True)
- bigint_as_string (bool): Encode large ints as strings (default: False)
- sort_keys (bool): Sort dictionary keys (default: False)
- item_sort_key: Callable for custom key sorting
- for_json (bool): Use for_json() method if available (default: False)
- ignore_nan (bool): Serialize NaN as null (default: False)
- int_as_string_bitcount: Bit count threshold for string encoding
- iterable_as_array (bool): Encode iterables as arrays (default: False)
Returns:
None
"""
def dumps(obj, skipkeys=False, ensure_ascii=True, check_circular=True,
allow_nan=False, cls=None, indent=None, separators=None,
encoding='utf-8', default=None, use_decimal=True,
namedtuple_as_object=True, tuple_as_array=True,
bigint_as_string=False, sort_keys=False, item_sort_key=None,
for_json=False, ignore_nan=False, int_as_string_bitcount=None,
iterable_as_array=False, **kw):
"""
Serialize obj to a JSON formatted string.
Parameters: Same as dump()
Returns:
str: JSON formatted string
"""
def load(fp, encoding=None, cls=None, object_hook=None, parse_float=None,
parse_int=None, parse_constant=None, object_pairs_hook=None,
use_decimal=False, allow_nan=False, **kw):
"""
Deserialize fp (a .read()-supporting file-like object) to a Python object.
Parameters:
- fp: File-like object with .read() method containing JSON document
- encoding (str): Character encoding (default: 'utf-8')
- cls: Custom JSONDecoder subclass
- object_hook: Function called with result of every JSON object decoded
- parse_float: Function to parse JSON floats
- parse_int: Function to parse JSON integers
- parse_constant: Function to parse -Infinity, Infinity, NaN
- object_pairs_hook: Function called with ordered list of pairs
- use_decimal (bool): Use Decimal for parsing floats (default: False)
- allow_nan (bool): Allow NaN, Infinity, -Infinity (default: False)
Returns:
Python object
"""
def loads(s, encoding=None, cls=None, object_hook=None, parse_float=None,
parse_int=None, parse_constant=None, object_pairs_hook=None,
use_decimal=False, allow_nan=False, **kw):
"""
Deserialize s (str or bytes containing JSON document) to a Python object.
Parameters: Same as load()
Returns:
Python object
"""Advanced JSON encoding with extensive customization options for specialized serialization requirements.
class JSONEncoder:
"""
Extensible JSON encoder for Python data structures.
"""
def __init__(self, skipkeys=False, ensure_ascii=True,
check_circular=True, allow_nan=False, sort_keys=False,
indent=None, separators=None, encoding='utf-8', default=None,
use_decimal=True, namedtuple_as_object=True,
tuple_as_array=True, bigint_as_string=False,
item_sort_key=None, for_json=False, ignore_nan=False,
int_as_string_bitcount=None, iterable_as_array=False):
"""
Initialize JSONEncoder with configuration options.
Parameters: Same as dump() function
"""
def default(self, o):
"""
Implement this method to serialize additional types.
Should return a serializable object or raise TypeError.
Parameters:
- o: Object to serialize
Returns:
Serializable object
Raises:
TypeError: If object cannot be serialized
"""
def encode(self, o):
"""
Return JSON string representation of Python object.
Parameters:
- o: Object to encode
Returns:
str: JSON representation
"""
def iterencode(self, o):
"""
Encode object and yield each string representation as available.
Parameters:
- o: Object to encode
Yields:
str: JSON string chunks
"""Advanced JSON decoding with parsing hooks and customization options for specialized deserialization requirements.
class JSONDecoder:
"""
Simple JSON decoder with customizable parsing behavior.
"""
def __init__(self, encoding=None, object_hook=None, parse_float=None,
parse_int=None, parse_constant=None, strict=True,
object_pairs_hook=None, allow_nan=False):
"""
Initialize JSONDecoder with parsing options.
Parameters:
- encoding (str): Character encoding for bytes objects (default: 'utf-8')
- object_hook: Function called with every decoded JSON object
- parse_float: Function to parse JSON floats (default: float)
- parse_int: Function to parse JSON integers (default: int)
- parse_constant: Function to parse -Infinity, Infinity, NaN
- strict (bool): Whether to allow control characters in strings (default: True)
- object_pairs_hook: Function called with ordered list of object pairs
- allow_nan (bool): Allow parsing of NaN, Infinity, -Infinity (default: False)
"""
def decode(self, s):
"""
Return Python representation of JSON string.
Parameters:
- s (str): JSON string to decode
Returns:
Python object
Raises:
JSONDecodeError: If JSON is invalid
"""
def raw_decode(self, s, idx=0):
"""
Decode JSON document from string starting at idx.
Parameters:
- s (str): JSON string
- idx (int): Starting index (default: 0)
Returns:
tuple: (decoded_object, end_index)
Raises:
JSONDecodeError: If JSON is invalid
"""Detailed error reporting for JSON parsing failures with precise location information.
class JSONDecodeError(ValueError):
"""
Subclass of ValueError for JSON decode errors with detailed location information.
"""
def __init__(self, msg, doc, pos, end=None):
"""
Initialize JSONDecodeError with error details.
Parameters:
- msg (str): Error message
- doc (str): JSON document being parsed
- pos (int): Character position where error occurred
- end (int): End position of error (optional)
"""
# Attributes available on instances:
# msg: str - The unformatted error message
# doc: str - The JSON document being parsed
# pos: int - The start index where parsing failed
# end: int - The end index where parsing failed (may be None)
# lineno: int - The line number corresponding to pos
# colno: int - The column number corresponding to pos
# endlineno: int - The line number corresponding to end (may be None)
# endcolno: int - The column number corresponding to end (may be None)Additional utilities for specialized JSON handling scenarios.
class RawJSON:
"""
Wrapper for pre-encoded JSON strings to embed directly in output.
"""
def __init__(self, encoded_json):
"""
Initialize with pre-encoded JSON string.
Parameters:
- encoded_json (str): Pre-encoded JSON string
"""
# Attributes:
# encoded_json: str - The pre-encoded JSON string
def simple_first(kv):
"""
Helper function to pass to item_sort_key to sort simple elements to the top, then container elements.
Parameters:
- kv: (key, value) tuple from dictionary items
Returns:
tuple: Sort key tuple (isinstance(value, (list, dict, tuple)), key)
"""
# Type alias for OrderedDict (collections.OrderedDict or fallback implementation)
OrderedDict = collections.OrderedDict # or fallback implementation for older Python versionsJSON validation and pretty-printing functionality accessible via command line.
# Usage: python -m simplejson.tool [infile [outfile]]
# Validates and pretty-prints JSON from stdin/file to stdout/file
#
# Examples:
# echo '{"json":"obj"}' | python -m simplejson.tool
# python -m simplejson.tool input.json
# python -m simplejson.tool input.json output.json
#
# Features:
# - Validates JSON syntax and reports errors with line/column information
# - Pretty-prints with 4-space indentation
# - Uses OrderedDict to preserve object key order
# - Uses Decimal for high-precision numbers
# - Sorts object keys alphabeticallyimport simplejson as json
from decimal import Decimal
from datetime import datetime
def custom_serializer(obj):
if isinstance(obj, datetime):
return obj.isoformat()
elif isinstance(obj, Decimal):
return float(obj)
raise TypeError(f"Object of type {type(obj)} is not JSON serializable")
data = {
"timestamp": datetime.now(),
"price": Decimal("19.99"),
"items": ["apple", "banana"]
}
json_string = json.dumps(data, default=custom_serializer, indent=2)import simplejson as json
from decimal import Decimal
def parse_decimal(s):
return Decimal(s)
def object_hook(dct):
if 'price' in dct:
dct['price'] = Decimal(str(dct['price']))
return dct
json_string = '{"price": "19.99", "quantity": 5}'
data = json.loads(json_string, parse_float=parse_decimal, object_hook=object_hook)import simplejson as json
# Avoid JavaScript precision loss for large integers
large_number = 9007199254740993 # Exceeds JavaScript safe integer limit
json_string = json.dumps({"id": large_number}, bigint_as_string=True)
# Result: {"id": "9007199254740993"}
# Use Decimal for financial precision
from decimal import Decimal
price = Decimal("123.456789")
json_string = json.dumps({"price": price}, use_decimal=True)import simplejson as json
large_data = {"items": list(range(1000000))}
# Stream encoding to avoid loading entire JSON string in memory
with open('large_file.json', 'w') as f:
encoder = json.JSONEncoder()
for chunk in encoder.iterencode(large_data):
f.write(chunk)import simplejson as json
try:
invalid_json = '{"name": "Alice", "age":}'
data = json.loads(invalid_json)
except json.JSONDecodeError as e:
print(f"JSON decode error: {e.msg}")
print(f"Error at line {e.lineno}, column {e.colno}")
print(f"Near: {e.doc[e.pos-10:e.pos+10]}")use_decimal=False, check_circular=False, sort_keys=False when not needed