API Reference

Top-level package

Load and save JSON files easily across files.

Public API: - Classes: JSONFile, JsonSerializationSettings - Functions: load, sync, reset, close - Defaults: DEFAULT_SERIALIZATION_SETTINGS

class singlejson.JSONFile(path: str | PathLike[str], default_data: Any = None, *, encoding: str = 'utf-8', settings: JsonSerializationSettings | None = None, auto_save: bool = True, **kwargs: Any)

Bases: object

A .json file on the disk.

json: Any

path() → Path

Return the absolute path of the file

Returns:

reload() → None

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

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

Save the data to the disk

Parameters:

settings – JsonSerializationSettings object

save_atomic(tmp_suffix: str = '.tmp') → None

Save atomically by writing to a temp file and replacing the target. Specify serialization settings with JSONFile.settings.

Parameters:

tmp_suffix – suffix to add to target file

Returns:

class singlejson.JsonSerializationSettings(indent: 'int' = 4, sort_keys: 'bool' = True, ensure_ascii: 'bool' = False)

Bases: object

ensure_ascii: bool = False

indent: int = 4

sort_keys: bool = True

singlejson.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.load(path: str | PathLike[str], default_data: dict[str, JSONSerializable] | list[JSONSerializable] | str | int | float | bool | None = None, **kwargs: Any) → JSONFile

Open a JSONFile (synchronously) with pooling per absolute path. Backward-compat: accepts legacy “default” keyword.

singlejson.reset() → None

Clear the file pool WITHOUT saving.

singlejson.sync() → None

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

File utilities

Utils for handling IO and JSON operations.

exception singlejson.fileutils.FileAccessError

Bases: Exception

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

class singlejson.fileutils.JSONFile(path: str | PathLike[str], default_data: Any = None, *, encoding: str = 'utf-8', settings: JsonSerializationSettings | None = None, auto_save: bool = True, **kwargs: Any)

Bases: object

A .json file on the disk.

json: Any

path() → Path

Return the absolute path of the file

Returns:

reload() → None

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

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

Save the data to the disk

Parameters:

settings – JsonSerializationSettings object

save_atomic(tmp_suffix: str = '.tmp') → None

Save atomically by writing to a temp file and replacing the target. Specify serialization settings with JSONFile.settings.

Parameters:

tmp_suffix – suffix to add to target file

Returns:

class singlejson.fileutils.JsonSerializationSettings(indent: 'int' = 4, sort_keys: 'bool' = True, ensure_ascii: 'bool' = False)

Bases: object

ensure_ascii: bool = False

indent: int = 4

sort_keys: bool = True

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

singlejson.fileutils.prepare(file: str | PathLike[str], default: str) → None

Prepare a file (check if it exists and create it if not)

Parameters:

• file – File to open

• default – default text to save if file is nonexistent

Pooling

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: str | PathLike[str], default_data: dict[str, JSONSerializable] | list[JSONSerializable] | str | int | float | bool | None = None, **kwargs: Any) → JSONFile

Open a JSONFile (synchronously) with pooling per absolute path. Backward-compat: accepts legacy “default” keyword.

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.