Provide app.storage.client as a location to store volatile data which only matters for the current connection

nicegui/client.py

@@ -15,11 +15,13 @@
 
 from . import background_tasks, binding, core, helpers, json
 from .awaitable_response import AwaitableResponse
+from .context import get_client
 from .dependencies import generate_resources
 from .element import Element
 from .favicon import get_favicon_url
 from .javascript_request import JavaScriptRequest
 from .logging import log
+from .observables import ObservableDict
 from .outbox import Outbox
 from .version import __version__
 
@@ -72,6 +74,7 @@ def __init__(self, page: page, *, shared: bool = False) -> None:
         self._body_html = ''
 
         self.page = page
+        self.state = ObservableDict()
 
         self.connect_handlers: List[Union[Callable[..., Any], Awaitable]] = []
         self.disconnect_handlers: List[Union[Callable[..., Any], Awaitable]] = []
@@ -83,6 +86,11 @@ def is_auto_index_client(self) -> bool:
         """Return True if this client is the auto-index client."""
         return self is self.auto_index_client
 
+    @staticmethod
+    def current_client() -> Optional[Client]:
+        """Returns the current client if obtainable from the current context."""
+        return get_client()
+
     @property
     def ip(self) -> Optional[str]:
         """Return the IP address of the client, or None if the client is not connected."""

nicegui/storage.py

@@ -13,7 +13,9 @@
 from starlette.responses import Response
 
 from . import background_tasks, context, core, json, observables
+from .context import get_slot_stack
 from .logging import log
+from .observables import ObservableDict
 
 request_contextvar: contextvars.ContextVar[Optional[Request]] = contextvars.ContextVar('request_var', default=None)
 
@@ -149,10 +151,26 @@ def general(self) -> Dict:
         """General storage shared between all users that is persisted on the server (where NiceGUI is executed)."""
         return self._general
 
+    @property
+    def client(self) -> ObservableDict:
+        """Client storage that is persisted on the server (where NiceGUI is executed) on a per client
+        connection basis.
+
+        The data is lost when the client disconnects through reloading the page, closing the tab or
+        navigating away from the page. It can be used to store data that is only relevant for the current view such
+        as filter settings on a dashboard or in-page navigation. As the data is not persisted it also allows the
+        storage of data structures such as database connections, pandas tables, numpy arrays, user specific ML models
+        or other living objects that are not serializable to JSON.
+        """
+        client = context.get_client()
+        return client.state
+
     def clear(self) -> None:
         """Clears all storage."""
         self._general.clear()
         self._users.clear()
+        if get_slot_stack():
+            self.client.clear()
         for filepath in self.path.glob('storage-*.json'):
             filepath.unlink()
 

tests/test_client_state.py

@@ -0,0 +1,23 @@
+from nicegui import ui, app
+from nicegui.testing import Screen
+
+
+def test_session_state(screen: Screen):
+    app.storage.client['counter'] = 123
+
+    def increment():
+        app.storage.client['counter'] = app.storage.client['counter'] + 1
+
+    ui.button('Increment').on_click(increment)
+    ui.label().bind_text(app.storage.client, 'counter')
+
+    screen.open('/')
+    screen.should_contain('123')
+    screen.click('Increment')
+    screen.wait_for('124')
+
+
+def test_clear(screen: Screen):
+    app.storage.client['counter'] = 123
+    app.storage.client.clear()
+    assert 'counter' not in app.storage.client