API Reference

Top-level package

The main singlejson package.

singlejson exports the JSONFile class as well as many functions from the singlejson.pool module:

• load() to load a shared JSON file instance

• sync() to save all loaded files

• reset() to clear the pool (with or without saving)

• close() to remove a specific file from the pool

To access default serialization settings, use:

• DEFAULT_SERIALIZATION_SETTINGS

• JsonSerializationSettings

Exceptions thrown by the package are also exported directly from the top-level package.

• DefaultNotJSONSerializableError

• FileAccessError

• JSONDeserializationError

singlejson.DEFAULT_SERIALIZATION_SETTINGS: JsonSerializationSettings

The global default serialization settings instance.

File utilities

This module contains the implementation details for file I/O and JSON serialization. Most of these are also available directly from the singlejson package.

Utils for handling IO and JSON operations.

singlejson.fileutils.DEFAULT_SERIALIZATION_SETTINGS = JsonSerializationSettings(indent=4, sort_keys=True, ensure_ascii=False, encoding='utf-8')

Default JsonSerializationSettings used by JSONFile instances with indent=4, sort_keys=True, ensure_ascii=False

exception singlejson.fileutils.DefaultNotJSONSerializableError

Bases: Exception

Raised when the provided default data is not JSON-serializable.

exception singlejson.fileutils.FileAccessError

Bases: Exception

Raised when the file cannot be accessed due to permissions or IO errors.

exception singlejson.fileutils.JSONDeserializationError

Bases: Exception

Raised when JSON data loaded from a file cannot be deserialized.

singlejson.fileutils.JSONFields: TypeAlias = dict[str, 'JSONFields'] | list['JSONFields'] | str | int | float | bool | None

A type alias for valid JSON fields (inside a json).

class singlejson.fileutils.JSONFile(path: str | PathLike[str], default_data: dict[str, dict[str, JSONFields] | list[JSONFields] | str | int | float | bool | None] | list[dict[str, JSONFields] | list[JSONFields] | str | int | float | bool | None] | str | None = None, default_path: str | PathLike[str] | None = None, *, settings: JsonSerializationSettings | None = None, auto_save: bool = True, preserve: bool | None = None, strict: bool = False, load_file: bool = True)

Bases: object

A .json file on the disk.

Create a new JSONFile instance and load data from disk Specify defaults preferably with default_data or default_path.

Parameters:

• path – path to file (str or PathLike)

• default_data – Default data to use if file at path is nonexistent or corrupted. Keep in mind that None is serializable as JSON “null” - will not throw an error if not specified.

• default_path – Overrides default_data if provided. Path to a JSON file to use as default data.

• settings – JsonSerializationSettings object

• auto_save – if True, context manager will save on exit

• preserve – Preserve the existing file by renaming it to <filename>.old.x.ext before writing defaults during recovery. None uses the instance default (False unless set later).

• strict – if True, will throw error if file cannot be read or if default_data or json in default_path is not JSON-serializable if False, will recover gracefully. Read Error handling for more info

• load_file – True by default, causes file to be loaded on init. Set to False to suppress loading.

Raises:

• FileAccessError – if file cannot be accessed (always)

• JSONDeserializationError – if strict is True and an error occurs during loading

• DefaultNotJSONSerializableError – if strict is True and default_data is not JSON-serializable

json: Any

Python representation of the JSON data.

property preserve: bool

Whether to keep backups of existing files during recovery.

reload(strict: bool = False, preserve: bool | None = None) → None

Reload from disk, recovering to default on invalid JSON. Always raises FileAccessError on permission issues.

Parameters:

• strict (bool) – if True, will throw error if file cannot be read or if default_data or json in default_path is not JSON-serializable if False, will recover gracefully. Read Error handling for more info

• preserve – Preserve the existing file by renaming it to <filename>.old.x.ext before writing defaults during recovery. None uses the instance setting (False unless changed).

Raises:

• FileAccessError – if file cannot be accessed (always)

• DefaultNotJSONSerializableError – if strict is True and JSON is invalid

restore_default(strict: bool = False, preserve: bool | None = None) → None

Revert the file to the default either by copying the default to the file path or by writing the default data to the file.

Parameters:

• strict – if True, will throw error if file cannot be read or if default_data or json in default_path is not JSON-serializable if False, will recover gracefully. Read Error handling for more info

• preserve – Preserve the existing file by renaming it to <filename>.old.x.ext before writing defaults during recovery. None uses the instance setting.

Raises:

• DefaultNotJSONSerializableError – if default data is not JSON-serializable and strict is true

• FileAccessError – if file cannot be accessed (always)

save(settings: JsonSerializationSettings | None = None) → None

Save the data to the disk (atomically by default).

Parameters:

settings – JsonSerializationSettings object (None for instance settings)

settings: JsonSerializationSettings

Serialization settings of this instance

class singlejson.fileutils.JsonSerializationSettings(indent: 'int' = 4, sort_keys: 'bool' = True, ensure_ascii: 'bool' = False, encoding: 'str' = 'utf-8')

Bases: object

encoding: str = 'utf-8'

ensure_ascii: bool = False

indent: int = 4

sort_keys: bool = True

singlejson.fileutils.SensibleTopLevelJSON: TypeAlias = dict[str, 'JSONFields'] | list['JSONFields'] | str

A type alias for valid top level JSON objects (only for use in default_data)

singlejson.fileutils.abs_filename(file: str | PathLike[str]) → Path

Return the absolute path of a file as pathlib.Path.

Parameters:

file – File to get the absolute path of

Returns:

Absolute Path of file

Pooling

This module manages the global file pool. The functions here are also available directly from the singlejson package.

The main files handling the file pool.

singlejson.pool.close(path: str | PathLike[str] | None = None, *, save: bool = True) → None

Close one file (by path) or all files, optionally saving first. If you wish to adjust settings, change the default or change the JsonFile.settings property.

Parameters:

• path – The path of the file to close.

• save – Whether to save the file or not.

singlejson.pool.load(path: PathOrSimilar, default_data: SensibleTopLevelJSON | None = None, default_path: PathOrSimilar | None = None, *, settings: JsonSerializationSettings | None = None, auto_save: bool = True, preserve: bool | None = None, strict: bool = False, load_file: bool = True) → JSONFile

Open a new JSONFile and add it to the pool. Specify defaults preferably with default_data or default_path.

Parameters:

• path – path to file (str or PathLike)

• default_data – Default data to use if file is nonexistent or corrupted. Keep in mind that None is serializable as JSON “null” - will not throw an error if not specified.

• default_path – Overrides default_data if provided. Path to a JSON file to use as default data.

• settings – JsonSerializationSettings object

• auto_save – if True, context manager will save on exit

• preserve – Preserve the existing file by renaming it to <filename>.old.x.ext before writing defaults during recovery. None uses the instance default.

• strict – if True, will throw error if file cannot be read if default_data or json in default_path is not JSON-serializable if False, will recover gracefully. Read Error handling for more info

• load_file – True by default, causes file to be loaded on init. Set to False to suppress loading.

Raises:

• FileAccessError – if file cannot be accessed (always)

• JSONDeserializationError – if strict is True and an error occurs during loading

• DefaultNotJSONSerializableError – if strict is True and default_data is not JSON-serializable

Returns:

pooled JSONFile instance

Return type:

JSONFile

singlejson.pool.reset() → None

Clear the file pool WITHOUT saving.

singlejson.pool.sync() → None

Sync all pooled files to the filesystem. If you wish to adjust settings, change the default or change the JsonFile.settings property.