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:

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

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[source]

Bases: Exception

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

exception singlejson.fileutils.FileAccessError[source]

Bases: Exception

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

exception singlejson.fileutils.JSONDeserializationError[source]

Bases: Exception

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

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

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

  • strict – if True, will throw error if file cannot be read or if default_data is not JSON-serializable

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

Raises:
json: Any

Python representation of the JSON data.

property path: Path

Return the absolute path of the file.

Returns:

absolute path

reload(*, recover: bool = True) → None[source]

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

Parameters:

recover (bool) – If True, recover when an error occurs during default loading. If False {} will be used if default loading fails.

Raises:
save(settings: JsonSerializationSettings | None = None) → None[source]

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

Parameters:

settings – JsonSerializationSettings object (None for instance settings)

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

Deprecated alias for save() — saves atomically by default.

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')[source]

Bases: object

encoding: str = 'utf-8'
ensure_ascii: bool = False
indent: int = 4
sort_keys: bool = True
singlejson.fileutils.abs_filename(file: str | PathLike[str]) → Path[source]

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[source]

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, dict[str, JSONSerializable] | list[JSONSerializable] | str | int | float | bool | None] | list[dict[str, JSONSerializable] | list[JSONSerializable] | str | int | float | bool | None] | str | int | float | bool | None = None, default_path: str | PathLike[str] | None = None, *, settings: JsonSerializationSettings | None = None, auto_save: bool = True, strict: bool = True, load_file: bool = True) → JSONFile[source]

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

  • strict – if True, will throw error if file cannot be read or if default_data is not JSON-serializable

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

Raises:
Returns:

pooled JSONFile instance

Return type:

JSONFile

singlejson.pool.reset() → None[source]

Clear the file pool WITHOUT saving.

singlejson.pool.sync() → None[source]

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