Serialization settings

Overview

The formatting of JSON files produced by singlejson is controlled by singlejson.JsonSerializationSettings. These settings govern indentation, key ordering, ASCII escaping, and other JSON encoder options. Settings may be applied globally (the default for all files), per JSONFile instance, or passed for a single save operation.

Common options

  • indent — number of spaces to use for pretty-printed JSON (None for compact output).

  • sort_keys — whether object keys should be sorted alphabetically.

  • ensure_ascii — escape non-ASCII characters when True.

  • encoding — character encoding used when writing files (normally utf-8).

Global defaults

A module-level DEFAULT_SERIALIZATION_SETTINGS is exported by singlejson. It is used whenever an instance does not provide its own settings.

from singlejson import DEFAULT_SERIALIZATION_SETTINGS

# Change global defaults (affects future JSONFile instances that don't
# override settings)
DEFAULT_SERIALIZATION_SETTINGS.indent = 2
DEFAULT_SERIALIZATION_SETTINGS.sort_keys = True

Note: DEFAULT_SERIALIZATION_SETTINGS is a mutable object. If you want to use the default values as a starting point without mutating the global object, copy it and pass the copy to a JSONFile instance (see next section).

Per-instance settings

Pass a JsonSerializationSettings instance to a JSONFile at creation time or assign to JSONFile.settings later to control formatting for that particular file.

from singlejson import JSONFile, JsonSerializationSettings

# Per-instance settings at creation
jf = JSONFile("data.json", default_data={},
              settings=JsonSerializationSettings(indent=4, sort_keys=False))

# Or replace settings on an existing instance
jf.settings = JsonSerializationSettings(indent=2, sort_keys=True)

Per-save overrides

If you need a one-off format change for a particular save, pass a settings argument to JSONFile.save(). This does not modify the instance or global defaults.

jf.save(settings=JsonSerializationSettings(indent=0, sort_keys=True))

Examples

A compact example showing global, per-instance and per-save usage:

from singlejson import JSONFile, JsonSerializationSettings, DEFAULT_SERIALIZATION_SETTINGS

# global default: pretty-print with indent=2
DEFAULT_SERIALIZATION_SETTINGS.indent = 2

# instance-specific: two-space indent, but sorted keys
jf = JSONFile("example.json", default_data={},
              settings=JsonSerializationSettings(indent=2, sort_keys=True))
jf.json = {"b": 2, "a": 1}
jf.save()  # uses instance settings

# one-off compact save (no indent)
jf.save(settings=JsonSerializationSettings(indent=None))

Notes and tips

  • Copy the global settings if you want to use them as a baseline without mutating the global object: DEFAULT_SERIALIZATION_SETTINGS.copy().

  • Use ensure_ascii=False to keep non-ASCII characters readable in output files (useful for UTF-8 workflows).

  • indent=None writes compact JSON on one line; indent=0 is not meaningful for the built-in encoder and should be avoided.