Getting Started

Installation

To use jsonyx, first install it using pip, pipx or conda:

(.venv) $ pip install -U jsonyx

(.venv) $ pip install --force-reinstall git+https://github.com/nineteendo/jsonyx

$ pipx install jsonyx

$ pipx install -f git+https://github.com/nineteendo/jsonyx

(base) $ conda install conda-forge::jsonyx

Check if the correct version is installed

Added in version 2.0.

$ jsonyx --version
jsonyx 2.4.0 (C extension)

Warning

If the version number is followed by (Python), the performance will be up to 82.11x slower for encoding and up to 92.54x slower decoding, so make sure you have a C compiler installed on Windows.

Quick start

Encoding basic Python object hierarchies

Changed in version 2.0: Made tuple serializable by default.

Dumping to a string:

>>> import jsonyx as json
>>> json.dumps(["foo", {"bar": ("baz", None, 1.0, 2)}])
'["foo", {"bar": ["baz", null, 1.0, 2]}]\n'

Writing to standard output:

>>> import jsonyx as json
>>> json.dump('"foo\bar')
"\"foo\bar"
>>> json.dump("\\")
"\\"
>>> json.dump("\u20AC")
"€"

Writing to an open file:

>>> import jsonyx as json
>>> from io import StringIO
>>> io = StringIO()
>>> json.dump(["writer protocol"], io)
>>> io.getvalue()
'["writer protocol"]\n'

Writing to a file:

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

Tip

Use jsonyx.Encoder directly for better performance.

Note

The output is not written incrementally, but in one-shot.

Compact encoding

Changed in version 2.0: Replaced item_separator and key_separator with separators.

>>> import jsonyx as json
>>> json.dumps({"a": 1, "b": 2, "c": 3}, end="", separators=(",", ":"))
'{"a":1,"b":2,"c":3}'

Pretty printing

Changed in version 2.0: Added indent_leaves and max_indent_level.

>>> import jsonyx as json
>>> obj = {"foo": [[1, 2], [3, 4]], "bar": {"a": 1, "b": 2, "c": 3}}
>>> json.dump(obj, indent=4, indent_leaves=False)
{
    "foo": [
        [1, 2],
        [3, 4]
    ],
    "bar": {"a": 1, "b": 2, "c": 3}
}
>>> json.dump(obj, indent=4, max_indent_level=1)
{
    "foo": [[1, 2], [3, 4]],
    "bar": {"a": 1, "b": 2, "c": 3}
}

Tip

Use sort_keys=True to sort the keys of objects.

See also

The built-in pprint module for pretty-printing arbitrary Python data structures.

Decoding JSON

Loading from a string:

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

Reading from an open file:

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

Reading from a file:

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

Tip

Use jsonyx.Decoder directly for better performance.

Note

Allow non-standard numeric values

By default, jsonyx does not allow NaN, Infinity or -Infinity. To enable them, pass jsonyx.allow.NAN_AND_INFINITY to allow:

>>> import jsonyx as json
>>> import jsonyx.allow
>>> json.loads("[NaN, Infinity, -Infinity]", allow=jsonyx.allow.NAN_AND_INFINITY)
[nan, inf, -inf]
>>> from math import inf, nan
>>> json.dump([nan, inf, -inf], allow=jsonyx.allow.NAN_AND_INFINITY)
[NaN, Infinity, -Infinity]

Making a patch from two Python objects

Added in version 2.0.

>>> import jsonyx as json
>>> json.make_patch([1, 2, 3], [1, 3])
[{'op': 'del', 'path': '$[1]'}]

Applying a patch

Added in version 2.0.

>>> import jsonyx as json
>>> json.apply_patch([1, 2, 3], {"op": "del", "path": "$[1]"})
[1, 3]

Tip

Using the jsonyx application

Added in version 2.0.

$ echo '{"foo": [1, 2, 3], "bar": {"a": 1, "b": 2, "c": 3}}' | jsonyx format \
--indent 4 \
--no-indent-leaves
{
    "foo": [1, 2, 3],
    "bar": {"a": 1, "b": 2, "c": 3}
}
$ echo "{1.2: 3.4}" | jsonyx format
  File "<stdin>", line 1, column 2
    {1.2: 3.4}
     ^
jsonyx.JSONSyntaxError: Expecting string

See API and Command Line Interface for more details.