or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/pypi-orjson

Fast, correct Python JSON library supporting dataclasses, datetimes, and numpy

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/orjson@3.11.x

To install, run

npx @tessl/cli install tessl/pypi-orjson@3.11.0

index.mddocs/

orjson

orjson is a fast, correct JSON library for Python. It benchmarks as the fastest Python library for JSON and is more correct than the standard json library or other third-party libraries. It serializes dataclass, datetime, numpy, and UUID instances natively with significant performance benefits over standard library alternatives.

Package Information

  • Package Name: orjson
  • Package Type: pypi
  • Language: Python (with Rust backend)
  • Installation: pip install orjson
  • Version: 3.11.3
  • Python Support: CPython 3.9, 3.10, 3.11, 3.12, 3.13, 3.14

Core Imports

import orjson

Or import specific components:

from orjson import dumps, loads, Fragment, JSONDecodeError, JSONEncodeError
from orjson import OPT_INDENT_2, OPT_SORT_KEYS, OPT_SERIALIZE_NUMPY

Basic Usage

import orjson
import datetime
import numpy

# Basic serialization and deserialization
data = {"type": "job", "id": 123, "active": True}
json_bytes = orjson.dumps(data)
parsed_data = orjson.loads(json_bytes)

# Advanced usage with options and native type support
complex_data = {
    "created_at": datetime.datetime(1970, 1, 1),
    "status": "🆗",
    "payload": numpy.array([[1, 2], [3, 4]]),
}

# Serialize with options
json_bytes = orjson.dumps(
    complex_data, 
    option=orjson.OPT_NAIVE_UTC | orjson.OPT_SERIALIZE_NUMPY | orjson.OPT_INDENT_2
)

# Parse back to Python objects
result = orjson.loads(json_bytes)

Capabilities

JSON Serialization

Converts Python objects to JSON bytes with high performance and native support for many Python types.

def dumps(
    __obj: Any,
    default: Callable[[Any], Any] | None = None,
    option: int | None = None,
) -> bytes:
    """
    Serialize Python objects to JSON bytes.
    
    Args:
        __obj: Object to serialize (positional only)
        default: Optional callable to handle unsupported types
        option: Optional serialization options (bitwise OR of OPT_* constants)
    
    Returns:
        JSON as UTF-8 encoded bytes
        
    Raises:
        JSONEncodeError: On serialization failures
    """

Native type support: str, dict, list, tuple, int, float, bool, None, dataclasses.dataclass, typing.TypedDict, datetime.datetime, datetime.date, datetime.time, uuid.UUID, numpy.ndarray (with OPT_SERIALIZE_NUMPY), enum.Enum, and subclasses of str, int, dict, list, dataclass.

Usage example with default handler:

import orjson
import decimal

def default_handler(obj):
    if isinstance(obj, decimal.Decimal):
        return str(obj)
    raise TypeError

data = {"value": decimal.Decimal("123.456")}
result = orjson.dumps(data, default=default_handler)

JSON Deserialization

Parses JSON input to Python objects with strict UTF-8 and RFC 8259 compliance.

def loads(__obj: bytes | bytearray | memoryview | str) -> Any:
    """
    Deserialize JSON to Python objects.
    
    Args:
        __obj: JSON input to parse (positional only)
    
    Returns:
        Parsed Python object (dict, list, int, float, str, bool, None)
        
    Raises:
        JSONDecodeError: On parsing failures
    """

Input types: Accepts bytes, bytearray, memoryview, and str. For best performance, pass binary data directly rather than converting to string first.

Output types: Always returns standard Python types: dict, list, int, float, str, bool, None.

Pre-serialized JSON Fragments

Include already-serialized JSON content without re-parsing for performance optimization.

class Fragment(tuple):
    """
    Container for pre-serialized JSON content.
    
    Args:
        contents: Pre-serialized JSON as bytes or str (positional only)
    """
    
    contents: bytes | str

Usage example:

import orjson

# Include cached JSON without parsing
cached_json = '{"nested": {"data": [1, 2, 3]}}'
data = {
    "key": "value",
    "cached": orjson.Fragment(cached_json)
}

result = orjson.dumps(data)
# Output: b'{"key":"value","cached":{"nested":{"data":[1,2,3]}}}'

Error Handling

Exception classes for JSON processing errors.

class JSONDecodeError(json.JSONDecodeError):
    """
    Exception raised when JSON parsing fails.
    Inherits from json.JSONDecodeError for compatibility with standard library.
    """

class JSONEncodeError(TypeError):
    """
    Exception raised when JSON serialization fails.
    Inherits from TypeError for compatibility with standard library.
    """

Serialization Options

Options are integer constants that can be combined with bitwise OR (|) to control serialization behavior.

Output Formatting Options

OPT_APPEND_NEWLINE: int  # Append \n to output
OPT_INDENT_2: int        # Pretty-print with 2-space indentation
OPT_SORT_KEYS: int       # Sort dictionary keys in output

Usage example:

import orjson

data = {"b": 1, "c": 2, "a": 3}

# Pretty-printed, sorted output with newline
result = orjson.dumps(
    data, 
    option=orjson.OPT_INDENT_2 | orjson.OPT_SORT_KEYS | orjson.OPT_APPEND_NEWLINE
)

Datetime Serialization Options

OPT_NAIVE_UTC: int           # Treat naive datetimes as UTC
OPT_OMIT_MICROSECONDS: int   # Don't serialize microseconds
OPT_UTC_Z: int               # Use 'Z' suffix for UTC instead of '+00:00'

Usage example:

import orjson
import datetime

dt = datetime.datetime(2023, 1, 1, 12, 0, 0, 123456)

# Standard format
orjson.dumps(dt)  # b'"2023-01-01T12:00:00.123456"'

# UTC with Z suffix, no microseconds
orjson.dumps(dt, option=orjson.OPT_NAIVE_UTC | orjson.OPT_UTC_Z | orjson.OPT_OMIT_MICROSECONDS)
# b'"2023-01-01T12:00:00Z"'

Key and Type Handling Options

OPT_NON_STR_KEYS: int      # Allow non-string dictionary keys
OPT_STRICT_INTEGER: int    # Enforce 53-bit integer limit (JavaScript compatibility)

Usage example:

import orjson
import datetime
import uuid

# Dictionary with various key types
data = {
    "string_key": "value1",
    42: "value2", 
    datetime.date(2023, 1, 1): "value3",
    uuid.UUID("12345678-1234-5678-1234-123456789abc"): "value4"
}

result = orjson.dumps(data, option=orjson.OPT_NON_STR_KEYS)

Passthrough Options

Control whether certain types use native serialization or are passed to the default handler.

OPT_PASSTHROUGH_DATACLASS: int  # Pass dataclasses to default function
OPT_PASSTHROUGH_DATETIME: int   # Pass datetime objects to default function  
OPT_PASSTHROUGH_SUBCLASS: int   # Pass subclasses to default function

Usage example:

import orjson
import dataclasses

@dataclasses.dataclass
class User:
    id: str
    name: str
    password: str

def custom_serializer(obj):
    if isinstance(obj, User):
        return {"id": obj.id, "name": obj.name}  # Exclude password
    raise TypeError

user = User("123", "Alice", "secret")

# Custom serialization excluding password
result = orjson.dumps(
    user, 
    option=orjson.OPT_PASSTHROUGH_DATACLASS,
    default=custom_serializer
)

Special Type Options

OPT_SERIALIZE_NUMPY: int     # Enable numpy array/scalar serialization
OPT_SERIALIZE_DATACLASS: int # Deprecated (no effect in v3)
OPT_SERIALIZE_UUID: int      # Deprecated (no effect in v3)

Numpy serialization example:

import orjson
import numpy as np

# Create numpy array
arr = np.array([[1, 2, 3], [4, 5, 6]], dtype=np.int32)

# Serialize with numpy support
result = orjson.dumps(arr, option=orjson.OPT_SERIALIZE_NUMPY)
# Output: b'[[1,2,3],[4,5,6]]'

Performance Characteristics

  • Speed: ~10x faster serialization, ~2x faster deserialization vs standard library
  • Memory: Efficient memory usage with string key caching (2048 entries, max 64 bytes per key)
  • Threading: GIL held during operations (no thread parallelism within single call)
  • Optimization: Uses AVX-512 when available on supported hardware
  • Compliance: Strict UTF-8 and RFC 8259 JSON compliance

Error Conditions

JSONEncodeError Scenarios

  • Unsupported type without default handler
  • Invalid UTF-8 in string input
  • Integer exceeding 64-bit range (or 53-bit with OPT_STRICT_INTEGER)
  • Non-string dict keys without OPT_NON_STR_KEYS
  • Circular references in objects
  • Recursion depth exceeded (254 levels in default function)
  • Unsupported timezone info in datetime objects

JSONDecodeError Scenarios

  • Invalid JSON syntax
  • Invalid UTF-8 encoding in input
  • NaN, Infinity, -Infinity values (not valid JSON)
  • Recursion depth exceeded (1024 levels for nested structures)
  • Memory allocation failures for large documents

Migration from Standard Library

Key differences when migrating from Python's built-in json module:

  1. Return type: orjson.dumps() returns bytes, json.dumps() returns str
  2. Options: Use option=orjson.OPT_SORT_KEYS instead of sort_keys=True
  3. Indentation: Use option=orjson.OPT_INDENT_2 instead of indent=2
  4. Non-string keys: Requires option=orjson.OPT_NON_STR_KEYS
  5. Native types: Many types serialize natively (no default needed)
  6. Stricter: orjson rejects invalid UTF-8 that json accepts

Module Metadata

__version__: str  # Library version (e.g., "3.11.3")