render.download
render.download(
self
fn=None
*
filename=None
media_type=None
encoding='utf-8'
label='Download'
)Decorator to register a function to handle a download.
This decorator is used to register a function that will be called when the user clicks a download link or button. The decorated function may be sync or async, and should do one of the following:
- Return a string. This will be assumed to be a filename; Shiny will return this file to the browser, and the downloaded file will have the same filename as the original, with an inferred mime type. This is the most convenient IF the file already exists on disk. But if the function must create a temporary file, then this method should not be used, because the temporary file will not be deleted by Shiny. Use the
yieldmethod instead. yieldone or more strings or bytestrings (b"..."orio.BytesIO().getvalue()). If strings are yielded, they'll be encoded in UTF-8. (This is better for temp files as after you're done yielding you can delete the temp file, or use a tempfile.TemporaryFile context manager) With this method, it's important that the@render.downloaddecorator have afilenameargument, as the decorated function won't help with that.
Parameters
filename : Optional[str | Callable[[], str]] = None-
The filename of the download.
media_type : None | str | Callable[[], str] = None-
The media type of the download.
encoding : str = 'utf-8'-
The encoding of the download.
label : TagChild = 'Download'-
(Express only) A label for the button. Defaults to “Download”.
Returns
:-
The decorated function.
See Also
Examples
#| standalone: true
#| components: [editor, viewer]
#| layout: vertical
#| viewerHeight: 400
## file: app.py
import asyncio
import io
import os
from datetime import date
from typing import Any
import matplotlib.pyplot as plt
import numpy as np
from shiny import App, Inputs, Outputs, Session, render, ui
def make_example(id: str, label: str, title: str, desc: str, extra: Any = None):
return ui.column(
4,
ui.div(
{"class": "card mb-4"},
ui.div(title, class_="card-header"),
ui.div(
{"class": "card-body"},
ui.p(desc, class_="card-text text-muted"),
extra,
ui.download_button(id, label, class_="btn-primary"),
),
),
)
app_ui = ui.page_fluid(
ui.row(
make_example(
"download1",
label="Download CSV",
title="Simple case",
desc="Downloads a pre-existing file, using its existing name on disk.",
),
),
ui.row(
make_example(
"download2",
label="Download plot",
title="Dynamic data generation",
desc="Downloads a PNG that's generated on the fly.",
extra=[
ui.input_text("title", "Plot title", "Random scatter plot"),
ui.input_slider(
"num_points", "Number of data points", min=1, max=100, value=50
),
],
),
),
ui.row(
make_example(
"download3",
"Download",
"Dynamic filename",
"Demonstrates that filenames can be generated on the fly (and use Unicode characters!).",
),
),
ui.row(
make_example(
"download4",
"Download",
"Failed downloads",
"Throws an error in the download handler, download should not succeed.",
),
),
ui.row(
make_example(
"download5",
"Download",
"Undefined download",
"This button doesn't have corresponding server code registered to it, download should result in 404 error",
),
),
)
def server(input: Inputs, output: Outputs, session: Session):
@render.download()
def download1():
"""
This is the simplest case. The implementation simply returns the name of a file.
Note that the function name (`download1`) determines which download_button()
corresponds to this function.
"""
path = os.path.join(os.path.dirname(__file__), "mtcars.csv")
return path
@render.download(filename="image.png")
def download2():
"""
Another way to implement a file download is by yielding bytes; either all at
once, like in this case, or by yielding multiple times. When using this
approach, you should pass a filename argument to @render.download, which
determines what the browser will name the downloaded file.
"""
print(input.num_points())
x = np.random.uniform(size=input.num_points())
y = np.random.uniform(size=input.num_points())
plt.figure()
plt.scatter(x, y)
plt.title(input.title())
with io.BytesIO() as buf:
plt.savefig(buf, format="png")
yield buf.getvalue()
@render.download(
filename=lambda: f"ć–°ĺž‹-{date.today().isoformat()}-{np.random.randint(100, 999)}.csv"
)
async def download3():
await asyncio.sleep(0.25)
yield "one,two,three\n"
yield "ć–°,1,2\n"
yield "ĺž‹,4,5\n"
@output(id="download4")
@render.download(filename="failuretest.txt")
async def _():
yield "hello"
raise Exception("This error was caused intentionally")
app = App(app_ui, server)
## file: mtcars.csv
mpg,cyl,disp,hp,drat,wt,qsec,vs,am,gear,carb
21,6,160,110,3.9,2.62,16.46,0,1,4,4
21,6,160,110,3.9,2.875,17.02,0,1,4,4
22.8,4,108,93,3.85,2.32,18.61,1,1,4,1
21.4,6,258,110,3.08,3.215,19.44,1,0,3,1
18.7,8,360,175,3.15,3.44,17.02,0,0,3,2
18.1,6,225,105,2.76,3.46,20.22,1,0,3,1
14.3,8,360,245,3.21,3.57,15.84,0,0,3,4
24.4,4,146.7,62,3.69,3.19,20,1,0,4,2
22.8,4,140.8,95,3.92,3.15,22.9,1,0,4,2
19.2,6,167.6,123,3.92,3.44,18.3,1,0,4,4
17.8,6,167.6,123,3.92,3.44,18.9,1,0,4,4
16.4,8,275.8,180,3.07,4.07,17.4,0,0,3,3
17.3,8,275.8,180,3.07,3.73,17.6,0,0,3,3
15.2,8,275.8,180,3.07,3.78,18,0,0,3,3
10.4,8,472,205,2.93,5.25,17.98,0,0,3,4
10.4,8,460,215,3,5.424,17.82,0,0,3,4
14.7,8,440,230,3.23,5.345,17.42,0,0,3,4
32.4,4,78.7,66,4.08,2.2,19.47,1,1,4,1
30.4,4,75.7,52,4.93,1.615,18.52,1,1,4,2
33.9,4,71.1,65,4.22,1.835,19.9,1,1,4,1
21.5,4,120.1,97,3.7,2.465,20.01,1,0,3,1
15.5,8,318,150,2.76,3.52,16.87,0,0,3,2
15.2,8,304,150,3.15,3.435,17.3,0,0,3,2
13.3,8,350,245,3.73,3.84,15.41,0,0,3,4
19.2,8,400,175,3.08,3.845,17.05,0,0,3,2
27.3,4,79,66,4.08,1.935,18.9,1,1,4,1
26,4,120.3,91,4.43,2.14,16.7,0,1,5,2
30.4,4,95.1,113,3.77,1.513,16.9,1,1,5,2
15.8,8,351,264,4.22,3.17,14.5,0,1,5,4
19.7,6,145,175,3.62,2.77,15.5,0,1,5,6
15,8,301,335,3.54,3.57,14.6,0,1,5,8
21.4,4,121,109,4.11,2.78,18.6,1,1,4,2