Allow for App to set bookmark save/restore dir functions

Author: schloerke

shiny/_app.py

@@ -31,8 +31,15 @@
 from ._error import ErrorMiddleware
 from ._shinyenv import is_pyodide
 from ._utils import guess_mime_type, is_async_callable, sort_keys_length
+from .bookmark import _global as bookmark_global_state
+from .bookmark._global import as_bookmark_dir_fn
 from .bookmark._restore_state import RestoreContext, restore_context
-from .bookmark._types import BookmarkStore
+from .bookmark._types import (
+    BookmarkDirFn,
+    BookmarkRestoreDirFn,
+    BookmarkSaveDirFn,
+    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
@@ -109,12 +116,10 @@ def server(input: Inputs, output: Outputs, session: Session):
     ui: RenderedHTML | Callable[[Request], Tag | TagList]
     server: Callable[[Inputs, Outputs, Session], None]
 
+    _bookmark_save_dir_fn: BookmarkSaveDirFn | None
+    _bookmark_restore_dir_fn: BookmarkRestoreDirFn | 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,
@@ -144,7 +149,7 @@ def __init__(
                 "`server` must have 1 (Inputs) or 3 parameters (Inputs, Outputs, Session)"
             )
 
-        self._bookmark_store = bookmark_store
+        self._init_bookmarking(bookmark_store=bookmark_store)
 
         self._debug: bool = debug
 
@@ -369,7 +374,9 @@ async def _on_root_request_cb(self, request: Request) -> Response:
         if self.bookmark_store == "disable":
             restore_ctx = RestoreContext()
         else:
-            restore_ctx = await RestoreContext.from_query_string(request.url.query)
+            restore_ctx = await RestoreContext.from_query_string(
+                request.url.query, app=self
+            )
 
         with restore_context(restore_ctx):
             if callable(self.ui):
@@ -492,6 +499,25 @@ def _render_page_from_file(self, file: Path, lib_prefix: str) -> RenderedHTML:
 
         return rendered
 
+    # ==========================================================================
+    # Bookmarking
+    # ==========================================================================
+
+    def _init_bookmarking(self, *, bookmark_store: BookmarkStore) -> None:
+        self._bookmark_save_dir_fn = bookmark_global_state.bookmark_save_dir
+        self._bookmark_restore_dir_fn = bookmark_global_state.bookmark_restore_dir
+        self._bookmark_store = bookmark_store
+
+    @property
+    def bookmark_store(self) -> BookmarkStore:
+        return self._bookmark_store
+
+    def set_bookmark_save_dir_fn(self, bookmark_save_dir_fn: BookmarkDirFn):
+        self._bookmark_save_dir_fn = as_bookmark_dir_fn(bookmark_save_dir_fn)
+
+    def set_bookmark_restore_dir_fn(self, bookmark_restore_dir_fn: BookmarkDirFn):
+        self._bookmark_restore_dir_fn = as_bookmark_dir_fn(bookmark_restore_dir_fn)
+
 
 def is_uifunc(x: Path | Tag | TagList | Callable[[Request], Tag | TagList]) -> bool:
     if (

shiny/bookmark/__init__.py

@@ -5,7 +5,7 @@
     BookmarkProxy,
 )
 from ._button import input_bookmark_button
-from ._external import set_restore_dir, set_save_dir
+from ._global import set_global_restore_dir_fn, set_global_save_dir_fn
 from ._restore_state import RestoreContext, RestoreState, restore_input
 from ._save_state import BookmarkState
 
@@ -18,8 +18,8 @@
     # _button
     "input_bookmark_button",
     # _external
-    "set_save_dir",
-    "set_restore_dir",
+    "set_global_save_dir_fn",
+    "set_global_restore_dir_fn",
     # _restore_state
     "RestoreContext",
     "RestoreState",

shiny/bookmark/_bookmark.py

@@ -462,7 +462,7 @@ async def root_state_on_save(state: BookmarkState) -> None:
             )
 
             if self.store == "server":
-                query_string = await root_state._save_state()
+                query_string = await root_state._save_state(app=self._session_root.app)
             elif self.store == "url":
                 query_string = await root_state._encode_state()
             # # Can we have browser storage?

shiny/bookmark/_external.py renamed to shiny/bookmark/_global.py

@@ -1,14 +1,14 @@
 from __future__ import annotations
 
-from pathlib import Path
-from typing import Awaitable, Callable, Literal, TypeVar
+from typing import overload
 
 from .._utils import wrap_async
-from ..types import MISSING, MISSING_TYPE
-from ._types import GetBookmarkRestoreDir, GetBookmarkSaveDir
-
-BookmarkStore = Literal["url", "server", "disable"]
-
+from ._types import (
+    BookmarkDirFn,
+    BookmarkDirFnAsync,
+    BookmarkRestoreDirFn,
+    BookmarkSaveDirFn,
+)
 
 # WARNING! This file contains global state!
 # During App initialization, the save_dir and restore_dir functions are conventionally set
@@ -17,40 +17,51 @@
 # The set methods below are used to set the save_dir and restore_dir locations for locations like Connect or SSP.
 # Ex:
 # ```python
-# @shiny.bookmark.set_save_dir
+# @shiny.bookmark.set_global_save_dir_fn
 # def connect_save_shiny_bookmark(id: str) -> Path:
 #     path = Path("connect") / id
 #     path.mkdir(parents=True, exist_ok=True)
 #     return path
-# @shiny.bookmark.set_restore_dir
+# @shiny.bookmark.set_global_restore_dir_fn
 # def connect_restore_shiny_bookmark(id: str) -> Path:
 #     return Path("connect") / id
 # ```
 
 
-_bookmark_save_dir: GetBookmarkSaveDir | MISSING_TYPE = MISSING
-_bookmark_restore_dir: GetBookmarkRestoreDir | MISSING_TYPE = MISSING
+bookmark_save_dir: BookmarkSaveDirFn | None = None
+bookmark_restore_dir: BookmarkRestoreDirFn | None = None
 
 
-GetBookmarkDirT = TypeVar(
-    "GetBookmarkDirT",
-    bound=Callable[[str], Awaitable[Path]] | Callable[[str], Awaitable[Path]],
-)
+@overload
+def as_bookmark_dir_fn(fn: BookmarkDirFn) -> BookmarkDirFnAsync:
+    pass
+
+
+@overload
+def as_bookmark_dir_fn(fn: None) -> None:
+    pass
+
+
+def as_bookmark_dir_fn(fn: BookmarkDirFn | None) -> BookmarkDirFnAsync | None:
+    if fn is None:
+        return None
+    return wrap_async(fn)
+
 
 # TODO: Barret - Integrate Set / Restore for Connect. Ex: Connect https://github.com/posit-dev/connect/blob/8de330aec6a61cf21e160b5081d08a1d3d7e8129/R/connect.R#L915
 
 
-def set_save_dir(fn: GetBookmarkDirT) -> GetBookmarkDirT:
+def set_global_save_dir_fn(fn: BookmarkDirFn):
     """TODO: Barret document"""
-    global _bookmark_save_dir
+    global bookmark_save_dir
 
-    _bookmark_save_dir = wrap_async(fn)
+    bookmark_save_dir = as_bookmark_dir_fn(fn)
     return fn
 
 
-def set_restore_dir(fn: GetBookmarkDirT) -> GetBookmarkDirT:
+def set_global_restore_dir_fn(fn: BookmarkDirFn):
     """TODO: Barret document"""
-    global _bookmark_restore_dir
+    global bookmark_restore_dir
 
-    _bookmark_restore_dir = wrap_async(fn)
+    bookmark_restore_dir = as_bookmark_dir_fn(fn)
     return fn

shiny/bookmark/_restore_state.py

@@ -5,15 +5,15 @@
 from contextlib import contextmanager
 from contextvars import ContextVar, Token
 from pathlib import Path
-from typing import Any, Literal, Optional
+from typing import TYPE_CHECKING, Any, Literal, Optional
 from urllib.parse import parse_qs, parse_qsl
 
-from shiny.types import MISSING_TYPE
-
-from . import _external as bookmark_external
 from ._bookmark_state import local_restore_dir
-from ._types import GetBookmarkRestoreDir
 from ._utils import from_json_str, is_hosted
+from ._types import BookmarkRestoreDirFn
+
+if TYPE_CHECKING:
+    from .._app import App
 
 
 class RestoreState:
@@ -105,7 +105,7 @@ def reset(self) -> None:
         self.dir = None
 
     @staticmethod
-    async def from_query_string(query_string: str) -> "RestoreContext":
+    async def from_query_string(query_string: str, *, app: App) -> "RestoreContext":
         res_ctx = RestoreContext()
 
         if query_string.startswith("?"):
@@ -128,7 +128,7 @@ async def from_query_string(query_string: str) -> "RestoreContext":
                 # ignore other key/value pairs. If not, restore from key/value
                 # pairs in the query string.
                 res_ctx.active = True
-                await res_ctx._load_state_qs(query_string)
+                await res_ctx._load_state_qs(query_string, app=app)
 
             else:
                 # The query string contains the saved keys and values
@@ -178,7 +178,7 @@ def as_state(self) -> RestoreState:
             dir=self.dir,
         )
 
-    async def _load_state_qs(self, query_string: str) -> None:
+    async def _load_state_qs(self, query_string: str, *, app: App) -> None:
         """Given a query string with a _state_id_, load saved state with that ID."""
         values = parse_qs(query_string)
         id = values.get("_state_id_", None)
@@ -188,9 +188,7 @@ async def _load_state_qs(self, query_string: str) -> None:
 
         id = id[0]
 
-        load_bookmark_fn: GetBookmarkRestoreDir | None = None
-        if not isinstance(bookmark_external._bookmark_restore_dir, MISSING_TYPE):
-            load_bookmark_fn = bookmark_external._bookmark_restore_dir
+        load_bookmark_fn: BookmarkRestoreDirFn | None = app._bookmark_restore_dir_fn
 
         if load_bookmark_fn is None:
             if is_hosted():
@@ -207,6 +205,7 @@ async def _load_state_qs(self, query_string: str) -> None:
         if not self.dir.exists():
             raise ValueError("Bookmarked state directory does not exist.")
 
+        # TODO: Barret; Store/restore as JSON
         with open(self.dir / "input.pickle", "rb") as f:
             input_values = pickle.load(f)
         self.input = RestoreInputSet(input_values)

shiny/bookmark/_save_state.py

@@ -7,13 +7,13 @@
 
 from .._utils import private_random_id
 from ..reactive import isolate
-from ..types import MISSING_TYPE
-from . import _external as bookmark_external
 from ._bookmark_state import local_save_dir
-from ._types import GetBookmarkSaveDir
 from ._utils import is_hosted, to_json_str
+from ._types import BookmarkSaveDirFn
 
 if TYPE_CHECKING:
+    from shiny._app import App
+
     from .. import Inputs
 else:
     Inputs = Any
@@ -56,7 +56,7 @@ async def _call_on_save(self):
             with isolate():
                 await self.on_save(self)
 
-    async def _save_state(self) -> str:
+    async def _save_state(self, *, app: App) -> str:
         """
         Save a state to disk (pickle).
 
@@ -72,9 +72,7 @@ async def _save_state(self) -> str:
         # to `self.dir`.
 
         # This will be defined by the hosting environment if it supports bookmarking.
-        save_bookmark_fn: GetBookmarkSaveDir | None = None
-        if not isinstance(bookmark_external._bookmark_save_dir, MISSING_TYPE):
-            save_bookmark_fn = bookmark_external._bookmark_save_dir
+        save_bookmark_fn: BookmarkSaveDirFn | None = app._bookmark_save_dir_fn
 
         if save_bookmark_fn is None:
             if is_hosted():

shiny/bookmark/_types.py

@@ -5,8 +5,12 @@
 
 # Q: Can we merge how bookmark dirs are saved / loaded?... it's the same directory! However, the save will return a possibly new path. Restoring will return an existing path.
 # A: No. Keep them separate. The save function may need to create a new directory, while the load function will always return an existing directory.
-GetBookmarkSaveDir = Callable[[str], Awaitable[Path]]
-GetBookmarkRestoreDir = Callable[[str], Awaitable[Path]]
+
+BookmarkDirFn = Callable[[str], Awaitable[Path]] | Callable[[str], Path]
+BookmarkDirFnAsync = Callable[[str], Awaitable[Path]]
+
+BookmarkSaveDirFn = BookmarkDirFnAsync
+BookmarkRestoreDirFn = BookmarkDirFnAsync
 
 
 BookmarkStore = Literal["url", "server", "disable"]

shiny/session/_session.py

@@ -641,7 +641,8 @@ def verify_state(expected_state: ConnectionState) -> None:
                             if ".clientdata_url_search" in message_obj["data"]:
                                 self.bookmark._restore_context_value = (
                                     await RestoreContext.from_query_string(
-                                        message_obj["data"][".clientdata_url_search"]
+                                        message_obj["data"][".clientdata_url_search"],
+                                        app=self.app,
                                     )
                                 )
                             else:

tests/playwright/shiny/bookmark/dir/.gitignore

@@ -0,0 +1 @@
+bookmarks-*/

tests/playwright/shiny/bookmark/dir/app-attr.py

@@ -0,0 +1,70 @@
+import shutil
+from pathlib import Path
+
+from starlette.requests import Request
+
+from shiny import App, Inputs, Outputs, Session, reactive, render, ui
+from shiny._utils import rand_hex
+
+
+def app_ui(request: Request):
+    return ui.page_fluid(
+        ui.input_radio_buttons("letter", "Choose a letter", choices=["A", "B", "C"]),
+        ui.h3("Has saved:"),
+        ui.output_code("called_saved"),
+        ui.h3("Has restored:"),
+        ui.output_code("called_restored"),
+    )
+
+
+def server(input: Inputs, ouput: Outputs, session: Session):
+
+    @reactive.effect
+    @reactive.event(input.letter, ignore_init=True)
+    async def _():
+        await session.bookmark()
+
+    @session.bookmark.on_bookmarked
+    async def _(url: str):
+        await session.bookmark.update_query_string(url)
+
+    @render.code
+    def called_saved():
+        reactive.invalidate_later(1)
+        return str(did_save)
+
+    @render.code
+    def called_restored():
+        reactive.invalidate_later(1)
+        return str(did_restore)
+
+
+did_save = False
+did_restore = False
+
+bookmark_dir = Path(__file__).parent / f"bookmarks-{rand_hex(8)}"
+bookmark_dir.mkdir(exist_ok=True)
+
+app = App(app_ui, server, bookmark_store="server")
+
+
+app.on_shutdown(lambda: shutil.rmtree(bookmark_dir))
+
+
+def restore_bookmark_dir(id: str) -> Path:
+    global did_restore
+    did_restore = True
+    return bookmark_dir / id
+
+
+def save_bookmark_dir(id: str) -> Path:
+    global did_save
+    did_save = True
+    save_dir = bookmark_dir / id
+    save_dir.mkdir(parents=True, exist_ok=True)
+    return save_dir
+
+
+# Same exact app as `app-global.py`, except we're using `App` functions to set the save and restore directories.
+app.set_bookmark_save_dir_fn(save_bookmark_dir)
+app.set_bookmark_restore_dir_fn(restore_bookmark_dir)