Implement @observe(suspended) and @session.output(suspend_when_hidden, priority) (#50)

Author: cpsievert

shiny/reactive.py

@@ -236,6 +236,7 @@ def __init__(
         self,
         fn: EffectFunction,
         *,
+        suspended: bool = False,
         priority: int = 0,
         session: Union[MISSING_TYPE, "Session", None] = MISSING,
     ) -> None:
@@ -249,6 +250,8 @@ def __init__(
         self._is_async: bool = False
 
         self._priority: int = priority
+        self._suspended = suspended
+        self._on_resume: Callable[[], None] = lambda: None
 
         self._invalidate_callbacks: list[Callable[[], None]] = []
         self._destroyed: bool = False
@@ -286,8 +289,16 @@ def on_invalidate_cb() -> None:
             for cb in self._invalidate_callbacks:
                 cb()
 
-            # TODO: Wrap this stuff up in a continue callback, depending on if suspended?
-            ctx.add_pending_flush(self._priority)
+            if self._destroyed:
+                return
+
+            def _continue() -> None:
+                ctx.add_pending_flush(self._priority)
+
+            if self._suspended:
+                self._on_resume = _continue
+            else:
+                _continue()
 
         async def on_flush_cb() -> None:
             if not self._destroyed:
@@ -325,6 +336,35 @@ def destroy(self) -> None:
         if self._ctx is not None:
             self._ctx.invalidate()
 
+    def suspend(self) -> None:
+        """
+        Causes this observer to stop scheduling flushes (re-executions) in response to
+        invalidations. If the observer was invalidated prior to this call but it has not
+        re-executed yet (because it waits until on_flush is called) then that
+        re-execution will still occur, because the flush is already scheduled.
+        """
+        self._suspended = True
+
+    def resume(self) -> None:
+        """
+        Causes this observer to start re-executing in response to invalidations. If the
+        observer was invalidated while suspended, then it will schedule itself for
+        re-execution (pending flush).
+        """
+        if self._suspended:
+            self._suspended = False
+            self._on_resume()
+            self._on_resume = lambda: None
+
+    def set_priority(self, priority: int = 0) -> None:
+        """
+        Change this observer's priority. Note that if the observer is currently
+        invalidated, then the change in priority will not take effect until the next
+        invalidation--unless the observer is also currently suspended, in which case the
+        priority change will be effective upon resume.
+        """
+        self._priority = priority
+
     def _on_session_ended_cb(self) -> None:
         self.destroy()
 
@@ -334,18 +374,27 @@ def __init__(
         self,
         fn: EffectFunctionAsync,
         *,
+        suspended: bool = False,
         priority: int = 0,
         session: Union[MISSING_TYPE, "Session", None] = MISSING,
     ) -> None:
         if not utils.is_async_callable(fn):
             raise TypeError(self.__class__.__name__ + " requires an async function")
 
-        super().__init__(cast(EffectFunction, fn), session=session, priority=priority)
+        super().__init__(
+            cast(EffectFunction, fn),
+            suspended=suspended,
+            session=session,
+            priority=priority,
+        )
         self._is_async = True
 
 
 def effect(
-    *, priority: int = 0, session: Union[MISSING_TYPE, "Session", None] = MISSING
+    *,
+    suspended: bool = False,
+    priority: int = 0,
+    session: Union[MISSING_TYPE, "Session", None] = MISSING,
 ) -> Callable[[Union[EffectFunction, EffectFunctionAsync]], Effect]:
     """[summary]
 
@@ -360,10 +409,12 @@ def effect(
     def create_effect(fn: Union[EffectFunction, EffectFunctionAsync]) -> Effect:
         if utils.is_async_callable(fn):
             fn = cast(EffectFunctionAsync, fn)
-            return EffectAsync(fn, priority=priority, session=session)
+            return EffectAsync(
+                fn, suspended=suspended, priority=priority, session=session
+            )
         else:
             fn = cast(EffectFunction, fn)
-            return Effect(fn, priority=priority, session=session)
+            return Effect(fn, suspended=suspended, priority=priority, session=session)
 
     return create_effect
 

shiny/session.py

@@ -32,6 +32,7 @@
     Dict,
     List,
     Any,
+    cast,
 )
 from starlette.requests import Request
 
@@ -53,7 +54,7 @@
 
 from htmltools import TagChildArg, TagList
 
-from .reactive import Value, Effect, EffectAsync, isolate
+from .reactive import Value, Effect, effect, isolate
 from .http_staticfiles import FileResponse
 from .connmanager import Connection, ConnectionClosed
 from . import reactcore
@@ -240,6 +241,8 @@ def _manage_inputs(self, data: Dict[str, object]) -> None:
 
             self.input[keys[0]]._set(val)
 
+            self.output.manage_hidden()
+
     # ==========================================================================
     # Message handlers
     # ==========================================================================
@@ -580,11 +583,16 @@ def __delattr__(self, key: str) -> None:
 # ======================================================================================
 class Outputs:
     def __init__(self, session: Session) -> None:
-        self._output_obervers: Dict[str, Effect] = {}
+        self._effects: Dict[str, Effect] = {}
+        self._suspend_when_hidden: Dict[str, bool] = {}
         self._session: Session = session
 
     def __call__(
-        self, *, name: Optional[str] = None
+        self,
+        *,
+        name: Optional[str] = None,
+        suspend_when_hidden: bool = True,
+        priority: int = 0,
     ) -> Callable[[render.RenderFunction], None]:
         def set_fn(fn: render.RenderFunction) -> None:
             fn_name = name or fn.__name__
@@ -594,10 +602,15 @@ def set_fn(fn: render.RenderFunction) -> None:
             if isinstance(fn, render.RenderFunction):
                 fn.set_metadata(self._session, fn_name)
 
-            if fn_name in self._output_obervers:
-                self._output_obervers[fn_name].destroy()
+            if fn_name in self._effects:
+                self._effects[fn_name].destroy()
 
-            @EffectAsync
+            self._suspend_when_hidden[fn_name] = suspend_when_hidden
+
+            @effect(
+                suspended=suspend_when_hidden and self._is_hidden(fn_name),
+                priority=priority,
+            )
             async def output_obs():
                 await self._session.send_message(
                     {"recalculating": {"name": fn_name, "status": "recalculating"}}
@@ -641,12 +654,36 @@ async def output_obs():
                     {"recalculating": {"name": fn_name, "status": "recalculated"}}
                 )
 
-            self._output_obervers[fn_name] = output_obs
+            self._effects[fn_name] = output_obs
 
             return None
 
         return set_fn
 
+    def manage_hidden(self) -> None:
+        "Suspends execution of hidden outputs and resumes execution of visible outputs."
+        output_names = list(self._suspend_when_hidden.keys())
+        for name in output_names:
+            if self._should_suspend(name):
+                self._effects[name].suspend()
+            else:
+                self._effects[name].resume()
+
+    def _should_suspend(self, name: str) -> bool:
+        return self._suspend_when_hidden[name] and self._is_hidden(name)
+
+    def _is_hidden(self, name: str) -> bool:
+        with isolate():
+            hidden = cast(
+                Optional[bool],
+                self._session.input[f".clientdata_output_{name}_hidden"](),
+            )
+
+        if hidden is None:
+            return True
+        else:
+            return hidden
+
 
 # ==============================================================================
 # Context manager for current session (AKA current reactive domain)

shiny/shinymodule.py

@@ -59,12 +59,19 @@ def _ns_key(self, key: str) -> str:
         return self._ns + "-" + key
 
     def __call__(
-        self, *, name: Optional[str] = None
+        self,
+        *,
+        name: Optional[str] = None,
+        suspend_when_hidden: bool = True,
+        priority: int = 0
     ) -> Callable[[RenderFunction], None]:
         def set_fn(fn: RenderFunction) -> None:
             fn_name = name or fn.__name__
             fn_name = self._ns_key(fn_name)
-            return self._outputs(name=fn_name)(fn)
+            out_fn = self._outputs(
+                name=fn_name, suspend_when_hidden=suspend_when_hidden, priority=priority
+            )
+            return out_fn(fn)
 
         return set_fn