Add docs; Rename ShinySaveState -> BookmarkState

Author: schloerke

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

@@ -31,11 +31,7 @@
 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,
-    get_current_restore_context,
-    restore_context,
-)
+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

shiny/bookmark/__init__.py

@@ -3,15 +3,14 @@
     BookmarkApp,
     BookmarkExpressStub,
     BookmarkProxy,
-    ShinySaveState,
 )
 from ._button import input_bookmark_button
 from ._external import set_restore_dir, set_save_dir
-from ._restore_state import RestoreContext, RestoreContextState, restore_input
+from ._restore_state import RestoreContext, RestoreState, restore_input
+from ._save_state import BookmarkState
 
 __all__ = (
     # _bookmark
-    "ShinySaveState",
     "Bookmark",
     "BookmarkApp",
     "BookmarkProxy",
@@ -23,6 +22,8 @@
     "set_restore_dir",
     # _restore_state
     "RestoreContext",
-    "RestoreContextState",
+    "RestoreState",
     "restore_input",
+    # _save_state
+    "BookmarkState",
 )

shiny/bookmark/_bookmark.py

@@ -8,8 +8,8 @@
 from .._utils import AsyncCallbacks, CancelCallback, wrap_async
 from ..types import MISSING, MISSING_TYPE
 from ._button import BOOKMARK_ID
-from ._restore_state import RestoreContextState
-from ._save_state import ShinySaveState
+from ._restore_state import RestoreState
+from ._save_state import BookmarkState
 from ._types import BookmarkStore
 
 # TODO: Barret - Bookmark state
@@ -192,8 +192,7 @@ def _get_bookmark_exclude(self) -> list[str]:
     def on_bookmark(
         self,
         callback: (
-            Callable[[ShinySaveState], None]
-            | Callable[[ShinySaveState], Awaitable[None]]
+            Callable[[BookmarkState], None] | Callable[[BookmarkState], Awaitable[None]]
         ),
         /,
     ) -> CancelCallback:
@@ -266,8 +265,7 @@ async def do_bookmark(self) -> None:
     def on_restore(
         self,
         callback: (
-            Callable[[RestoreContextState], None]
-            | Callable[[RestoreContextState], Awaitable[None]]
+            Callable[[RestoreState], None] | Callable[[RestoreState], Awaitable[None]]
         ),
     ) -> CancelCallback:
         """
@@ -281,8 +279,7 @@ def on_restore(
     def on_restored(
         self,
         callback: (
-            Callable[[RestoreContextState], None]
-            | Callable[[RestoreContextState], Awaitable[None]]
+            Callable[[RestoreState], None] | Callable[[RestoreState], Awaitable[None]]
         ),
     ) -> CancelCallback:
         """
@@ -402,8 +399,7 @@ def _get_bookmark_exclude(self) -> list[str]:
     def on_bookmark(
         self,
         callback: (
-            Callable[[ShinySaveState], None]
-            | Callable[[ShinySaveState], Awaitable[None]]
+            Callable[[BookmarkState], None] | Callable[[BookmarkState], Awaitable[None]]
         ),
         /,
     ) -> CancelCallback:
@@ -419,17 +415,15 @@ def on_bookmarked(
     def on_restore(
         self,
         callback: (
-            Callable[[RestoreContextState], None]
-            | Callable[[RestoreContextState], Awaitable[None]]
+            Callable[[RestoreState], None] | Callable[[RestoreState], Awaitable[None]]
         ),
     ) -> CancelCallback:
         return self._on_restore_callbacks.register(wrap_async(callback))
 
     def on_restored(
         self,
         callback: (
-            Callable[[RestoreContextState], None]
-            | Callable[[RestoreContextState], Awaitable[None]]
+            Callable[[RestoreState], None] | Callable[[RestoreState], Awaitable[None]]
         ),
     ) -> CancelCallback:
         return self._on_restored_callbacks.register(wrap_async(callback))
@@ -457,14 +451,14 @@ async def do_bookmark(self) -> None:
 
         try:
             # ?withLogErrors
-            from ..bookmark._bookmark import ShinySaveState
+            from ..bookmark._bookmark import BookmarkState
             from ..session import session_context
 
-            async def root_state_on_save(state: ShinySaveState) -> None:
+            async def root_state_on_save(state: BookmarkState) -> None:
                 with session_context(self._session_root):
                     await self._on_bookmark_callbacks.invoke(state)
 
-            root_state = ShinySaveState(
+            root_state = BookmarkState(
                 input=self._session_root.input,
                 exclude=self._get_bookmark_exclude(),
                 on_save=root_state_on_save,
@@ -541,7 +535,7 @@ def __init__(self, session_proxy: SessionProxy):
         # The goal of this method is to save the scope's values. All namespaced inputs
         # will already exist within the `root_state`.
         @self._root_bookmark.on_bookmark
-        async def scoped_on_bookmark(root_state: ShinySaveState) -> None:
+        async def scoped_on_bookmark(root_state: BookmarkState) -> None:
             return await self._scoped_on_bookmark(root_state)
 
         from ..session import session_context
@@ -557,7 +551,7 @@ async def scoped_on_bookmarked(url: str) -> None:
         ns_prefix = str(self._ns + self._ns._sep)
 
         @self._root_bookmark.on_restore
-        async def scoped_on_restore(restore_state: RestoreContextState) -> None:
+        async def scoped_on_restore(restore_state: RestoreState) -> None:
             if self._on_restore_callbacks.count() == 0:
                 return
 
@@ -567,22 +561,22 @@ async def scoped_on_restore(restore_state: RestoreContextState) -> None:
                 await self._on_restore_callbacks.invoke(scoped_restore_state)
 
         @self._root_bookmark.on_restored
-        async def scoped_on_restored(restore_state: RestoreContextState) -> None:
+        async def scoped_on_restored(restore_state: RestoreState) -> None:
             if self._on_restored_callbacks.count() == 0:
                 return
 
             scoped_restore_state = restore_state._state_within_namespace(ns_prefix)
             with session_context(self._session_proxy):
                 await self._on_restored_callbacks.invoke(scoped_restore_state)
 
-    async def _scoped_on_bookmark(self, root_state: ShinySaveState) -> None:
+    async def _scoped_on_bookmark(self, root_state: BookmarkState) -> None:
         # Exit if no user-defined callbacks.
         if self._on_bookmark_callbacks.count() == 0:
             return
 
-        from ..bookmark._bookmark import ShinySaveState
+        from ..bookmark._bookmark import BookmarkState
 
-        scoped_state = ShinySaveState(
+        scoped_state = BookmarkState(
             input=self._session_root.input,
             exclude=self._root_bookmark.exclude,
             on_save=None,
@@ -621,8 +615,7 @@ def _create_effects(self) -> NoReturn:
     def on_bookmark(
         self,
         callback: (
-            Callable[[ShinySaveState], None]
-            | Callable[[ShinySaveState], Awaitable[None]]
+            Callable[[BookmarkState], None] | Callable[[BookmarkState], Awaitable[None]]
         ),
         /,
     ) -> CancelCallback:
@@ -658,17 +651,15 @@ def store(self) -> BookmarkStore:
     def on_restore(
         self,
         callback: (
-            Callable[[RestoreContextState], None]
-            | Callable[[RestoreContextState], Awaitable[None]]
+            Callable[[RestoreState], None] | Callable[[RestoreState], Awaitable[None]]
         ),
     ) -> CancelCallback:
         return self._on_restore_callbacks.register(wrap_async(callback))
 
     def on_restored(
         self,
         callback: (
-            Callable[[RestoreContextState], None]
-            | Callable[[RestoreContextState], Awaitable[None]]
+            Callable[[RestoreState], None] | Callable[[RestoreState], Awaitable[None]]
         ),
     ) -> CancelCallback:
         return self._on_restored_callbacks.register(wrap_async(callback))
@@ -697,8 +688,7 @@ def _get_bookmark_exclude(self) -> NoReturn:
     def on_bookmark(
         self,
         callback: (
-            Callable[[ShinySaveState], None]
-            | Callable[[ShinySaveState], Awaitable[None]]
+            Callable[[BookmarkState], None] | Callable[[BookmarkState], Awaitable[None]]
         ),
     ) -> NoReturn:
         raise NotImplementedError(
@@ -728,8 +718,7 @@ async def do_bookmark(self) -> NoReturn:
     def on_restore(
         self,
         callback: (
-            Callable[[RestoreContextState], None]
-            | Callable[[RestoreContextState], Awaitable[None]]
+            Callable[[RestoreState], None] | Callable[[RestoreState], Awaitable[None]]
         ),
     ) -> NoReturn:
         raise NotImplementedError(
@@ -739,8 +728,7 @@ def on_restore(
     def on_restored(
         self,
         callback: (
-            Callable[[RestoreContextState], None]
-            | Callable[[RestoreContextState], Awaitable[None]]
+            Callable[[RestoreState], None] | Callable[[RestoreState], Awaitable[None]]
         ),
     ) -> NoReturn:
         raise NotImplementedError(

shiny/bookmark/_button.py

@@ -9,70 +9,50 @@
 BOOKMARK_ID = "._bookmark_"
 
 
-# ' Create a button for bookmarking/sharing
-# '
-# ' A `bookmarkButton` is a [actionButton()] with a default label
-# ' that consists of a link icon and the text "Bookmark...". It is meant to be
-# ' used for bookmarking state.
-# '
-# ' @inheritParams actionButton
-# ' @param title A tooltip that is shown when the mouse cursor hovers over the
-# '   button.
-# ' @param id An ID for the bookmark button. The only time it is necessary to set
-# '   the ID unless you have more than one bookmark button in your application.
-# '   If you specify an input ID, it should be excluded from bookmarking with
-# '   [setBookmarkExclude()], and you must create an observer that
-# '   does the bookmarking when the button is pressed. See the examples below.
-# '
-# ' @seealso [enableBookmarking()] for more examples.
-# '
-# ' @examples
-# ' ## Only run these examples in interactive sessions
-# ' if (interactive()) {
-# '
-# ' # This example shows how to use multiple bookmark buttons. If you only need
-# ' # a single bookmark button, see examples in ?enableBookmarking.
-# ' ui <- function(request) {
-# '   fluidPage(
-# '     tabsetPanel(id = "tabs",
-# '       tabPanel("One",
-# '         checkboxInput("chk1", "Checkbox 1"),
-# '         bookmarkButton(id = "bookmark1")
-# '       ),
-# '       tabPanel("Two",
-# '         checkboxInput("chk2", "Checkbox 2"),
-# '         bookmarkButton(id = "bookmark2")
-# '       )
-# '     )
-# '   )
-# ' }
-# ' server <- function(input, output, session) {
-# '   # Need to exclude the buttons from themselves being bookmarked
-# '   setBookmarkExclude(c("bookmark1", "bookmark2"))
-# '
-# '   # Trigger bookmarking with either button
-# '   observeEvent(input$bookmark1, {
-# '     session$doBookmark()
-# '   })
-# '   observeEvent(input$bookmark2, {
-# '     session$doBookmark()
-# '   })
-# ' }
-# ' enableBookmarking(store = "url")
-# ' shinyApp(ui, server)
-# ' }
-# ' @export
 def input_bookmark_button(
     label: TagChild = "Bookmark...",
     *,
     icon: TagChild | MISSING_TYPE = MISSING,
     width: Optional[str] = None,
     disabled: bool = False,
-    # id: str = "._bookmark_",
+    id: str = BOOKMARK_ID,
     title: str = "Bookmark this application's state and get a URL for sharing.",
     **kwargs: TagAttrValue,
 ) -> Tag:
-    resolved_id = resolve_id(BOOKMARK_ID)
+    """
+    Button for bookmarking/sharing.
+
+    A `bookmarkButton` is a [input_action_button()] with a default label that consists of a link icon and the text "Bookmark...". It is meant to be used for bookmarking state.
+
+    Parameters
+    ----------
+    label
+        The button label.
+    icon
+        The icon to display on the button.
+    width
+        The CSS width, e.g. '400px', or '100%'.
+    disabled
+        Whether the button is disabled.
+    id
+        An ID for the bookmark button. The only time it is necessary to set the ID unless you have more than one bookmark button in your application. If you specify an input ID, it should be excluded from bookmarking with `session.bookmark.exclude.append(ID)`, and you must create a reactive effect that performs the bookmarking (`session.bookmark()`) when the button is pressed.
+    title
+        A tooltip that is shown when the mouse cursor hovers over the button.
+    kwargs
+        Additional attributes for the button.
+
+    Returns
+    -------
+    :
+        A UI element.
+
+    See Also
+    --------
+    * :func:`~shiny.ui.input_action_button`
+    * :func:`~shiny.ui.input_action_link`
+    * :func:`~shiny.reactive.event`
+    """
+    resolved_id = resolve_id(id)
     if isinstance(icon, MISSING_TYPE):
         icon = HTML("&#x1F517;")