feat: Add support for bookmarking via shiny.bookmark

.gitignore

@@ -115,6 +115,7 @@ docs/source/reference/
 _dev/
 tests/playwright/deploys/**/requirements.txt
 test-results/
+shiny_bookmarks/
 
 # setuptools_scm
 shiny/_version.py

docs/_quartodoc-core.yml

@@ -98,6 +98,24 @@ quartodoc:
         - ui.input_file
         - ui.download_button
         - ui.download_link
+    - title: Bookmarking
+      desc: Saving and restoring app state
+      contents:
+        - ui.input_bookmark_button
+        - bookmark.restore_input
+        - bookmark.Bookmark
+        - session.Session.bookmark.exclude
+        - bookmark.BookmarkState
+        - bookmark.RestoreState
+        - kind: page
+          path: bookmark_integration
+          summary:
+            name: "Integration"
+            desc: "Decorators to set save and restore directories."
+          flatten: true
+          contents:
+            - bookmark.set_save_dir
+            - bookmark.set_restore_dir
     - title: Chat interface
       desc: Build a chatbot interface
       contents:

shiny/_app.py

@@ -3,10 +3,11 @@
 import copy
 import os
 import secrets
+import warnings
 from contextlib import AsyncExitStack, asynccontextmanager
 from inspect import signature
 from pathlib import Path
-from typing import Any, Callable, Mapping, Optional, TypeVar, cast
+from typing import Any, Callable, Literal, Mapping, Optional, TypeVar, cast
 
 import starlette.applications
 import starlette.exceptions
@@ -30,6 +31,8 @@
 from ._error import ErrorMiddleware
 from ._shinyenv import is_pyodide
 from ._utils import guess_mime_type, is_async_callable, sort_keys_length
+from .bookmark._restore_state import RestoreContext, restore_context
+from .bookmark._types import BookmarkStore
 from .html_dependencies import jquery_deps, require_deps, shiny_deps
 from .http_staticfiles import FileResponse, StaticFiles
 from .session._session import AppSession, Inputs, Outputs, Session, session_context
@@ -106,6 +109,12 @@ def server(input: Inputs, output: Outputs, session: Session):
     ui: RenderedHTML | Callable[[Request], Tag | TagList]
     server: Callable[[Inputs, Outputs, Session], None]
 
+    _bookmark_store: BookmarkStore
+
+    @property
+    def bookmark_store(self) -> BookmarkStore:
+        return self._bookmark_store
+
     def __init__(
         self,
         ui: Tag | TagList | Callable[[Request], Tag | TagList] | Path,
@@ -114,6 +123,8 @@ def __init__(
         ),
         *,
         static_assets: Optional[str | Path | Mapping[str, str | Path]] = None,
+        # Document type as Literal to have clearer type hints to App author
+        bookmark_store: Literal["url", "server", "disable"] = "disable",
         debug: bool = False,
     ) -> None:
         # Used to store callbacks to be called when the app is shutting down (according
@@ -133,6 +144,8 @@ def __init__(
                 "`server` must have 1 (Inputs) or 3 parameters (Inputs, Outputs, Session)"
             )
 
+        self._bookmark_store = bookmark_store
+
         self._debug: bool = debug
 
         # Settings that the user can change after creating the App object.
@@ -167,7 +180,7 @@ def __init__(
 
         self._sessions: dict[str, AppSession] = {}
 
-        self._sessions_needing_flush: dict[int, AppSession] = {}
+        # self._sessions_needing_flush: dict[int, AppSession] = {}
 
         self._registered_dependencies: dict[str, HTMLDependency] = {}
         self._dependency_handler = starlette.routing.Router()
@@ -353,11 +366,24 @@ async def _on_root_request_cb(self, request: Request) -> Response:
         request for / occurs.
         """
         ui: RenderedHTML
-        if callable(self.ui):
-            ui = self._render_page(self.ui(request), self.lib_prefix)
+        if self.bookmark_store == "disable":
+            restore_ctx = RestoreContext()
         else:
-            ui = self.ui
-        return HTMLResponse(content=ui["html"])
+            restore_ctx = await RestoreContext.from_query_string(request.url.query)
+
+        with restore_context(restore_ctx):
+            if callable(self.ui):
+                ui = self._render_page(self.ui(request), self.lib_prefix)
+            else:
+                if restore_ctx.active:
+                    # TODO: Barret - Docs: See ?enableBookmarking
+                    warnings.warn(
+                        "Trying to restore saved app state, but UI code must be a function for this to work!",
+                        stacklevel=1,
+                    )
+
+                ui = self.ui
+            return HTMLResponse(content=ui["html"])
 
     async def _on_connect_cb(self, ws: starlette.websockets.WebSocket) -> None:
         """

shiny/_main_create.py

@@ -775,8 +775,7 @@ def copy_template_files(
         )
         sys.exit(1)
 
-    if not dest_dir.exists():
-        dest_dir.mkdir()
+    dest_dir.mkdir(parents=True, exist_ok=True)
 
     for item in template.path.iterdir():
         if item.is_file():

shiny/_namespaces.py

@@ -7,6 +7,8 @@
 
 
 class ResolvedId(str):
+    _sep: str = "-"  # Shared object for all instances
+
     def __call__(self, id: Id) -> ResolvedId:
         if isinstance(id, ResolvedId):
             return id
@@ -16,7 +18,7 @@ def __call__(self, id: Id) -> ResolvedId:
         if self == "":
             return ResolvedId(id)
         else:
-            return ResolvedId(self + "-" + id)
+            return ResolvedId(str(self) + self._sep + id)
 
 
 Root: ResolvedId = ResolvedId("")

shiny/_utils.py

@@ -281,7 +281,7 @@ async def fn_async(*args: P.args, **kwargs: P.kwargs) -> R:
     return fn_async
 
 
-# # TODO-barret-future; Q: Keep code?
+# # TODO: Barret - Future: Q: Keep code?
 # class WrapAsync(Generic[P, R]):
 #     """
 #     Make a function asynchronous.
@@ -517,11 +517,11 @@ async def __anext__(self):
 # ==============================================================================
 class Callbacks:
     def __init__(self) -> None:
-        self._callbacks: dict[int, tuple[Callable[[], None], bool]] = {}
+        self._callbacks: dict[int, tuple[Callable[..., None], bool]] = {}
         self._id: int = 0
 
     def register(
-        self, fn: Callable[[], None], once: bool = False
+        self, fn: Callable[..., None], once: bool = False
     ) -> Callable[[], None]:
         self._id += 1
         id = self._id
@@ -533,14 +533,14 @@ def _():
 
         return _
 
-    def invoke(self) -> None:
+    def invoke(self, *args: Any, **kwargs: Any) -> None:
         # The list() wrapper is necessary to force collection of all the items before
         # iteration begins. This is necessary because self._callbacks may be mutated
         # by callbacks.
         for id, value in list(self._callbacks.items()):
             fn, once = value
             try:
-                fn()
+                fn(*args, **kwargs)
             finally:
                 if once:
                     if id in self._callbacks:
@@ -550,32 +550,35 @@ def count(self) -> int:
         return len(self._callbacks)
 
 
+CancelCallback = Callable[[], None]
+
+
 class AsyncCallbacks:
     def __init__(self) -> None:
-        self._callbacks: dict[int, tuple[Callable[[], Awaitable[None]], bool]] = {}
+        self._callbacks: dict[int, tuple[Callable[..., Awaitable[None]], bool]] = {}
         self._id: int = 0
 
     def register(
-        self, fn: Callable[[], Awaitable[None]], once: bool = False
-    ) -> Callable[[], None]:
+        self, fn: Callable[..., Awaitable[None]], once: bool = False
+    ) -> CancelCallback:
         self._id += 1
         id = self._id
         self._callbacks[id] = (fn, once)
 
-        def _():
+        def cancel_callback():
             if id in self._callbacks:
                 del self._callbacks[id]
 
-        return _
+        return cancel_callback
 
-    async def invoke(self) -> None:
+    async def invoke(self, *args: Any, **kwargs: Any) -> None:
         # The list() wrapper is necessary to force collection of all the items before
         # iteration begins. This is necessary because self._callbacks may be mutated
         # by callbacks.
         for id, value in list(self._callbacks.items()):
             fn, once = value
             try:
-                await fn()
+                await fn(*args, **kwargs)
             finally:
                 if once:
                     if id in self._callbacks:

shiny/bookmark/__init__.py

@@ -0,0 +1,29 @@
+from ._bookmark import (
+    Bookmark,
+    BookmarkApp,
+    BookmarkExpressStub,
+    BookmarkProxy,
+)
+from ._button import input_bookmark_button
+from ._external import set_restore_dir, set_save_dir
+from ._restore_state import RestoreContext, RestoreState, restore_input
+from ._save_state import BookmarkState
+
+__all__ = (
+    # _bookmark
+    "Bookmark",
+    "BookmarkApp",
+    "BookmarkProxy",
+    "BookmarkExpressStub",
+    # _button
+    "input_bookmark_button",
+    # _external
+    "set_save_dir",
+    "set_restore_dir",
+    # _restore_state
+    "RestoreContext",
+    "RestoreState",
+    "restore_input",
+    # _save_state
+    "BookmarkState",
+)