or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/pypi-simplejson

Simple, fast, extensible JSON encoder/decoder for Python

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/simplejson@3.20.x

To install, run

npx @tessl/cli install tessl/pypi-simplejson@3.20.0

index.mddocs/

simplejson

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.

Package Information

  • Package Name: simplejson
  • Language: Python
  • Installation: pip install simplejson
  • Version: 3.20.1
  • Python Compatibility: Python 2.5+ and Python 3.3+

Core Imports

import simplejson as json

Alternative import (for compatibility with stdlib json):

import simplejson

Access to specific classes and functions:

from simplejson import (
    dump, dumps, load, loads,
    JSONDecoder, JSONDecodeError, JSONEncoder,
    OrderedDict, simple_first, RawJSON
)

Basic Usage

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)

Architecture

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

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

Capabilities

Core JSON Operations

Basic 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
    """

Encoder Classes

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
        """

Decoder Classes

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
        """

Error Handling

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)

Utility Classes and Functions

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 versions

Command Line Tool

JSON 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 alphabetically

Advanced Usage Examples

Custom Serialization

import 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)

Custom Deserialization

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)

High-Precision Numbers

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)

Streaming Large Objects

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)

Error Handling Examples

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]}")

Performance Considerations

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