Rename suspend_display() to hide()

Author: wch

shiny/express/__init__.py

@@ -8,8 +8,9 @@
 from ._is_express import is_express_app
 from ._output import (  # noqa: F401
     ui_kwargs,
-    suspend_display,
+    hide,
     output_args,  # pyright: ignore[reportUnusedImport]
+    suspend_display,  # pyright: ignore[reportUnusedImport] - Deprecated
 )
 from ._run import wrap_express_app
 from .display_decorator import display_body
@@ -20,7 +21,7 @@
     "session",
     "is_express_app",
     "ui_kwargs",
-    "suspend_display",
+    "hide",
     "wrap_express_app",
     "ui",
     "display_body",

shiny/express/_output.py

@@ -6,13 +6,15 @@
 from typing import Callable, Generator, TypeVar, overload
 
 from .. import ui
+from .._deprecated import warn_deprecated
 from .._typing_extensions import ParamSpec
 from ..render.renderer import RendererBase, RendererBaseT
 from ..render.transformer import OutputRenderer
 from ..render.transformer._transformer import OT
 
 __all__ = (
     "ui_kwargs",
+    "hide",
     "suspend_display",
 )
 
@@ -98,29 +100,29 @@ def wrapper(renderer: OutputRenderer[OT]) -> OutputRenderer[OT]:
 
 
 @overload
-def suspend_display(fn: CallableT) -> CallableT:
+def hide(fn: CallableT) -> CallableT:
     ...
 
 
 @overload
-def suspend_display(fn: RendererBaseT) -> RendererBaseT:
+def hide(fn: RendererBaseT) -> RendererBaseT:
     ...
 
 
 @overload
-def suspend_display() -> AbstractContextManager[None]:
+def hide() -> AbstractContextManager[None]:
     ...
 
 
-def suspend_display(
+def hide(
     fn: Callable[P, R] | RendererBaseT | None = None
 ) -> Callable[P, R] | RendererBaseT | AbstractContextManager[None]:
-    """Suppresses the display of UI elements in various ways.
+    """Prevent the display of UI elements in various ways.
 
-    If used as a context manager (`with suspend_display():`), it suppresses the display
-    of all UI elements within the context block. (This is useful when you want to
-    temporarily suppress the display of a large number of UI elements, or when you want
-    to suppress the display of UI elements that are not directly under your control.)
+    If used as a context manager (`with hide():`), it prevents the display of all UI
+    elements within the context block. (This is useful when you want to temporarily
+    prevent the display of a large number of UI elements, or when you want to prevent
+    the display of UI elements that are not directly under your control.)
 
     If used as a decorator (without parentheses) on a Shiny rendering function, it
     prevents that function from automatically outputting itself at the point of its
@@ -134,19 +136,19 @@ def suspend_display(
     Parameters
     ----------
     fn
-        The function to decorate. If `None`, returns a context manager that suppresses
-        the display of UI elements within the context block.
+        The function to decorate. If `None`, returns a context manager that prevents the
+        display of UI elements within the context block.
 
     Returns
     -------
     :
-        If `fn` is `None`, returns a context manager that suppresses the display of UI
+        If `fn` is `None`, returns a context manager that prevents the display of UI
         elements within the context block. Otherwise, returns a decorated version of
         `fn`.
     """
 
     if fn is None:
-        return suspend_display_ctxmgr()
+        return hide_ctxmgr()
 
     # Special case for RendererBase; when we decorate those, we just mean "don't
     # display yourself"
@@ -155,11 +157,21 @@ def suspend_display(
         fn.default_ui = null_ui
         return fn
 
-    return suspend_display_ctxmgr()(fn)
+    return hide_ctxmgr()(fn)
+
+
+def suspend_display(
+    fn: Callable[P, R] | RendererBaseT | None = None
+) -> Callable[P, R] | RendererBaseT | AbstractContextManager[None]:
+    warn_deprecated(
+        "`suspend_display` is deprecated. Please use `hide` instead. "
+        "It has a new name, but the exact same functionality."
+    )
+    return hide(fn)  # type: ignore
 
 
 @contextlib.contextmanager
-def suspend_display_ctxmgr() -> Generator[None, None, None]:
+def hide_ctxmgr() -> Generator[None, None, None]:
     oldhook = sys.displayhook
     sys.displayhook = null_displayhook
     try:

tests/playwright/shiny/shiny-express/suspend_display/app.py renamed to tests/playwright/shiny/shiny-express/hide/app.py

@@ -1,10 +1,10 @@
 from shiny import render, ui
-from shiny.express import input, suspend_display
+from shiny.express import hide, input
 
 with ui.card(id="card"):
     ui.input_slider("s1", "A", 1, 100, 20)
 
-    @suspend_display
+    @hide
     @render.text
     def hidden():
         return input.s1()

tests/playwright/shiny/shiny-express/suspend_display/test_suspend_display.py renamed to tests/playwright/shiny/shiny-express/hide/test_hide.py

@@ -6,7 +6,7 @@
 import pytest
 
 from shiny import render, ui
-from shiny.express import suspend_display, ui_kwargs
+from shiny.express import hide, ui_kwargs
 from shiny.express._run import run_express
 
 
@@ -53,7 +53,7 @@ def text1():
         == ui.output_text_verbatim("text1").get_html_string()
     )
 
-    @suspend_display
+    @hide
     @render.text
     def text2():
         return "text"
@@ -79,7 +79,7 @@ def text4():
         text4.tagify()
 
 
-def test_suspend_display():
+def test_hide():
     old_displayhook = sys.displayhook
     try:
         called = False
@@ -90,11 +90,11 @@ def display_hook_spy(_: object) -> Any:
 
         sys.displayhook = display_hook_spy
 
-        with suspend_display():
+        with hide():
             sys.displayhook("foo")
-        suspend_display(lambda: sys.displayhook("bar"))()
+        hide(lambda: sys.displayhook("bar"))()
 
-        @suspend_display
+        @hide
         def whatever(x: Any):
             sys.displayhook(x)