The lodum.json module provides JSON serialization and deserialization for lodum-enabled classes with support for both in-memory and streaming operations.
Functions
dump
def dump(
obj: Any,
target: Optional[Union[IO[str], Path]] = None,
**kwargs
) -> Optional[str]
target
Optional[Union[IO[str], Path]]
Optional file-like object or Path to write to. If provided, uses O(1) streaming mode.
Additional arguments for json.dump(s) (e.g., indent). Note: If target is provided, O(1) streaming is used and some formatting kwargs might be ignored in the current implementation.
target is None, otherwise None.
Example:
import lodum
from lodum import json
@lodum
class Person:
name: str
age: int
person = Person(name="Alice", age=30)
# Serialize to string
json_str = json.dump(person, indent=2)
# Serialize to file
json.dump(person, Path("person.json"))
dumps
def dumps(obj: Any, **kwargs) -> str
dump(obj).
Additional arguments for json.dumps.
load
def load(
cls: Type[T],
source: Union[str, IO[Any], Path],
max_size: int = DEFAULT_MAX_SIZE
) -> T
The class to instantiate.
source
Union[str, IO[Any], Path]
required
JSON string, file-like object, or Path.
max_size
int
default:"DEFAULT_MAX_SIZE"
Maximum allowed size for string input.
cls.
Raises: DeserializationError if the input is invalid or exceeds max_size.
Example:
import lodum
from lodum import json
@lodum
class Person:
name: str
age: int
# Load from string
json_str = '{"name": "Alice", "age": 30}'
person = json.load(Person, json_str)
# Load from file
person = json.load(Person, Path("person.json"))
loads
def loads(cls: Type[T], json_string: str, **kwargs) -> T
load(cls, source).
The class to instantiate.
Additional arguments (e.g., max_size).
cls.
stream
def stream(cls: Type[T], source: Union[IO[bytes], Path]) -> Iterator[T]
cls. Intended for sources containing a top-level array of objects.
The class to instantiate for each item.
source
Union[IO[bytes], Path]
required
A binary stream, file-like object, or Path to a JSON array.
cls.
Raises: RuntimeError if ijson is not installed. Install with: pip install lodum[ijson]
Example:
import lodum
from lodum import json
@lodum
class Person:
name: str
age: int
# Stream from file containing JSON array
for person in json.stream(Person, Path("people.json")):
print(person.name, person.age)
load_stream
def load_stream(cls: Type[T], stream_io: IO[bytes]) -> Iterator[T]
stream(cls, source).
The class to instantiate for each item.
cls.
schema
def schema(cls: Type[Any]) -> Dict[str, Any]
import lodum
from lodum import json
@lodum
class Person:
name: str
age: int
schema_dict = json.schema(Person)
print(schema_dict)