Storage

Key/value persistence backed by the platform-native store (NSUserDefaults on iOS, SharedPreferences on Android, a local JSON file in desktop tests). All operations are coroutines so they don't block the framework loop.

Cross-platform key/value persistence (AsyncStorage).

Mirrors React Native's AsyncStorage API but with native async coroutines and a JSON convenience layer. Values are persisted using the platform-appropriate key/value store:

• iOS: NSUserDefaults (standard user defaults).
• Android: SharedPreferences (file "pn_async_storage").
• Desktop / tests: an in-memory dict optionally backed by a JSON file under FileSystem.app_dir for inter-run persistence during local development.

All operations are coroutines so they don't block the framework loop; the underlying native calls are dispatched via :func:asyncio.to_thread.

Example

import pythonnative as pn


async def remember_user(user):
    await pn.AsyncStorage.set_json("current_user", user.to_dict())


async def restore_session():
    user_dict = await pn.AsyncStorage.get_json("current_user")
    if user_dict is None:
        return None
    return User.from_dict(user_dict)

Classes:

Name	Description
AsyncStorage	Async key/value persistence layered on platform-native stores.

Functions:

Name	Description
use_persisted_state	Persisted use_state variant.

AsyncStorage

Async key/value persistence layered on platform-native stores.

Every method is a coroutine that returns when the underlying native operation completes. Strings round-trip directly via get / set; richer values can use get_json / set_json which add a JSON encode/decode step.

Methods:

Name	Description
get	Return the string stored at key, or None if missing.
set	Persist value under key.
delete	Remove the entry at key if present (no-op otherwise).
all_keys	Return every persisted key (order is platform-dependent).
clear	Remove every entry written through AsyncStorage.
get_json	Return the JSON-decoded value stored at key, or None.
set_json	JSON-encode value and persist it under key.

get async staticmethod

get(key: str) -> Optional[str]

Return the string stored at key, or None if missing.

set async staticmethod

set(key: str, value: str) -> None

Persist value under key.

value must be a str. For non-string values, use set_json.

delete async staticmethod

delete(key: str) -> None

Remove the entry at key if present (no-op otherwise).

all_keys async staticmethod

all_keys() -> List[str]

Return every persisted key (order is platform-dependent).

clear async staticmethod

clear() -> None

Remove every entry written through AsyncStorage.

get_json async staticmethod

get_json(key: str) -> Any

Return the JSON-decoded value stored at key, or None.

If the stored value isn't valid JSON, returns None rather than raising; assume the entry was written by another process or an older version of the app.

set_json async staticmethod

set_json(key: str, value: Any) -> None

JSON-encode value and persist it under key.

use_persisted_state

use_persisted_state(key: str, initial: T) -> Tuple[T, Callable[[Any], None]]

Persisted use_state variant.

Backed by AsyncStorage: behaves like use_state but loads the prior value (if any) on mount and persists every subsequent update. Until the load completes the value is initial, the same fallback React Native users get with AsyncStorage.getItem.

The setter accepts either a value or a current -> new callable, matching use_state. Writes are fire-and-forget; failures are silently absorbed (storage is best-effort by design).

Parameters:

Name	Type	Description	Default
key	str	Storage key. Pass a stable, namespaced string (e.g. "settings.theme").	required
initial	T	Value used before the first load completes.	required

Returns:

Type	Description
T	(value, setter), same shape as
Callable[[Any], None]	use_state.

Example

import pythonnative as pn


@pn.component
def ThemeToggle():
    theme, set_theme = pn.use_persisted_state("settings.theme", "light")
    return pn.Button(
        f"Theme: {theme}",
        on_click=lambda: set_theme("dark" if theme == "light" else "light"),
    )

Patterns

• Token / session storage: write strings with set and read with get.
• Complex values: use set_json / get_json for dicts, lists, and primitives.
• Component state that survives restarts: reach for use_persisted_state instead of manually wiring an effect to AsyncStorage.

Next steps

• The pattern is walked through end-to-end in the Async + data guide.