jsonyx.Decoder

class jsonyx.Decoder(*, allow=NOTHING, cache_keys=False, hooks=None)

Bases: object

A configurable JSON decoder.

Changed in version 2.0: Replaced use_decimal with hooks.`

Changed in version 2.2: Added cache_keys (default False instead of True).

Parameters:

• allow (Container[str], default: NOTHING) – the JSON deviations from jsonyx.allow

• cache_keys (bool, default: False) – re-use the keys of objects

• hooks (dict[str, _Hook] | None, default: None) – the hooks used for transforming data

See also

jsonyx.Encoder for serialization.

load(fp, *, root='.')

Deserialize an open JSON file to a Python object.

Parameters:

• fp (Reader[bytes | str]) – an open JSON file

• root (_StrPath, default: ".") – the path to the archive containing this JSON file

Raises:

• RecursionError – if the JSON file is too deeply nested

• TruncatedSyntaxError – when failing to decode the file

• ValueError – if a number is too big

Returns:

Any – a Python object

Example:

>>> import jsonyx as json
>>> from io import StringIO
>>> decoder = json.Decoder()
>>> io = StringIO('["reader protocol"]')
>>> decoder.load(io)
['reader protocol']

Tip

Specify root to display the zip filename in error messages.

Note

• The input is not read incrementally, but in one-shot.

• The encoding is detected using jsonyx.detect_encoding().

• Keys are never re-used across calls.

loads(s, *, filename='<string>')

Deserialize a JSON string to a Python object.

Parameters:

• s (bytearray | bytes | str) – a JSON string

• filename (_StrPath, default: "<string>") – the path to the JSON file

Raises:

• RecursionError – if the JSON string is too deeply nested

• TruncatedSyntaxError – when failing to decode the string

• ValueError – if a number is too big

Returns:

Any – a Python object

Example:

>>> import jsonyx as json
>>> decoder = json.Decoder()
>>> decoder.loads('{"foo": ["bar", null, 1.0, 2]}')
{'foo': ['bar', None, 1.0, 2]}
>>> decoder.loads(r'"\"foo\bar"')
'"foo\x08ar'

Tip

Specify filename to display the filename in error messages.

Note

• The encoding is detected using jsonyx.detect_encoding().

• Keys are never re-used across calls.

read(filename)

Deserialize a JSON file to a Python object.

Parameters:

filename (_StrPath) – the path to the JSON file

Raises:

• OSError – if the file can’t be opened

• RecursionError – if the JSON file is too deeply nested

• TruncatedSyntaxError – when failing to decode the file

• ValueError – if a number is too big

Returns:

Any – a Python object

Example:

>>> import jsonyx as json
>>> from os.path import join
>>> from tempfile import TemporaryDirectory
>>> decoder = json.Decoder()
>>> with TemporaryDirectory() as tmpdir:
...     filename = join(tmpdir, "file.json")
...     with open(filename, "w", encoding="utf-8") as fp:
...         _ = fp.write('["filesystem API"]')
...     decoder.read(filename)
...
['filesystem API']

Note

• The input is not read incrementally, but in one-shot.

• The encoding is detected using jsonyx.detect_encoding().

• Keys are never re-used across calls.