jsonyx.Encoder¶

class jsonyx.Encoder(*, allow=NOTHING, check_circular=True, commas=True, hook=None, end='\\n', ensure_ascii=False, indent=None, indent_leaves=True, max_indent_level=None, quoted_keys=True, separators=(', ', ': '), skipkeys=False, sort_keys=False, trailing_comma=False, types=None)¶

Bases: object

A configurable JSON encoder.

Changed in version 2.0:

Added commas, indent_leaves, max_indent_level, quoted_keys and types.
Made tuple serializable by default instead of enum.Enum and decimal.Decimal.
Replaced item_separator and key_separator with separators.

Changed in version 2.1: Added check_circular, hook and skipkeys.

Parameters:

allow (Container[str], default: NOTHING) – the JSON deviations from jsonyx.allow
check_circular (bool, default: True) – check for circular references
commas (bool, default: True) – separate items by commas when indented
hook (_Hook | None, default: None) – the hook used for transforming data
end (str, default: "\\n") – the string to append at the end
ensure_ascii (bool, default: False) – escape non-ASCII characters
indent (int | str | None, default: None) – the number of spaces or string to indent with
indent_leaves (bool, default: True) – indent leaf objects and arrays
max_indent_level (int | None, default: None) – the level up to which to indent
quoted_keys (bool, default: True) – quote keys which are identifiers
separators (tuple[str, str], default: (", ", ": ")) – the item and key separator
skipkeys (bool, default: False) – skip non-string keys
sort_keys (bool, default: False) – sort the keys of objects
trailing_comma (bool, default: False) – add a trailing comma when indented
types (dict[str, type | tuple[type, ...]] | None, default: None) – a dictionary of additional types

Note

The item separator is automatically stripped when indented.

Warning

Avoid specifying ABCs for types, that is very slow.

dump(obj, fp=None)[source]¶

Serialize a Python object to an open JSON file.

Parameters:

obj (object) – a Python object
fp (_SupportsWrite[str] | None, default: None) – an open JSON file

Raises:

RecursionError – if the object is too deeply nested
TypeError – for unserializable values
TruncatedSyntaxError – when failing to write to the file
ValueError – for invalid values

Example:

Writing to standard output:

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

Writing to an open file:

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

dumps(obj)[source]¶

Serialize a Python object to a JSON string.

Parameters:

obj (object) – a Python object

Raises:

RecursionError – if the object is too deeply nested
TypeError – for unserializable values
ValueError – for invalid values

Returns:

str – a JSON string

Example:

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

write(obj, filename, encoding='utf-8')[source]¶

Serialize a Python object to a JSON file.

Changed in version 2.0: Added encoding.

Parameters:

obj (object) – a Python object
filename (_StrPath) – the path to the JSON file
encoding (str, default: "utf-8") – the JSON encoding

Raises:

OSError – if the file can’t be opened
RecursionError – if the object is too deeply nested
TypeError – for unserializable values
TruncatedSyntaxError – when failing to encode the file
ValueError – for invalid values

Example:

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