Skip to content

Commit 342d44a

Browse files
authored
Update docstrings for expressify, hold, and render.express (#1066)
1 parent 585777c commit 342d44a

File tree

4 files changed

+73
-22
lines changed

4 files changed

+73
-22
lines changed

docs/_quartodoc.yml

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -165,6 +165,7 @@ quartodoc:
165165
- render.table
166166
- render.text
167167
- render.ui
168+
- render.express
168169
- render.data_frame
169170
- render.DataGrid
170171
- render.DataTable
@@ -329,6 +330,15 @@ quartodoc:
329330
flatten: true
330331
contents:
331332
- express.ui.page_opts
333+
- kind: page
334+
path: DisplayFunctions
335+
summary:
336+
name: "Display functions"
337+
desc: ""
338+
flatten: true
339+
contents:
340+
- express.ui.hold
341+
- express.expressify
332342
- title: Deprecated
333343
desc: ""
334344
contents:

shiny/express/expressify_decorator/_expressify.py

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,32 @@ def expressify() -> Callable[[TFunc], TFunc]:
102102

103103

104104
def expressify(fn: TFunc | None = None) -> TFunc | Callable[[TFunc], TFunc]:
105+
"""
106+
Decorate a function so that output is captured as in Shiny Express
107+
108+
In a Shiny Express app, the output of each line of the app file is captured and
109+
displayed in the UI. However, if the app calls a function, only the return value of
110+
the function is displayed. This decorator changes the behavior of the function so
111+
that when it is executed, the result of each line is captured and displayed, just
112+
like code at the top level of a Shiny Express app.
113+
114+
Parameters
115+
----------
116+
fn :
117+
The function to decorate. If not provided, this is a decorator factory.
118+
119+
Returns
120+
-------
121+
:
122+
A function that returns `None`, or a decorator for a function that returns
123+
`None`.
124+
125+
See Also
126+
--------
127+
* ~shiny.render.express
128+
* ~shiny.express.ui.hold
129+
"""
130+
105131
def decorator(fn: TFunc) -> TFunc:
106132
if is_pyodide:
107133
# Disable code caching on Pyodide due to bug in hashing bytecode in 0.22.1.

shiny/express/ui/_hold.py

Lines changed: 15 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -19,32 +19,25 @@
1919
def hold() -> HoldContextManager:
2020
"""Prevent the display of UI elements in various ways.
2121
22-
If used as a context manager (`with hide():`), it prevents the display of all UI
23-
elements within the context block. (This is useful when you want to temporarily
24-
prevent the display of a large number of UI elements, or when you want to prevent
25-
the display of UI elements that are not directly under your control.)
26-
27-
If used as a decorator (without parentheses) on a Shiny rendering function, it
28-
prevents that function from automatically outputting itself at the point of its
29-
declaration. (This is useful when you want to define the rendering logic for an
30-
output, but want to explicitly call a UI output function to indicate where and how
31-
it should be displayed.)
32-
33-
If used as a decorator (without parentheses) on any other function, it turns
34-
Python's `sys.displayhook` into a no-op for the duration of the function call.
35-
36-
Parameters
37-
----------
38-
fn
39-
The function to decorate. If `None`, returns a context manager that prevents the
40-
display of UI elements within the context block.
22+
This is used as a context manager, as in `with hold():`. It prevents the display of
23+
all UI elements within the context block. (This is useful when you want to
24+
temporarily prevent the display of a large number of UI elements, or when you want
25+
to prevent the display of UI elements that are not directly under your control.)
26+
27+
It can also be used as `with hold() as content:` to capture the UI elements that
28+
would be displayed within the context block. Then, later, you can put `content` on a
29+
line by itself to display the captured UI elements.
4130
4231
Returns
4332
-------
4433
:
45-
If `fn` is `None`, returns a context manager that prevents the display of UI
46-
elements within the context block. Otherwise, returns a decorated version of
47-
`fn`.
34+
A context manager that prevents the display of UI elements within the context
35+
block.
36+
37+
See Also
38+
--------
39+
* ~shiny.render.express
40+
* ~shiny.express.expressify
4841
"""
4942

5043
return HoldContextManager()

shiny/render/_express.py

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,28 @@
1818

1919

2020
class express(Renderer[None]):
21+
"""
22+
Reactively render HTML content with output captured as in Shiny Express
23+
24+
This is similar to :class:`~shiny.render.ui`, except that :class:`~shiny.render.ui`
25+
uses the return value from the the decorated function, whereas this function works
26+
like Shiny Express: as it executes each line of the decorated function, it calls
27+
:func:`~sys.displayhook()` on the result. This has the effet of "capturing" the
28+
output of each line.
29+
30+
Returns
31+
-------
32+
:
33+
A decorator for a function that returns `None`.
34+
35+
See Also
36+
--------
37+
* ~shiny.render.ui
38+
* ~shiny.ui.output_ui
39+
* ~shiny.express.expressify
40+
* ~shiny.express.ui.hold
41+
"""
42+
2143
def auto_output_ui(
2244
self,
2345
*,

0 commit comments

Comments
 (0)