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.3.0 (C extension)

Warning

If the version number is followed by (Python), the performance will be up to 8.03x slower for encoding and up to 46.71x slower for 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(["streaming API"], io)
>>> io.getvalue()
'["streaming API"]\n'

Writing to a file:

>>> import jsonyx as json
>>> from pathlib import Path
>>> from tempfile import TemporaryDirectory
>>> with TemporaryDirectory() as tmpdir:
...     filename = Path(tmpdir) / "file.json"
...     json.write(["filesystem API"], filename)
...     filename.read_text("utf-8")
...
'["filesystem API"]\n'

Tip

Using jsonyx.Encoder is faster.

Compact encoding

Changed in version 2.0:

  • Added quoted_keys.

  • 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}'

Tip

Use quoted_keys=False for even more compact encoding, but this isn’t widely supported.

Pretty printing

Changed in version 2.0: Added indent_leaves and max_indent_level.

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

Tip

Use ensure_ascii=True to escape non-ASCII characters, max_indent_level=1 to indent up to level 1, and 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('["streaming API"]')
>>> json.load(io)
['streaming API']

Reading from a file:

>>> import jsonyx as json
>>> from pathlib import Path
>>> from tempfile import TemporaryDirectory
>>> with TemporaryDirectory() as tmpdir:
...     filename = Path(tmpdir) / "file.json"
...     _ = filename.write_text('["filesystem API"]', "utf-8")
...     json.read(filename)
...
['filesystem API']

Tip

Using jsonyx.Decoder is faster.

Using decimal.Decimal instead of float

Changed in version 2.0:

  • Added types.

  • Made decimal.Decimal not serializable by default.

  • Replaced use_decimal with hooks.

>>> import jsonyx as json
>>> from decimal import Decimal
>>> json.loads("1.1", hooks={"float": Decimal})
Decimal('1.1')
>>> json.dump(Decimal('1.1'), types={"float": Decimal})
1.1

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 a filter instead of an index is more robust.

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.