JSON

The json module provides fast JSON serialization and deserialization using orjson when available, with automatic fallback to the standard library json module.

The JSON backend is selected once at import time, so there is no per-call overhead.

Installation

orjson is included in the standard extra:

pip install grelmicro[standard]

Without the extra, the module falls back to stdlib json transparently.

Usage

from grelmicro.json import json_dumps_bytes, json_loads

# Serialize Python objects to JSON bytes
data = json_dumps_bytes({"id": 1, "name": "Alice"})
print(data)
# b'{"id":1,"name":"Alice"}'

# Deserialize JSON bytes back to Python objects
obj = json_loads(data)
print(obj)
# {"id": 1, "name": "Alice"}

Cache Integration

For caching, use the built-in serializer classes instead of the low-level functions. See the cache serialization docs for JsonSerializer, PydanticSerializer, and PickleSerializer.

Datetime Handling

datetime objects are automatically serialized to ISO 8601 strings. Note that deserialization returns a string, not a datetime object:

from datetime import UTC, datetime

from grelmicro.json import json_dumps_bytes

# datetime objects are automatically serialized to ISO 8601
event = {
    "type": "login",
    "timestamp": datetime(2025, 6, 15, 10, 30, tzinfo=UTC),
}
data = json_dumps_bytes(event)
print(data)

Performance

orjson is about 7 times faster than stdlib json for serialization. The module chooses the implementation at import time, so there is no per-call branching.

Method	Speed
orjson (with grelmicro[standard])	~0.2 us/call
stdlib json (fallback)	~1.5 us/call

Use has_orjson() to check which backend is active at runtime:

from grelmicro.json import has_orjson

if has_orjson():
    print("Using orjson")
else:
    print("Using stdlib json")

API Reference

JSON serialization utilities.

Fast JSON encoding and decoding using orjson when available, with automatic fallback to the standard library json module.

orjson is roughly 7x faster than stdlib json and is included in the grelmicro[standard] extra.

Example::

from grelmicro.cache import TTLCache, JsonSerializer

cache = TTLCache(ttl=300, serializer=JsonSerializer())

JSONDecodable module-attribute

JSONDecodable: TypeAlias = (
    dict[str, Any]
    | list[Any]
    | str
    | int
    | float
    | bool
    | None
)

Types returned by json_loads.

JSONEncodable module-attribute

JSONEncodable: TypeAlias = (
    str
    | int
    | float
    | bool
    | datetime
    | None
    | Mapping[str, "JSONEncodable"]
    | list["JSONEncodable"]
    | tuple["JSONEncodable", ...]
)

Recursive JSON-encodable value. datetime is serialized as ISO 8601 string.

has_orjson

has_orjson() -> bool

Check if orjson is available.

json_default

json_default(obj: object) -> str

Handle non-serializable types for stdlib json.

Converts datetime instances to ISO 8601 strings. Raises TypeError for all other non-serializable types.

json_dumps_bytes

json_dumps_bytes(obj: JSONEncodable) -> bytes

Serialize object to JSON bytes using stdlib json.

json_dumps_str

json_dumps_str(obj: JSONEncodable) -> str

Serialize object to JSON string using stdlib json.

json_loads

json_loads(data: bytes | str) -> JSONDecodable

Deserialize JSON bytes or string using stdlib json.