Create output renderers

Package author methods for creating new output renderers.

render.renderer.Renderer

render.renderer.Renderer(self, _fn=None)

Output renderer class

An output renderer is a class that will take in a callable function (value function), transform the returned value into a JSON-serializable object, and send the result to the browser.

When the value function is received, the renderer will be auto registered with the current session's Output class, hooking it into Shiny's reactive graph. By auto registering as an Output, it allows for App authors to skip adding @output above the renderer. (If programmatic id is needed, @output(id="foo") can still be used!)

There are two methods that must be implemented by the subclasses: .auto_output_ui(self) and either .transform(self, value: IT) or .render(self).

In Express mode, the output renderer will automatically render its UI via .auto_output_ui(self). This helper method allows App authors to skip adding a ui.output_* function to their UI, making Express mode even more concise. If more control is needed over the UI, @ui.hold can be used to suppress the auto rendering of the UI. When using @ui.hold on a renderer, the renderer's UI will need to be added to the app to connect the rendered output to Shiny's reactive graph.
The render method is responsible for executing the value function and performing any transformations for the output value to be JSON-serializable (None is a valid value!). To avoid the boilerplate of resolving the value function and returning early if None is received, package authors may implement the .transform(self, value: IT) method. The transform method's sole job is to transform non-None values into an object that is JSON-serializable.

Examples

#| standalone: true
#| components: [editor, viewer]
#| layout: vertical
#| viewerHeight: 400

## file: app.py
from __future__ import annotations

# Import the custom renderer implementations
from renderers import render_capitalize, render_upper

from shiny import App, Inputs, Outputs, Session, ui

app_ui = ui.page_fluid(
    ui.h1("Capitalization renderer"),
    ui.input_text("caption", "Caption:", "Data summary"),
    "@render_upper: ",
    ui.output_text_verbatim("upper", placeholder=True),
    "@render_upper(): ",
    ui.output_text_verbatim("upper_with_paren", placeholder=True),
    "@render_capitalize: ",
    ui.output_text_verbatim("cap_upper", placeholder=True),
    "@render_capitalize(to='lower'): ",
    ui.output_text_verbatim("cap_lower", placeholder=True),
)


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)

Attributes

Name	Description
fn	App-supplied output value function which returns type `IT`. This function is always asyncronous as the original app-supplied function possibly wrapped to execute asynchonously.
output_id	Output function name or ID (provided to `@output(id=)`).

Methods

Name	Description
auto_output_ui	Express mode method that automatically generates the output’s UI.
render	Renders the output value function.
transform	Transform an output value into a JSON-serializable object.

auto_output_ui

render.renderer.Renderer.auto_output_ui()

Express mode method that automatically generates the output's UI.

render

render.renderer.Renderer.render()

Renders the output value function.

This method is called when the renderer is requested to render its output.

The Renderer's render() implementation goes as follows:

Execute the value function supplied to the renderer.
If the output value is None, None will be returned.
If the output value is not None, the .transform() method will be called to transform the value into a JSON-serializable object.

When overwriting this method in a subclass, the implementation should execute the value function .fn and return the transformed value (which is JSON-serializable).

transform

render.renderer.Renderer.transform(value)

Transform an output value into a JSON-serializable object.

When subclassing Renderer, this method can be implemented to transform non-None values into a JSON-serializable object.

If a .render() method is not implemented, this method must be implemented. When the output is requested, the Renderer's .render() method will execute the output value function, return None if the value is None, and call this method to transform the value into a JSON-serializable object.

Note, only one of .transform() or .render() should be implemented.

render.renderer.Jsonifiable

render.renderer.Jsonifiable

render.renderer.ValueFn

render.renderer.ValueFn

App-supplied output value function which returns type IT or None. This function can be synchronous or asynchronous.

render.renderer.AsyncValueFn

render.renderer.AsyncValueFn(self, fn)

App-supplied output value function which returns type IT. asynchronous.

Type definition: Callable[[], Awaitable[IT]]

Methods

Name	Description
get_async_fn	Return the async value function.
get_sync_fn	Retrieve the original, synchronous value function function.
is_async	Was the original function asynchronous?

get_async_fn

render.renderer.AsyncValueFn.get_async_fn()

Return the async value function.

Returns

Type	Description
Callable[[], Awaitable[`IT` \| None]]	Async wrapped value function supplied to the `AsyncValueFn` constructor.

get_sync_fn

render.renderer.AsyncValueFn.get_sync_fn()

Retrieve the original, synchronous value function function.

If the original function was asynchronous, a runtime error will be thrown.

Returns

Type	Description
Callable[[], `IT` \| None]	Original, synchronous function supplied to the `AsyncValueFn` constructor.

is_async

render.renderer.AsyncValueFn.is_async()

Was the original function asynchronous?

Returns

Type	Description
bool	Whether the original function is asynchronous.

render.renderer.RendererT

render.renderer.RendererT

Generic output renderer class to pass the original Renderer subclass through a decorator function.

When accepting and returning a Renderer class, utilize this TypeVar as to not reduce the variable type to Renderer[Any]