Advanced usage¶

Context manager and auto-save¶

JSONFile implements __enter__/__exit__. By default it saves automatically on a clean exit (no exception). You can disable this by passing auto_save=False.

from singlejson import JSONFile

# Auto-save on clean exit
with JSONFile("data.json", default_data={}) as jf:
    jf.json["counter"] = 1

# No auto-save
with JSONFile("scratch.json", default_data={}, auto_save=False) as jf:
    jf.json["tmp"] = True

Pooling: one instance per path¶

singlejson.load(path) returns a shared instance per absolute path, so different parts of your code operate on the same in-memory object.

from singlejson import load, sync

a = load("shared.json", default_data={})
b = load("shared.json")
assert a is b
a.json["x"] = 1
sync()  # persists changes to disk

Serialization settings¶

Use singlejson.JsonSerializationSettings to control indentation, key ordering, and ASCII escaping. You can set a per-instance default via JSONFile(..., settings=...).

If not specified, the global default settings from DEFAULT_SERIALIZATION_SETTINGS will be loaded. You can also directly change these.

from singlejson import JSONFile, JsonSerializationSettings, DEFAULT_SERIALIZATION_SETTINGS

jf = JSONFile("fmt.json", default_data={},
             settings=JsonSerializationSettings(indent=2, sort_keys=True, ensure_ascii=False))
jf.json = {"b": 2, "a": 1}
jf.save()               # uses the instance settings
jf.save_atomic()        # atomic write using the same settings

global_jf = JSONFile("global.json", default_data={})
global_jf.json = {"b": 2, "a": 1}
DEFAULT_SERIALIZATION_SETTINGS.indent = 4
global_jf.save()        # uses updated global settings
global_jf.save_atomic() # atomic write using the global settings

Atomic saves¶

JSONFile.save_atomic() writes to a temporary file and replaces the target file in a single operation, helping avoid corruption on crashes.

This will fully write a temporary file before replacing the original. save_atomic() is safer but may not be suitable for very large files.

Error handling¶

Invalid JSON on load is handled gracefully by falling back to default_data.
FileAccessError is raised for permission or IO errors during prepare/read/write.