API Reference

class JsonReader(input: Any, **kwargs: Any)

Bases: object

A streaming JSON reader that allows streaming parsing of JSON data. The current implementation uses ijson. Exceptions are raised as ijson.JsonError.

JsonReader provides methods to navigate through a JSON structure without loading the entire content into memory. This is particularly useful for processing large JSON files or streams efficiently.

__init__(input: Any, **kwargs: Any)

Creates a new JsonReader that reads from the specified input. The input is expected to be a binary file-like object, but str and bytes can be used as well.

close() → None

Closes the input and releases any resources associated with it.

peek() → str | None

Looks at the next token in the JSON stream without consuming it.

This method allows you to check what type of token is coming next without advancing the reader position.

Returns:

The type of the next token, or None if the end of the stream has been reached.

start_array() → None

Consumes the beginning of a JSON array.

Raises:

JSONError – if the next token is not the beginning of an array (‘[‘)

end_array() → None

Consumes the end of a JSON array.

Raises:

JSONError – if the next token is not the end of an array (‘]’)

start_map() → None

Consumes the beginning of a JSON object.

Raises:

JSONError – if the next token is not the beginning of an object (‘{‘)

end_map() → None

Consumes the end of a JSON object.

Raises:

JSONError – if the next token is not the end of an object (‘}’)

has_next() → bool

Checks if there are more elements in the current array or object.

This method is typically used in a while loop to iterate through all elements in an array or all properties in an object.

Returns:

True if there are more elements, or False if the end of the current array or object has been reached

Examples:

reader.start_array()
while reader.has_next():
    print(reader.next_string())
reader.end_array()

next_map_key() → str

Reads the name of the next property in a JSON object.

Returns:

The name of the property

Raises:

JSONError – if the next token is not a property name

Examples:

reader.start_map()
while reader.has_next():
    property_name = reader.next_map_key()
    print(property_name)
    reader.skip_value()
reader.end_map()

next_json() → Any

Reads the next complete JSON value (object, array, or primitive).

This method parses and returns the entire next value in the JSON stream, regardless of its complexity. It’s useful when you want to read a complete JSON structure without manually navigating through it.

Returns:

The parsed JSON value

Raises:

JSONError – if the JSON is invalid or incomplete

Examples:

# assuming the JSON value is: [{"manager": {"name": "Jane"}}, {"manager": {"name": "Alice"}}]
result = reader.next_json()
print(result[1]['manager']['name']) # prints 'Alice'

skip_value() → None

Skips the next value in the JSON stream.

Raises:

JSONError – if there is no more JSON to read, or if the next token is a property name

Examples:

reader.start_map()
while reader.has_next():
    property_name = reader.next_map_key()
    if property_name == "importantProperty":
        value = reader.next_string()
        print(value)
    else:
        print(f'Skipping {property_name}')
        reader.skip_value()
reader.end_map()

next_json_primitive() → Any

Reads the next JSON primitive value.

Returns:

The primitive value

Raises:

JSONError – if the next token is not a primitive value

next_string() → str

Reads the next value as a string.

If the next value is already a string, it is returned as is. If the next value is another primitive type, it is converted to a string.

Returns:

The string value

Raises:

JSONError – if the next token is not a primitive value

next_null() → None

Reads the next value as null.

Returns:

The null value

Raises:

JSONError – if the next token is not null

next_boolean() → bool

Reads the next value as a boolean.

Returns:

The boolean value

Raises:

JSONError – if the next token is not a boolean

next_number() → int | float

Reads the next value as a number.

Returns:

The number value

Raises:

JSONError – if the next token is not a number

json_parse(input: Any) → Any

Parses JSON data from various input sources using a streaming approach.

This function provides a way to parse JSON content from different input types without loading the entire content into memory at once. It uses the JsonReader class internally to perform the streaming parsing.

The input is expected to be a binary file-like object, but str and bytes can be used as well.

This function is mostly used for testing.

Parameters:

input – The JSON data to parse

Returns:

The parsed JSON value