Decoder

Note

Checkout the getting started guide for more details on encoding.

Implementation of the JSON5 decoder.

ObjectHookArg module-attribute

ObjectHookArg = dict[str, JsonValue]

Type hint for the argument of the object_hook function.

ObjectHook module-attribute

ObjectHook = Callable[[ObjectHookArg], Any]

Type hint for the object_hook function signature.

ObjectPairsHookArg module-attribute

ObjectPairsHookArg = list[tuple[str, JsonValue]]

Type hint for the argument of the object_pairs_hook function.

ObjectPairsHook module-attribute

ObjectPairsHook = Callable[[ObjectPairsHookArg], Any]

Type hint for the object_pairs_hook function signature.

Json5Decoder

Json5Decoder(
    *,
    parse_float: Callable[[str], Any] | None = None,
    parse_int: Callable[[str], Any] | None = None,
    parse_constant: Callable[[str], Any] | None = None,
    strict: bool = True,
    allow_reserved_words: bool = True,
    object_hook: ObjectHook | None = None,
    object_pairs_hook: ObjectPairsHook | None = None,
)

JSON5 decoder

Performs the following translations in decoding by default:

JSON	Python
object	dict
array	list
string	str
number (int)	int
number (real)	float
true	True
false	False
null	None

It also understands NaN, Infinity, and -Infinity as their corresponding float values, which is outside the JSON spec.

Example:

import ujson5
json5_str = '{"key": "value"}'
obj = ujson5.Json5Decoder().decode(json5_str)
# obj == {'key': 'value'}

Parameters:

Name	Type	Description	Default
parse_float	Callable[[str], Any] | None	if specified, will be called with the string of every JSON float to be decoded. By default this is equivalent to float(num_str). This can be used to use another datatype or parser for JSON floats (e.g. decimal.Decimal).	None
parse_int	Callable[[str], Any] | None	if specified, will be called with the string of every JSON int to be decoded. By default this is equivalent to int(num_str). This can be used to use another datatype or parser for JSON integers (e.g. float).	None
parse_constant	Callable[[str], Any] | None	if specified, will be called with one of the following strings: -Infinity, Infinity, NaN. This can be used to raise an exception if invalid JSON numbers are encountered.	None
strict	bool	control characters will be allowed inside strings if strict is False. Control characters in this context are those with character codes in the 0-31 range, including '\\t' (tab), '\\n', '\\r' and '\\0'.	True
allow_reserved_words	bool	if True, reserved words can be used as identifiers. Reserved words are defined here https://262.ecma-international.org/5.1/#sec-7.6.1. Default is True.	True
object_hook	ObjectHook | None	an optional function that will be called with the result of any object literal decode (a dict). The return value of object_hook will be used instead of the dict. This feature can be used to implement custom decoders (e.g. JSON-RPC class hinting).	None
object_pairs_hook	ObjectPairsHook | None	if specified will be called with the result of every JSON object decoded with an ordered list of pairs. The return value of object_pairs_hook will be used instead of the dict. This feature can be used to implement custom decoders. If object_hook is also defined, the object_pairs_hook takes priority.	None

Raises:

Type	Description
JSON5DecodeError	If the JSON5 string is invalid.

Source code in src/ujson5/decoder.py

def __init__(
    self,
    *,
    parse_float: Callable[[str], Any] | None = None,
    parse_int: Callable[[str], Any] | None = None,
    parse_constant: Callable[[str], Any] | None = None,
    strict: bool = True,
    allow_reserved_words: bool = True,
    object_hook: ObjectHook | None = None,
    object_pairs_hook: ObjectPairsHook | None = None,
) -> None:
    self._object_hook: ObjectHook | None = object_hook
    self._parse_float: Callable[[str], Any] | None = parse_float
    self._parse_int: Callable[[str], Any] | None = parse_int
    self._parse_constant: Callable[[str], Any] | None = parse_constant
    self._allow_reserved_words: bool = allow_reserved_words
    self._strict: bool = strict
    self._object_pairs_hook: ObjectPairsHook | None = object_pairs_hook

decode

decode(json5_str: str) -> Any

Deserialize a JSON5 string to a Python object.

Parameters:

Name	Type	Description	Default
json5_str	str	The JSON5 string to be deserialized.	required

Returns:

Type	Description
Any	The Python object represented by the JSON5 string.

Raises:

Type	Description
JSON5DecodeError	If the JSON5 string is invalid.

Source code in src/ujson5/decoder.py

def decode(self, json5_str: str) -> Any:
    """Deserialize a JSON5 string to a Python object.

    Args:
        json5_str: The JSON5 string to be deserialized.

    Returns:
        The Python object represented by the JSON5 string.

    Raises:
        JSON5DecodeError: If the JSON5 string is invalid.
    """
    tokens = tokenize(json5_str)
    return self._parse_json5(json5_str, tokens)

raw_decode

raw_decode(json5_str: str) -> tuple[Any, int]

Deserialize a JSON5 string to a Python object and return the index of the last character parsed.

Parameters:

Name	Type	Description	Default
json5_str	str	The JSON5 string to be deserialized.	required

Returns:

Type	Description
tuple[Any, int]	A tuple of the Python object represented by the JSON5 string and the index of the last character parsed.

Raises:

Type	Description
JSON5DecodeError	If the JSON5 string is invalid.

Source code in src/ujson5/decoder.py

def raw_decode(self, json5_str: str) -> tuple[Any, int]:
    """Deserialize a JSON5 string to a Python object and return the index of the last
    character parsed.

    Args:
        json5_str: The JSON5 string to be deserialized.

    Returns:
        A tuple of the Python object represented by the JSON5 string and the index
            of the last character parsed.

    Raises:
        JSON5DecodeError: If the JSON5 string is invalid.
    """
    tokens = tokenize(json5_str)
    if tokens[-1].tk_type == TOKEN_TYPE["STRING"]:
        # If the last token is a string, we need to skip the closing quote
        return self._parse_json5(json5_str, tokens), tokens[-1].value[1] + 1
    return self._parse_json5(json5_str, tokens), tokens[-1].value[1]

load

load(
    input_file: TextIO,
    *,
    cls: type[Json5Decoder] | None = None,
    parse_float: Callable[[str], Any] | None = None,
    parse_int: Callable[[str], Any] | None = None,
    parse_constant: Callable[[str], Any] | None = None,
    strict: bool = True,
    allow_reserved_words: bool = True,
    object_hook: ObjectHook | None = None,
    object_pairs_hook: ObjectPairsHook | None = None,
) -> Any

Deserialize fp (a .read()-supporting file-like object containing a JSON document) to a Python object.

Example:

import ujson5
with open('file.json5', 'r') as f:
    obj = ujson5.load(f)

All arguments except file are keyword-only.

Parameters:

Name	Type	Description	Default
file		A file-like object containing a JSON document.	required
cls	type[Json5Decoder] | None	If specified, must be a Json5Decoder subclass. The cls will be used to instantiate the decoder. If cls is not specified, the default Json5Decoder will be used.	None
parse_float	Callable[[str], Any] | None	if specified, will be called with the string of every JSON float to be decoded. By default this is equivalent to float(num_str). This can be used to use another datatype or parser for JSON floats (e.g. decimal.Decimal).	None
parse_int	Callable[[str], Any] | None	if specified, will be called with the string of every JSON int to be decoded. By default this is equivalent to int(num_str). This can be used to use another datatype or parser for JSON integers (e.g. float).	None
parse_constant	Callable[[str], Any] | None	if specified, will be called with one of the following strings: -Infinity, Infinity, NaN. This can be used to raise an exception if invalid JSON numbers are encountered.	None
strict	bool	control characters will be allowed inside strings if strict is False. Control characters in this context are those with character codes in the 0-31 range, including '\\t' (tab), '\\n', '\\r' and '\\0'.	True
allow_reserved_words	bool	if True, reserved words can be used as identifiers. Reserved words are defined here https://262.ecma-international.org/5.1/#sec-7.6.1. Default is True.	True
object_hook	ObjectHook | None	an optional function that will be called with the result of any object literal decode (a dict). The return value of object_hook will be used instead of the dict. This feature can be used to implement custom decoders (e.g. JSON-RPC class hinting).	None
object_pairs_hook	ObjectPairsHook | None	if specified will be called with the result of every JSON object decoded with an ordered list of pairs. The return value of object_pairs_hook will be used instead of the dict. This feature can be used to implement custom decoders. If object_hook is also defined, the object_pairs_hook takes priority.	None

Source code in src/ujson5/decoder.py

def load(
    input_file: TextIO,
    *,
    cls: type[Json5Decoder] | None = None,
    parse_float: Callable[[str], Any] | None = None,
    parse_int: Callable[[str], Any] | None = None,
    parse_constant: Callable[[str], Any] | None = None,
    strict: bool = True,
    allow_reserved_words: bool = True,
    object_hook: ObjectHook | None = None,
    object_pairs_hook: ObjectPairsHook | None = None,
) -> Any:
    r"""Deserialize `fp` (a `.read()`-supporting file-like object containing
    a JSON document) to a Python object.

    Example:
    ```python
    import ujson5
    with open('file.json5', 'r') as f:
        obj = ujson5.load(f)
    ```

    All arguments except `file` are keyword-only.

    Args:
        file: A file-like object containing a JSON document.
        cls: If specified, must be a [`Json5Decoder`][ujson5.Json5Decoder] subclass. The `cls`
            will be used to instantiate the decoder. If `cls` is not specified, the default
            `Json5Decoder` will be used.
        parse_float: if specified, will be called with the string of every JSON float to be
            decoded. By default this is equivalent to float(num_str). This can be used to use
            another datatype or parser for JSON floats (e.g. decimal.Decimal).
        parse_int: if specified, will be called with the string of every JSON int to be
            decoded. By default this is equivalent to int(num_str). This can be used to
            use another datatype or parser for JSON integers (e.g. float).
        parse_constant: if specified, will be called with one of the following strings:
            -Infinity, Infinity, NaN. This can be used to raise an exception if invalid
            JSON numbers are encountered.
        strict: control characters will be allowed inside strings if `strict` is False.
            Control characters in this context are those with character codes in the 0-31
            range, including `'\\t'` (tab), `'\\n'`, `'\\r'` and `'\\0'`.
        allow_reserved_words: if `True`, reserved words can be used as identifiers. Reserved
            words are defined here https://262.ecma-international.org/5.1/#sec-7.6.1.
            Default is `True`.
        object_hook: an optional function that will be called with the result of any object
            literal decode (a `dict`). The return value of `object_hook` will be used instead
            of the `dict`. This feature can be used to implement custom decoders
            (e.g. JSON-RPC class hinting).
        object_pairs_hook: if specified will be called with the result of every JSON object
            decoded with an ordered list of pairs.  The return value of `object_pairs_hook`
            will be used instead of the `dict`. This feature can be used to implement
            custom decoders. If `object_hook` is also defined, the `object_pairs_hook`
            takes priority.
    """
    return loads(
        input_file.read(),
        cls=cls,
        object_hook=object_hook,
        parse_float=parse_float,
        parse_int=parse_int,
        parse_constant=parse_constant,
        strict=strict,
        allow_reserved_words=allow_reserved_words,
        object_pairs_hook=object_pairs_hook,
    )

loads

loads(
    json5_str: str,
    *,
    cls: type[Json5Decoder] | None = None,
    parse_float: Callable[[str], Any] | None = None,
    parse_int: Callable[[str], Any] | None = None,
    parse_constant: Callable[[str], Any] | None = None,
    strict: bool = True,
    allow_reserved_words: bool = True,
    object_hook: ObjectHook | None = None,
    object_pairs_hook: ObjectPairsHook | None = None,
) -> Any

Deserialize json5_str (a str, bytes or bytearray instance containing a JSON document) to a Python object.

Example:

import ujson5
json5_str = '{"key": "value"}'
obj = ujson5.loads(json5_str)
# obj == {'key': 'value'}

All arguments except json5_str are keyword-only.

Parameters:

Name	Type	Description	Default
json5_str	str	The JSON5 string to be deserialized.	required
cls	type[Json5Decoder] | None	If specified, must be a Json5Decoder subclass. The cls will be used to instantiate the decoder. If cls is not specified, the default Json5Decoder will be used.	None
parse_float	Callable[[str], Any] | None	if specified, will be called with the string of every JSON float to be decoded. By default this is equivalent to float(num_str). This can be used to use another datatype or parser for JSON floats (e.g. decimal.Decimal).	None
parse_int	Callable[[str], Any] | None	if specified, will be called with the string of every JSON int to be decoded. By default this is equivalent to int(num_str). This can be used to use another datatype or parser for JSON integers (e.g. float).	None
parse_constant	Callable[[str], Any] | None	if specified, will be called with one of the following strings: '-Infinity', 'Infinity', 'NaN'. This can be used to raise an exception if invalid JSON numbers are encountered.	None
strict	bool	control characters will be allowed inside strings if strict is False. Control characters in this context are those with character codes in the 0-31 range, including '\\t' (tab), '\\n', '\\r' and '\\0'.	True
allow_reserved_words	bool	if True, reserved words can be used as identifiers. Reserved words are defined here https://262.ecma-international.org/5.1/#sec-7.6.1. Default is True.	True
object_hook	ObjectHook | None	an optional function that will be called with the result of any object literal decode (a dict). The return value of object_hook will be used instead of the dict. This feature can be used to implement custom decoders (e.g. JSON-RPC class hinting).	None
object_pairs_hook	ObjectPairsHook | None	if specified will be called with the result of every JSON object decoded with an ordered list of pairs. The return value of object_pairs_hook will be used instead of the dict. This feature can be used to implement custom decoders. If object_hook is also defined, the object_pairs_hook takes priority.	None

Source code in src/ujson5/decoder.py

def loads(
    json5_str: str,
    *,
    cls: type[Json5Decoder] | None = None,
    parse_float: Callable[[str], Any] | None = None,
    parse_int: Callable[[str], Any] | None = None,
    parse_constant: Callable[[str], Any] | None = None,
    strict: bool = True,
    allow_reserved_words: bool = True,
    object_hook: ObjectHook | None = None,
    object_pairs_hook: ObjectPairsHook | None = None,
) -> Any:
    r"""Deserialize `json5_str` (a `str`, `bytes` or `bytearray` instance
    containing a JSON document) to a Python object.

    Example:
    ```python
    import ujson5
    json5_str = '{"key": "value"}'
    obj = ujson5.loads(json5_str)
    # obj == {'key': 'value'}
    ```

    All arguments except `json5_str` are keyword-only.

    Args:
        json5_str: The JSON5 string to be deserialized.
        cls: If specified, must be a [`Json5Decoder`][ujson5.Json5Decoder] subclass. The `cls`
            will be used to instantiate the decoder. If `cls` is not specified, the default
            `Json5Decoder` will be used.
        parse_float: if specified, will be called with the string of every JSON float to be
            decoded. By default this is equivalent to float(num_str). This can be used to use
            another datatype or parser for JSON floats (e.g. decimal.Decimal).
        parse_int: if specified, will be called with the string of every JSON int to be
            decoded. By default this is equivalent to int(num_str). This can be used to
            use another datatype or parser for JSON integers (e.g. float).
        parse_constant: if specified, will be called with one of the following strings:
            '-Infinity', 'Infinity', 'NaN'. This can be used to raise an exception if invalid
            JSON numbers are encountered.
        strict: control characters will be allowed inside strings if `strict` is False.
            Control characters in this context are those with character codes in the 0-31
            range, including `'\\t'` (tab), `'\\n'`, `'\\r'` and `'\\0'`.
        allow_reserved_words: if `True`, reserved words can be used as identifiers. Reserved
            words are defined here https://262.ecma-international.org/5.1/#sec-7.6.1.
            Default is `True`.
        object_hook: an optional function that will be called with the result of any object
            literal decode (a `dict`). The return value of `object_hook` will be used instead
            of the `dict`. This feature can be used to implement custom decoders
            (e.g. JSON-RPC class hinting).
        object_pairs_hook: if specified will be called with the result of every JSON object
            decoded with an ordered list of pairs.  The return value of `object_pairs_hook`
            will be used instead of the `dict`. This feature can be used to implement
            custom decoders. If `object_hook` is also defined, the `object_pairs_hook`
            takes priority.
    """
    if cls is not None:
        decoder: Json5Decoder = cls(
            object_hook=object_hook,
            parse_float=parse_float,
            parse_int=parse_int,
            parse_constant=parse_constant,
            strict=strict,
            allow_reserved_words=allow_reserved_words,
            object_pairs_hook=object_pairs_hook,
        )
    else:
        decoder = Json5Decoder(
            object_hook=object_hook,
            parse_float=parse_float,
            parse_int=parse_int,
            parse_constant=parse_constant,
            strict=strict,
            allow_reserved_words=allow_reserved_words,
            object_pairs_hook=object_pairs_hook,
        )
    return decoder.decode(json5_str)