Use a renderer generator to create sync/async render methods with full typing

[schloerke]

A renderer author can now supply a value that will render a value (value_fn) given the result of the user.

Example given render.text:

@renderer_components
async def _text(_meta: RenderMeta, _fn: RenderFnAsync[str | None]) -> str | None:
    value = await _fn()
    if value is None:
        return None
    return str(value)


@overload
def text() -> _text.type_decorator:
    ...


@overload
def text(_fn: _text.type_renderer_fn) -> _text.type_renderer:
    ...


def text(_fn: _text.type_impl_fn = None) -> _text.type_impl:
    " DOCS "
    return _text.impl(_fn)

Previous definition for render.text (w/ docs removed for fair comparison)

RenderTextFunc = Callable[[], "str | None"]
RenderTextFuncAsync = Callable[[], Awaitable["str | None"]]


class RenderText(RenderFunction["str | None", "str | None"]):
    def __init__(self, fn: RenderTextFunc) -> None:
        super().__init__(fn)
        # The Render*Async subclass will pass in an async function, but it tells the
        # static type checker that it's synchronous. wrap_async() is smart -- if is
        # passed an async function, it will not change it.
        self._fn: RenderTextFuncAsync = _utils.wrap_async(fn)

    def __call__(self) -> str | None:
        return _utils.run_coro_sync(self._run())

    async def _run(self) -> str | None:
        res = await self._fn()
        if res is None:
            return None
        return str(res)


class RenderTextAsync(RenderText, RenderFunctionAsync["str | None", "str | None"]):
    def __init__(self, fn: RenderTextFuncAsync) -> None:
        if not _utils.is_async_callable(fn):
            raise TypeError(self.__class__.__name__ + " requires an async function")
        super().__init__(typing.cast(RenderTextFunc, fn))

    async def __call__(  # pyright: ignore[reportIncompatibleMethodOverride]
        self,
    ) -> str | None:
        return await self._run()


@overload
def text(fn: RenderTextFunc | RenderTextFuncAsync) -> RenderText:
    ...


@overload
def text() -> Callable[[RenderTextFunc | RenderTextFuncAsync], RenderText]:
    ...


def text(
    fn: Optional[RenderTextFunc | RenderTextFuncAsync] = None,
) -> RenderText | Callable[[RenderTextFunc | RenderTextFuncAsync], RenderText]:
    def wrapper(fn: RenderTextFunc | RenderTextFuncAsync) -> RenderText:
        if _utils.is_async_callable(fn):
            return RenderTextAsync(fn)
        else:
            fn = typing.cast(RenderTextFunc, fn)
            return RenderText(fn)

    if fn is None:
        return wrapper
    else:
        return wrapper(fn)

---

Render methods converted:

• text
• plot
• image
• table
• ui

Questions

• In render.plot()... Plot variable calls are after self._fn() has been called. Is this ok? (Previously they were before)
  • A: The transform function needs to take the value function and call it to get the value.
• How can I update an @overloaded function name?
  • A: You can't. Very sad

---

Ex renderer used in testing:

from __future__ import annotations

from typing import Optional, overload

from shiny import App, Inputs, Outputs, Session, ui
from shiny.render.transformer import (
    TransformerMetadata,
    ValueFn,
    is_async_callable,
    output_transformer,
    resolve_value_fn,
)


@output_transformer
async def TestTextTransformer(
    _meta: TransformerMetadata,
    _fn: ValueFn[str | None],
    *,
    extra_txt: Optional[str] = None,
) -> str | None:
    value = await resolve_value_fn(_fn)
    value = str(value)
    value += "; "
    value += "async" if is_async_callable(_fn) else "sync"
    if extra_txt:
        value = value + "; " + str(extra_txt)
    return value


@overload
def render_test_text(
    *, extra_txt: Optional[str] = None
) -> TestTextTransformer.OutputRendererDecorator:
    ...


@overload
def render_test_text(
    _fn: TestTextTransformer.ValueFn,
) -> TestTextTransformer.OutputRenderer:
    ...


def render_test_text(
    _fn: TestTextTransformer.ValueFn | None = None,
    *,
    extra_txt: Optional[str] = None,
) -> TestTextTransformer.OutputRenderer | TestTextTransformer.OutputRendererDecorator:
    return TestTextTransformer(
        _fn,
        TestTextTransformer.params(extra_txt=extra_txt),
    )


app_ui = ui.page_fluid(
    ui.code("t1:"),
    ui.output_text_verbatim("t1"),
    ui.code("t2:"),
    ui.output_text_verbatim("t2"),
    ui.code("t3:"),
    ui.output_text_verbatim("t3"),
    ui.code("t4:"),
    ui.output_text_verbatim("t4"),
    ui.code("t5:"),
    ui.output_text_verbatim("t5"),
    ui.code("t6:"),
    ui.output_text_verbatim("t6"),
)


def server(input: Inputs, output: Outputs, session: Session):
    @output
    @render_test_text
    def t1():
        return "t1; no call"
        # return "hello"

    @output
    @render_test_text
    async def t2():
        return "t2; no call"

    @output
    @render_test_text()
    def t3():
        return "t3; call"

    @output
    @render_test_text()
    async def t4():
        return "t4; call"

    @output
    @render_test_text(extra_txt="w/ extra_txt")
    def t5():
        return "t5; call"

    @output
    @render_test_text(extra_txt="w/ extra_txt")
    async def t6():
        return "t6; call"


app = App(app_ui, server)

With expectations:

    OutputTextVerbatim(page, "t1").expect_value("t1; no call; sync")
    OutputTextVerbatim(page, "t2").expect_value("t2; no call; async")
    OutputTextVerbatim(page, "t3").expect_value("t3; call; sync")
    OutputTextVerbatim(page, "t4").expect_value("t4; call; async")
    OutputTextVerbatim(page, "t5").expect_value("t5; call; sync; w/ extra_txt")
    OutputTextVerbatim(page, "t6").expect_value("t6; call; async; w/ extra_txt")