ddp_utils.browser.facade.storage

import ddp_utils.browser.facade.storage

Backend-neutral Web Storage services.

class ddp_utils.browser.facade.storage.BrowserStorage(browser: Browser)

Bases: object

Expose local and session Web Storage areas.

Parameters

Name	Type	Description
browser	Browser	Owning browser facade.

Examples

Use both storage scopes explicitly:

browser.storage.local.set("persistent", "yes")
browser.storage.session.set("temporary", "yes")

Create both session-bound storage areas.

Parameters

Name	Type	Description
browser	Browser	Owning browser facade.

Examples

Browser creates this aggregate once:

storage = BrowserStorage(browser)

get(key: str, default: Any = None, *, area: str = 'local') → Any

Return one Web Storage value.

Parameters

Name	Type	Description
key	str	Storage key.
default	Any	Value returned when absent.
area	str	local or session.

Returns

Type	Description
Any	Stored value or default.

Examples

cursor = browser.storage.get("cursor").

set(key: str, value: Any, *, area: str = 'local') → None

Set one Web Storage value.

Parameters

Name	Type	Description
key	str	Storage key.
value	Any	Value converted to text.
area	str	local or session.

Examples

browser.storage.set("cursor", 5).

delete(key: str, *, area: str = 'local') → bool

Delete one Web Storage key.

Parameters

Name	Type	Description
key	str	Storage key.
area	str	local or session.

Returns

Type	Description
bool	True when the key existed.

Examples

browser.storage.delete("cursor").

clear(*, area: str = 'local', origin: str | None = None) → None

Clear one storage area for the active origin.

Parameters

Name	Type	Description
area	str	local or session.
origin	str | None	Optional active-origin assertion.

Raises

Exception	Description
ValueError	origin differs from the active page origin.

Examples

browser.storage.clear(area="session").

items(*, area: str = 'local') → dict[str, Any]

Return all values in one storage area.

Parameters

Name	Type	Description
area	str	local or session.

Returns

Type	Description
dict[str, Any]	Key/value mapping.

Examples

state = browser.storage.items().

snapshot(*, origins: Any = None) → StorageSnapshot

Capture Web Storage for the active origin.

Parameters

Name	Type	Description
origins	Any	Optional origin or collection; every value must equal the active origin because synchronous Web Storage is origin-bound.

Returns

Type	Description
StorageSnapshot	Portable storage snapshot.

Raises

Exception	Description
ValueError	If an origin other than the active one is requested.

Examples

snapshot = browser.storage.snapshot().

restore(snapshot: StorageSnapshot, *, clear: bool = False) → None

Restore storage for the active origin.

Parameters

Name	Type	Description
snapshot	StorageSnapshot	Portable storage snapshot.
clear	bool	Clear both areas before restoring.

Raises

Exception	Description
ValueError	The snapshot lacks the active origin.

Examples

browser.storage.restore(snapshot, clear=True).

save(path: str | Path, *, origins: Any = None) → Path

Persist a storage snapshot as UTF-8 JSON.

Parameters

Name	Type	Description
path	str | Path	Destination file.
origins	Any	Optional active-origin assertion.

Returns

Type	Description
Path	Absolute destination path.

Examples

browser.storage.save("storage.json").

load(path: str | Path, *, clear: bool = False) → None

Load and restore a JSON storage snapshot.

Parameters

Name	Type	Description
path	str | Path	Source file.
clear	bool	Clear current values first.

Examples

browser.storage.load("storage.json", clear=True).

class ddp_utils.browser.facade.storage.BrowserStorageArea(browser: Browser, name: str)

Bases: object

Operate on one localStorage or sessionStorage area.

Parameters

Name	Type	Description
browser	Browser	Owning browser facade.
name	str	localStorage or sessionStorage.

Examples

Store one local value:

browser.storage.local.set("court", "Fulton")

Bind one validated storage area.

Parameters

Name	Type	Description
browser	Browser	Owning browser facade.
name	str	JavaScript storage object name.

Raises

Exception	Description
ValueError	The area name is unsupported.

Examples

Create the session storage service:

area = BrowserStorageArea(browser, "sessionStorage")

get(key: str, default: Any = None) → Any

Return a stored string or a caller-provided default.

Parameters

Name	Type	Description
key	str	Storage key.
default	Any	Value returned when the key is absent.

Returns

Type	Description
Any	Stored string or default.

Raises

Exception	Description
UnsupportedCapabilityError	Storage is unavailable.

Examples

Read an optional cursor:

cursor = browser.storage.session.get("cursor")

set(key: str, value: Any) → None

Store one value after converting it to text.

Parameters

Name	Type	Description
key	str	Storage key.
value	Any	Value converted to text.

Raises

Exception	Description
UnsupportedCapabilityError	Storage is unavailable.

Examples

Store a project checkpoint:

browser.storage.local.set("page", 5)

update(values: Mapping[str, Any]) → None

Store multiple values in one browser-side operation.

Parameters

Name	Type	Description
values	Mapping[str, Any]	Key/value mapping converted to strings.

Raises

Exception	Description
UnsupportedCapabilityError	Storage is unavailable.

Examples

Store related project state atomically in one script call:

browser.storage.local.update({"page": 5, "row": 11})

remove(key: str) → None

Delete one storage key.

Parameters

Name	Type	Description
key	str	Storage key.

Raises

Exception	Description
UnsupportedCapabilityError	Storage is unavailable.

Examples

Remove an obsolete cursor:

browser.storage.session.remove("cursor")

clear() → None

Remove every value from this storage area.

Raises

Exception	Description
UnsupportedCapabilityError	Storage is unavailable.

Examples

Reset local application state:

browser.storage.local.clear()

all() → dict[str, str]

Return a complete storage snapshot.

Returns

Type	Description
dict[str, str]	String key/value mapping.

Raises

Exception	Description
UnsupportedCapabilityError	Storage is unavailable.

Examples

Preserve state for diagnostics:

snapshot = browser.storage.local.all()

class ddp_utils.browser.facade.storage.StorageSnapshot(origins: dict[str, dict[str, dict[str, Any]]])

Bases: object

Store Web Storage values grouped by origin and area.

Parameters

Name	Type	Description
origins	dict[str, dict[str, dict[str, Any]]]	origin -> {local, session} mappings.

Examples

snapshot = browser.storage.snapshot().