When serializing inputs for bookmark, pass in single object for future param expansion

Author: schloerke

shiny/bookmark/__init__.py

@@ -8,6 +8,7 @@
 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
+from ._serializers import Unserializable, serializer_unserializable, SerializeInputInfo
 
 __all__ = (
     # _bookmark
@@ -26,4 +27,8 @@
     "restore_input",
     # _save_state
     "BookmarkState",
+    # _serializers
+    "SerializeInputInfo",
+    "Unserializable",
+    "serializer_unserializable",
 )

shiny/bookmark/_serializers.py

@@ -6,46 +6,49 @@
 
 from typing_extensions import TypeIs
 
+T = TypeVar("T")
+
 
 class Unserializable: ...
 
 
-T = TypeVar("T")
+class SerializeInputInfo:
+    value: Any
+    state_dir: Path | None
+
+    def __init__(self, *, value: Any, state_dir: Path | None):
+        self.value = value
+        self.state_dir = state_dir
 
 
 def is_unserializable(x: Any) -> TypeIs[Unserializable]:
     return isinstance(x, Unserializable)
 
 
-async def serializer_unserializable(
-    value: Any = None, state_dir: Path | None = None
-) -> Unserializable:
+async def serializer_unserializable(info: SerializeInputInfo) -> Unserializable:
     return Unserializable()
 
 
-async def serializer_default(value: T, state_dir: Path | None) -> T:
-    return value
+async def serializer_default(info: SerializeInputInfo) -> Any:
+    return info.value
 
 
 # TODO: Barret - Integrate
-def serializer_file_input(
-    value: Any,
-    state_dir: Path | None,
-) -> Any | Unserializable:
-    if state_dir is None:
+def serializer_file_input(info: SerializeInputInfo) -> Any | Unserializable:
+    if info.state_dir is None:
         return Unserializable()
 
     # TODO: Barret - Double check this logic!
 
     # `value` is a data frame. When persisting files, we need to copy the file to
     # the persistent dir and then strip the original path before saving.
-    datapath = Path(value["datapath"])
-    new_paths = state_dir / datapath.name
+    datapath = Path(info.value["datapath"])
+    new_paths = info.state_dir / datapath.name
 
     if new_paths.exists():
         new_paths.unlink()
     copyfile(datapath, new_paths)
 
-    value["datapath"] = new_paths.name
+    info.value["datapath"] = new_paths.name
 
-    return value
+    return info.value

shiny/session/_session.py

@@ -43,7 +43,7 @@
 from .._namespaces import Id, Root
 from .._typing_extensions import NotRequired, TypedDict
 from .._utils import wrap_async
-from ..bookmark import BookmarkApp, BookmarkProxy
+from ..bookmark import BookmarkApp, BookmarkProxy, SerializeInputInfo
 from ..bookmark._button import BOOKMARK_ID
 from ..bookmark._restore_state import RestoreContext
 from ..http_staticfiles import FileResponse
@@ -1354,7 +1354,7 @@ class Inputs:
     _serializers: dict[
         str,
         Callable[
-            [Any, Path | None],
+            [SerializeInputInfo],
             Awaitable[Any | Unserializable],
         ],
     ]
@@ -1424,14 +1424,8 @@ def set_serializer(
         self,
         id: str,
         fn: (
-            Callable[
-                [Any, Path | None],
-                Awaitable[Any | Unserializable],
-            ]
-            | Callable[
-                [Any, Path | None],
-                Any | Unserializable,
-            ]
+            Callable[[SerializeInputInfo], Awaitable[Any | Unserializable]]
+            | Callable[[SerializeInputInfo], Any | Unserializable]
         ),
     ) -> None:
         """
@@ -1442,9 +1436,44 @@ def set_serializer(
         id
             The ID of the input value.
         fn
-            A function that takes the input value and returns a modified value. The
-            returned value will be used for test snapshots and bookmarking.
+            A function that takes the input value information: an object containing
+            `value` and `state_dir`. The function should return a JSON serializable
+            value. During execution, the function may save information to disk using the
+            `.state_dir` attribute. The returned value will be used for bookmarking.
+
+        Examples
+        --------
+
+        When setting an input, you can add a suffix to the name: e.g. `"x:shiny.date"`
+        or `"y:shiny.password"`. This will cause the name to go through the appropriate
+        input handler, e.g. `"shiny.date"`.
+
+        A good use for this implementation is to set the bookmark serializer for this
+        object. An example for inputs handled by `"shiny.password"` is given below where
+        the bookmark serializer is set to always ignore this value.
+
+        ```python
+        @shiny.input_handlers.add("shiny.password")
+        def _(value: str, name: ResolvedId, session: Session) -> str:
+            # Never bookmark passwords
+            session.input.set_serializer(name, serializer_unserializable)
+
+            return value
+        ```
+
+        ```python
+        def serializer_capitalize(info: SerializeInputInfo) -> str:
+            return info.value.upper()
+
+        @shiny.input_handlers.add("capitalize")
+        def _(value: str, name: ResolvedId, session: Session) -> str:
+            # Capitalize the value before bookmarking
+            session.input.set_serializer(name, serializer_capitalize)
+
+            return value
+        ```
         """
+        # test snapshots and
         self._serializers[id] = wrap_async(fn)
 
     async def _serialize(
@@ -1476,7 +1505,8 @@ async def _serialize(
 
                 # Possibly apply custom serialization given the input id
                 serializer = self._serializers.get(key, serializer_default)
-                serialized_value = await serializer(val, state_dir)
+                serializer_info = SerializeInputInfo(value=val, state_dir=state_dir)
+                serialized_value = await serializer(serializer_info)
 
                 # Filter out any values that were marked as unserializable.
                 if isinstance(serialized_value, Unserializable):