pyglet.storage

Paths and persistence notifications for application-created data.

Unlike pyglet.resource, which locates read-only files shipped with an application, this module provides locations for files created while the application is running. Files are read and written with the usual Python filesystem APIs.

Location	Purpose
`temporary`	Disposable working files. It may be cleared at any time.
`cache`	Re-creatable files retained between runs, but safe to purge.
`data`	User-created or irreplaceable application content.
`settings`	Preferences, key bindings, and other configuration.

On desktop platforms cache files live below the application’s data directory. In a browser, data and settings use the IndexedDB-backed /data mount while cache uses the Origin Private File System-backed /cache mount. Both browser locations require Storage.sync() to make writes durable.

Structured settings

Named settings sections provide a small dictionary-like API backed by one human-readable JSON file:

storage = pyglet.storage.get("my-game")
window = storage.settings.create(
    "window",
    defaults={"size": [1280, 720], "fullscreen": False},
)
window["size"] = [1920, 1080]
storage.settings.sync()

Defaults fill in missing keys without replacing values that were already saved. Assign a key to replace one value, or call clear followed by update to replace an entire section. Settings values must be JSON serializable. Use storage.settings.path or storage.settings / "filename" for additional files that should live in the settings directory but do not belong in the JSON document.

Browser persistence is asynchronous internally. Storage.sync() returns immediately and dispatches on_sync or on_sync_error when synchronization finishes.

class Settings( path: str | PathLike[str], sync: Callable[[], bool], ) → None

JSON-backed application settings and their containing directory.

Use create() to obtain named dictionary-like sections. Files that do not belong in the JSON document can still be stored beneath path, or by using the / operator directly on this object.

Load the JSON settings document beneath path if it exists.

create( name: str, defaults: Mapping[str, Any] | None = None, ) → SettingsSection

Return a named settings section, filling in any missing defaults.

Existing values are never replaced by defaults, which allows new defaults to be added in later application versions without resetting a user’s choices.

Return type:: SettingsSection

remove(name: str) → None

Remove a settings section.

Raises:: KeyError – If the section does not exist.
Return type:: None

save() → None

Write all settings sections to the JSON file.

Return type:: None

sync() → bool

Write all sections to JSON and request platform persistence.

Return type:: bool

class SettingsSection(name: str, data: dict[str, Any]) → None

A dictionary-like named section in a Settings document.

Create a view over one section of a settings document.

class Storage(name: str, *, _backend: Any | None = None) → None

Filesystem locations belonging to one application or component.

Applications will normally obtain one instance with get(). Multiple named instances are supported so reusable libraries, editors with separate projects, and test environments can avoid sharing settings or saved data. Repeated calls to get with the same name return the same instance.

Parameters:: name (str) – Stable application or component identifier. It may contain ASCII letters, digits, dots, underscores, and hyphens, but no path separators.

Events:

on_sync:: Dispatched after all synchronization requests made so far have completed successfully.
on_sync_error(error):: Dispatched when persistent storage could not be synchronized.

Create storage paths for name using the current platform.

on_sync() → None

Default handler for successful synchronization.

Return type:: None

on_sync_error(error: Exception) → None

Default handler for synchronization failure.

Return type:: None

sync() → bool

Request that pending writes be committed to persistent storage.

This method never needs to be awaited. On desktop systems completion is immediate. In a browser, the host’s pyglet_emscripten module asynchronously synchronizes both the data and cache filesystems.

If synchronization is already active, the request is coalesced into a single follow-up pass. This prevents overlapping saves while ensuring that writes made during the active pass are included before on_sync is dispatched.

Return type:: bool

property persistent: bool: Whether the backend is intended to survive application restarts.

property syncing: bool: Whether a persistent-storage synchronization is in progress.

get(name: str) → Storage

Return the shared storage object for an application or component.

Most applications should call this once with a stable identifier and use the returned object throughout their lifetime. The name is required so saved data remains in the same location if the executable or entry-point filename changes.

Multiple names are allowed primarily for reusable components that must not write into their host application’s namespace, applications that manage independently stored projects or profiles, and isolated tests. Calling this function repeatedly with the same name does not create additional storage areas; it returns the existing Storage instance.

Return type:: Storage