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

Loading...




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

: 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

: Callable[[], IT | None]

Original, synchronous function supplied to the AsyncValueFn constructor.

is_async

render.renderer.AsyncValueFn.is_async()

Was the original function asynchronous?

Returns

: 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]