jsonyx.write

jsonyx.write(obj, filename, encoding='utf-8', *, allow=NOTHING, check_circular=True, commas=True, end='\\n', ensure_ascii=False, formatters=None, hook=None, indent=None, indent_leaves=True, max_indent_level=None, quoted_keys=True, separators=(', ', ': '), skipkeys=False, sort_keys=False, trailing_comma=False, types=None)[source]

Serialize a Python object to a JSON file.

Changed in version 2.0:

  • Added commas, encoding, indent_leaves, max_indent_level, quoted_keys and types.

  • Allowed overriding serialization in subclasses of float and int (e.g. enum.Enum).

  • Made tuple serializable by default instead of decimal.Decimal.

  • Replaced item_separator and key_separator with separators.

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

Changed in version 2.4:

  • Added formatters.

  • Allowed overriding serialization in subclasses of str (e.g. enum.Enum).

  • Made frozendict serializable by default.

Parameters:

  • obj (object) – a Python object

  • filename (_StrPath) – the path to the JSON file

  • encoding (str, default: "utf-8") – the JSON encoding

  • 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

  • end (str, default: "\\n") – the string to append at the end

  • ensure_ascii (bool, default: False) – escape non-ASCII characters

  • formatters (dict[str, _Formatter] | None, default: None) – a dictionary of formatters

  • hook (_Hook | None, default: None) – the hook used for transforming data

  • 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, _ClassInfo] | None, default: None) – a dictionary of additional types

Raises:
Example:
>>> 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 item separator is automatically stripped when indented.

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

Warning

Avoid specifying ABCs for types, that is very slow.

See also