Storage#

A persistent, dict-like key-value store for application preferences, backed by a JSON file and written through on every change.

For a task-oriented introduction — creating a store, autosave, JSON-only values, remembering app state — see the Preferences Store guide.

class bootstack.store.Store(name='settings', *, path=None, app_name=None, autosave=True)#

Bases: object

A persistent, dict-like key-value store for app preferences.

Construct one with a logical name and it lives at <config>/<app>/<name>.json (the per-platform config directory — Library/Application Support on macOS, %APPDATA% on Windows, $XDG_CONFIG_HOME on Linux), or pass an explicit path. Read with get() or store[key], write with set() or store[key] = value; by default every change is saved immediately with an atomic write, so a crash cannot corrupt the file.

Values must be JSON-serializable (scalars, lists, dicts); anything else raises SerializationError. Keys must be strings. A missing or unreadable file simply starts the store empty rather than raising.

Store does not require a running App — it is plain file I/O. When no app_name is given it uses the active App’s name if there is one, otherwise 'bootstack'.

Parameters:

  • name (str) – Logical store name; the file is <name>.json under the per-app config directory. Ignored when path is given.

  • path (str | PathLike[str] | None) – An explicit file path, overriding name/app_name.

  • app_name (str | None) – Override the per-app config sub-directory. Defaults to the active App’s name, or 'bootstack'.

  • autosave (bool) – When True (default), persist on every change. When False, changes stay in memory until save() is called.

Example

`python store = Store("settings") app = bs.App(theme=store.get("theme", "light")) # later, when the user switches theme: store.set("theme", "bootstrap-dark") `

property path: Path#

The file this store reads from and writes to.

as_dict()#

Return a deep copy of the store’s contents as a plain dict.

clear()#

Remove every key, persisting the now-empty store.

delete(key)#

Remove key if present; a no-op when it is missing.

get(key, default=None)#

Return the value for key, or default if it is not present.

items()#

Return the (key, value) pairs, as a list snapshot.

keys()#

Return the keys, as a list snapshot.

reload()#

Discard in-memory state and re-read the store from disk.

save()#

Write the store to disk now, atomically.

Useful when autosave=False, or to force a flush. Writes to a temporary file and renames it over the target so a partial write never replaces good data.

Raises:

OSError – If the directory cannot be created or the file written.

set(key, value)#

Set key to value and (by default) persist immediately.

Parameters:

  • key (str) – A string key.

  • value (Any) – A JSON-serializable value.

Raises:
setdefault(key, default=None)#

Return key’s value, inserting default first if it is missing.

update(values=None, **kwargs)#

Merge values in, persisting once at the end.

Accepts a mapping, keyword arguments, or both (mirroring dict.update), so store.update(theme="dark") and store.update({"theme": "dark"}) are equivalent.

values()#

Return the values, as a list snapshot.