api!: Add Renderer class for creating output renderers (#964)

Author: schloerke

CHANGELOG.md

@@ -16,6 +16,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   * prompt users to install `requirements.txt`
 * Fixed `js-react` template build error. (#965)
 
+### Developer features
+
+* Output renderers should now be created with the `shiny.render.renderer.Renderer` class. This class should contain either a `.transform(self, value)` method (common) or a `.render(self)` (rare). These two methods should return something can be converted to JSON. In addition, `.default_ui(self, id)` should be implemented by returning `htmltools.Tag`-like content for use within Shiny Express. To make your own output renderer, please inherit from the `Renderer[IT]` class where `IT` is the type (excluding `None`) required to be returned from the App author. (#964)
+
+* `shiny.render.RenderFunction` and `shiny.render.RenderFunctionAsync` have been removed. They were deprecated in v0.6.0. Instead, please use `shiny.render.renderer.Renderer`. (#964)
+
+* When transforming values within `shiny.render.transformer.output_transformer` transform function,  `shiny.render.transformer.resolve_value_fn` is no longer needed as the value function given to the output transformer is now **always** an asynchronous function. `resolve_value_fn(fn)` method has been deprecated. Please change your code from `value = await resolve_value_fn(_fn)` to `value = await _fn()`. (#964)
+
+* `shiny.render.OutputRendererSync` and `shiny.render.OutputRendererAsync` helper classes have been removed in favor of an updated `shiny.render.OutputRenderer` class. Now, the app's output value function will be transformed into an asynchronous function for simplified, consistent execution behavior. If redesigning your code, instead please create a new renderer that inherits from `shiny.render.renderer.Renderer`. (#964)
 
 
 ## [0.6.1.1] - 2023-12-22

docs/_quartodoc.yml

@@ -175,17 +175,11 @@ quartodoc:
             name: "Create rendering outputs"
             desc: ""
           contents:
-            - render.transformer.output_transformer
-            - render.transformer.OutputTransformer
-            - render.transformer.TransformerMetadata
-            - render.transformer.TransformerParams
-            - render.transformer.OutputRenderer
-            - render.transformer.OutputRendererSync
-            - render.transformer.OutputRendererAsync
-            - render.transformer.is_async_callable
-            - render.transformer.resolve_value_fn
-            - render.transformer.ValueFn
-            - render.transformer.TransformFn
+            - render.renderer.Renderer
+            - render.renderer.RendererBase
+            - render.renderer.Jsonifiable
+            - render.renderer.ValueFn
+            - render.renderer.AsyncValueFn
     - title: Reactive programming
       desc: ""
       contents:
@@ -330,6 +324,7 @@ quartodoc:
         - ui.panel_main
         - ui.panel_sidebar
         - ui.nav
+        - render.transformer.resolve_value_fn
     - title: Experimental
       desc: "These methods are under consideration and are considered unstable. However, if there is a method you are excited about, please let us know!"
       contents:

shiny/_typing_extensions.py

@@ -23,13 +23,13 @@
 # they should both come from the same typing module.
 # https://peps.python.org/pep-0655/#usage-in-python-3-11
 if sys.version_info >= (3, 11):
-    from typing import NotRequired, TypedDict, assert_type
+    from typing import NotRequired, Self, TypedDict, assert_type
 else:
-    from typing_extensions import NotRequired, TypedDict, assert_type
+    from typing_extensions import NotRequired, Self, TypedDict, assert_type
 
 
 # The only purpose of the following line is so that pyright will put all of the
 # conditional imports into the .pyi file when generating type stubs. Without this line,
 # pyright will not include the above imports in the generated .pyi file, and it will
 # result in a lot of red squiggles in user code.
-_: 'Concatenate[str, ParamSpec("P")] | ParamSpec | TypeGuard | NotRequired | TypedDict | assert_type'  # type:ignore
+_: 'Concatenate[str, ParamSpec("P")] | ParamSpec | TypeGuard | NotRequired | TypedDict | assert_type | Self'  # type:ignore

shiny/_utils.py

@@ -221,35 +221,89 @@ def private_seed() -> Generator[None, None, None]:
 # Async-related functions
 # ==============================================================================
 
-T = TypeVar("T")
+R = TypeVar("R")  # Return type
 P = ParamSpec("P")
 
 
 def wrap_async(
-    fn: Callable[P, T] | Callable[P, Awaitable[T]]
-) -> Callable[P, Awaitable[T]]:
+    fn: Callable[P, R] | Callable[P, Awaitable[R]]
+) -> Callable[P, Awaitable[R]]:
     """
-    Given a synchronous function that returns T, return an async function that wraps the
+    Given a synchronous function that returns R, return an async function that wraps the
     original function. If the input function is already async, then return it unchanged.
     """
 
     if is_async_callable(fn):
         return fn
 
-    fn = cast(Callable[P, T], fn)
+    fn = cast(Callable[P, R], fn)
 
     @functools.wraps(fn)
-    async def fn_async(*args: P.args, **kwargs: P.kwargs) -> T:
+    async def fn_async(*args: P.args, **kwargs: P.kwargs) -> R:
         return fn(*args, **kwargs)
 
     return fn_async
 
 
+# # TODO-barret-future; Q: Keep code?
+# class WrapAsync(Generic[P, R]):
+#     """
+#     Make a function asynchronous.
+
+#     Parameters
+#     ----------
+#     fn
+#         Function to make asynchronous.
+
+#     Returns
+#     -------
+#     :
+#         Asynchronous function (within the `WrapAsync` instance)
+#     """
+
+#     def __init__(self, fn: Callable[P, R] | Callable[P, Awaitable[R]]):
+#         if isinstance(fn, WrapAsync):
+#             fn = cast(WrapAsync[P, R], fn)
+#             return fn
+#         self._is_async = is_async_callable(fn)
+#         self._fn = wrap_async(fn)
+
+#     async def __call__(self, *args: P.args, **kwargs: P.kwargs) -> R:
+#         """
+#         Call the asynchronous function.
+#         """
+#         return await self._fn(*args, **kwargs)
+
+#     @property
+#     def is_async(self) -> bool:
+#         """
+#         Was the original function asynchronous?
+
+#         Returns
+#         -------
+#         :
+#             Whether the original function is asynchronous.
+#         """
+#         return self._is_async
+
+#     @property
+#     def fn(self) -> Callable[P, R] | Callable[P, Awaitable[R]]:
+#         """
+#         Retrieve the original function
+
+#         Returns
+#         -------
+#         :
+#             Original function supplied to the `WrapAsync` constructor.
+#         """
+#         return self._fn
+
+
 # This function should generally be used in this code base instead of
 # `iscoroutinefunction()`.
 def is_async_callable(
-    obj: Callable[P, T] | Callable[P, Awaitable[T]]
-) -> TypeGuard[Callable[P, Awaitable[T]]]:
+    obj: Callable[P, R] | Callable[P, Awaitable[R]]
+) -> TypeGuard[Callable[P, Awaitable[R]]]:
     """
     Determine if an object is an async function.
 
@@ -282,7 +336,7 @@ def is_async_callable(
 # of how this stuff works.
 # For a more in-depth explanation, see
 # https://snarky.ca/how-the-heck-does-async-await-work-in-python-3-5/.
-def run_coro_sync(coro: Awaitable[T]) -> T:
+def run_coro_sync(coro: Awaitable[R]) -> R:
     """
     Run a coroutine that is in fact synchronous. Given a coroutine (which is
     returned by calling an `async def` function), this function will run the
@@ -310,7 +364,7 @@ def run_coro_sync(coro: Awaitable[T]) -> T:
     )
 
 
-def run_coro_hybrid(coro: Awaitable[T]) -> "asyncio.Future[T]":
+def run_coro_hybrid(coro: Awaitable[R]) -> "asyncio.Future[R]":
     """
     Synchronously runs the given coro up to its first yield, then runs the rest of the
     coro by scheduling it on the current event loop, as per normal. You can think of
@@ -325,7 +379,7 @@ def run_coro_hybrid(coro: Awaitable[T]) -> "asyncio.Future[T]":
     asyncio Task implementation, this is a hastily assembled hack job; who knows what
     unknown unknowns lurk here.
     """
-    result_future: asyncio.Future[T] = asyncio.Future()
+    result_future: asyncio.Future[R] = asyncio.Future()
 
     if not inspect.iscoroutine(coro):
         raise TypeError("run_coro_hybrid requires a Coroutine object.")

shiny/api-examples/Renderer/app.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from shiny import App, Inputs, Outputs, Session, ui
+from shiny.render.renderer import Renderer, ValueFn
+
+#######
+# Start of package author code
+#######
+
+
+class render_capitalize(Renderer[str]):
+    # The documentation for the class will be displayed when the user hovers over the
+    # decorator when **no** parenthesis are used. Ex: `@render_capitalize`
+    # If no documentation is supplied to the `__init__()` method, then this
+    # documentation will be displayed when parenthesis are used on the decorator.
+    """
+    Render capitalize class documentation goes here.
+    """
+
+    to_case: Literal["upper", "lower", "ignore"]
+    """
+    The case to render the value in.
+    """
+    placeholder: bool
+    """
+    Whether to render a placeholder value. (Defaults to `True`)
+    """
+
+    def default_ui(self, id: str):
+        """
+        Express UI for the renderer
+        """
+        return ui.output_text_verbatim(id, placeholder=self.placeholder)
+
+    def __init__(
+        self,
+        _fn: ValueFn[str | None] | None = None,
+        *,
+        to_case: Literal["upper", "lower", "ignore"] = "upper",
+        placeholder: bool = True,
+    ) -> None:
+        # If a different set of documentation is supplied to the `__init__` method,
+        # then this documentation will be displayed when parenthesis are used on the decorator.
+        # Ex: `@render_capitalize()`
+        """
+        Render capitalize documentation goes here.
+
+        It is a good idea to talk about parameters here!
+
+        Parameters
+        ----------
+        to_case
+            The case to render the value. (`"upper"`)
+
+            Options:
+            - `"upper"`: Render the value in upper case.
+            - `"lower"`: Render the value in lower case.
+            - `"ignore"`: Do not alter the case of the value.
+
+        placeholder
+            Whether to render a placeholder value. (`True`)
+        """
+        # Do not pass params
+        super().__init__(_fn)
+        self.widget = None
+        self.to_case = to_case
+
+    async def render(self) -> str | None:
+        value = await self.value_fn()
+        if value is None:
+            # If `None` is returned, then do not render anything.
+            return None
+
+        ret = str(value)
+        if self.to_case == "upper":
+            return ret.upper()
+        if self.to_case == "lower":
+            return ret.lower()
+        if self.to_case == "ignore":
+            return ret
+        raise ValueError(f"Invalid value for `to_case`: {self.to_case}")
+
+
+class render_upper(Renderer[str]):
+    """
+    Minimal capitalize string transformation renderer.
+
+    No parameters are supplied to this renderer. This allows us to skip the `__init__()`
+    method and `__init__()` documentation. If you hover over this decorator with and
+    without parenthesis, you will see this documentation in both situations.
+
+    Note: This renderer is equivalent to `render_capitalize(to="upper")`.
+    """
+
+    def default_ui(self, id: str):
+        """
+        Express UI for the renderer
+        """
+        return ui.output_text_verbatim(id, placeholder=True)
+
+    async def transform(self, value: str) -> str:
+        """
+        Transform the value to upper case.
+
+        This method is shorthand for the default `render()` method. It is useful to
+        transform non-`None` values. (Any `None` value returned by the app author will
+        be forwarded to the browser.)
+
+        Parameters
+        ----------
+        value
+            The a non-`None` value to transform.
+
+        Returns
+        -------
+        str
+            The transformed value. (Must be a subset of `Jsonifiable`.)
+        """
+
+        return str(value).upper()
+
+
+#######
+# End of package author code
+#######
+
+
+#######
+# Start of app author code
+#######
+
+
+def text_row(id: str, label: str):
+    return ui.tags.tr(
+        ui.tags.td(f"{label}:"),
+        ui.tags.td(ui.output_text_verbatim(id, placeholder=True)),
+    )
+    return ui.row(
+        ui.column(6, f"{id}:"),
+        ui.column(6, ui.output_text_verbatim(id, placeholder=True)),
+    )
+
+
+app_ui = ui.page_fluid(
+    ui.h1("Capitalization renderer"),
+    ui.input_text("caption", "Caption:", "Data summary"),
+    ui.tags.table(
+        text_row("upper", "@render_upper"),
+        text_row("upper_with_paren", "@render_upper()"),
+        #
+        text_row("cap_upper", "@render_capitalize"),
+        text_row("cap_lower", "@render_capitalize(to='lower')"),
+    ),
+)
+
+
+def server(input: Inputs, output: Outputs, session: Session):
+    # Hovering over `@render_upper` will display the class documentation
+    @render_upper
+    def upper():
+        return input.caption()
+
+    # Hovering over `@render_upper` will display the class documentation as there is no
+    # `__init__()` documentation
+    @render_upper()
+    def upper_with_paren():
+        return input.caption()
+
+    # Hovering over `@render_capitalize` will display the class documentation
+    @render_capitalize
+    def cap_upper():
+        return input.caption()
+
+    # Hovering over `@render_capitalize` will display the `__init__()` documentation
+    @render_capitalize(to_case="lower")
+    def cap_lower():
+        return input.caption()
+
+
+app = App(app_ui, server)

shiny/api-examples/output_transformer/app.py

@@ -11,6 +11,10 @@
 )
 
 #######
+# DEPRECATED. Please see `shiny.render.renderer.Renderer` for the latest API.
+# This example is kept for backwards compatibility.
+#
+#
 # Package authors can create their own output transformer methods by leveraging
 # `output_transformer` decorator.
 #