Download Media¶

Source code for examples/ui/download.py

Tip: paste this code into an empty cell, and the marimo editor will create cells for you

# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "marimo",
#     "pandas==2.2.3",
# ]
# ///
import marimo

__generated_with = "0.10.14"
app = marimo.App()


@app.cell
def _():
    import marimo as mo
    return (mo,)


@app.cell(hide_code=True)
def _(json, mo, pd):
    # Text file download
    text_download = mo.download(
        data="Hello, world!".encode("utf-8"),
        filename="hello.txt",
        mimetype="text/plain",
        label="Download text",
    )

    # CSV download using pandas
    df = pd.DataFrame({"name": ["Alice", "Bob", "Charlie"], "age": [25, 30, 35]})
    csv_download = mo.download(
        data=df.to_csv().encode("utf-8"),
        filename="data.csv",
        mimetype="text/csv",
        label="Download CSV",
    )

    # JSON download
    data = {"message": "Hello", "count": 42}
    json_download = mo.download(
        data=json.dumps(data).encode("utf-8"),
        filename="data.json",
        mimetype="application/json",
        label="Download JSON",
    )

    mo.hstack([text_download, csv_download, json_download])
    return csv_download, data, df, json_download, text_download


@app.cell(hide_code=True)
def _(json, mo, pd):
    import time
    import asyncio


    # Text file download with lazy loading
    def get_text_data():
        time.sleep(1)
        return "Hello, world!".encode("utf-8")


    text_download_lazy = mo.download(
        data=get_text_data,
        filename="hello.txt",
        mimetype="text/plain",
        label="Download text",
    )


    # CSV download using pandas with lazy loading
    async def get_csv_data():
        await asyncio.sleep(1)
        _df = pd.DataFrame(
            {"name": ["Alice", "Bob", "Charlie"], "age": [25, 30, 35]}
        )
        return _df


    csv_download_lazy = mo.download(
        data=get_csv_data,
        filename="data.csv",
        mimetype="text/csv",
        label="Download CSV",
    )


    # JSON download with lazy loading
    async def get_json_data():
        await asyncio.sleep(1)
        _data = {"message": "Hello", "count": 42}
        return json.dumps(_data).encode("utf-8")


    json_download_lazy = mo.download(
        data=get_json_data,
        filename="data.json",
        mimetype="application/json",
        label="Download JSON",
    )


    mo.hstack([text_download_lazy, csv_download_lazy, json_download_lazy])
    return (
        asyncio,
        csv_download_lazy,
        get_csv_data,
        get_json_data,
        get_text_data,
        json_download_lazy,
        text_download_lazy,
        time,
    )


@app.cell
def _():
    import pandas as pd
    import json
    return json, pd


if __name__ == "__main__":
    app.run()

marimo.download ¶

download(
    data: Union[
        DataType,
        Callable[[], DataType],
        Callable[[], Coroutine[None, None, DataType]],
    ],
    filename: Optional[str] = None,
    mimetype: Optional[str] = None,
    disabled: bool = False,
    *,
    label: str = "Download"
)

Bases: UIElement[None, None]

Show a download button for a url, bytes, or file-like object.

PARAMETER	DESCRIPTION
`data`	The data to download. Can be: - string (interpreted as a URL) - bytes - file opened in binary mode - callable returning any of the above (for lazy loading) - async callable returning any of the above (for lazy loading) TYPE: `Union[str, bytes, BytesIO, callable]`
`filename`	The name of the file to download. If not provided, the name will be guessed from the data. TYPE: `str` DEFAULT: `None`
`mimetype`	The mimetype of the file to download, for example, (e.g. "text/csv", "image/png"). If not provided, the mimetype will be guessed from the filename. TYPE: `str` DEFAULT: `None`
`disabled`	Whether to disable the download button. TYPE: `bool` DEFAULT: `False`
`label`	The label of the download button. TYPE: `str` DEFAULT: `'Download'`

Example

# Eager loading
download_txt = mo.download(
    data="Hello, world!".encode("utf-8"),
    filename="hello.txt",
    mimetype="text/plain",
)


# Lazy loading
def get_large_data():
    return b"large data"


download_lazy = mo.download(
    data=get_large_data,
    filename="large.txt",
)

text `property` ¶

text: str

A string of HTML representing this element.

value `property` `writable` ¶

value: T

The element's current value.

batch ¶

batch(**elements: UIElement[JSONType, object]) -> batch

Convert an HTML object with templated text into a UI element.

This method lets you create custom UI elements that are represented by arbitrary HTML.

Example

user_info = mo.md(
    '''
    - What's your name?: {name}
    - When were you born?: {birthday}
    '''
).batch(name=mo.ui.text(), birthday=mo.ui.date())

In this example, user_info is a UI Element whose output is markdown and whose value is a dict with keys 'name' and 'birthday' (and values equal to the values of their corresponding elements).

PARAMETER	DESCRIPTION
`elements`	the UI elements to interpolate into the HTML template. TYPE: `UIElement[JSONType, object]` DEFAULT: `{}`

callout ¶

callout(
    kind: Literal[
        "neutral", "danger", "warn", "success", "info"
    ] = "neutral"
) -> Html

Create a callout containing this HTML element.

A callout wraps your HTML element in a raised box, emphasizing its importance. You can style the callout for different situations with the kind argument.

Examples:

mo.md("Hooray, you did it!").callout(kind="success")

mo.md("It's dangerous to go alone!").callout(kind="warn")

center ¶

center() -> Html

Center an item.

Example

mo.md("# Hello, world").center()

RETURNS	DESCRIPTION
`Html`	An `Html` object.

form ¶

form(
    label: str = "",
    *,
    bordered: bool = True,
    loading: bool = False,
    submit_button_label: str = "Submit",
    submit_button_tooltip: Optional[str] = None,
    submit_button_disabled: bool = False,
    clear_on_submit: bool = False,
    show_clear_button: bool = False,
    clear_button_label: str = "Clear",
    clear_button_tooltip: Optional[str] = None,
    validate: Optional[
        Callable[[Optional[JSONType]], Optional[str]]
    ] = None,
    on_change: Optional[
        Callable[[Optional[T]], None]
    ] = None
) -> form[S, T]

Create a submittable form out of this UIElement.

Creates a form that gates submission of a UIElement's value until a submit button is clicked. The form's value is the value of the underlying element from the last submission.

Examples:

Convert any UIElement into a form:

prompt = mo.ui.text_area().form()

Combine with HTML.batch to create a form made out of multiple UIElements:

form = (
    mo.ui.md(
        '''
    **Enter your prompt.**

    {prompt}

    **Choose a random seed.**

    {seed}
    '''
    )
    .batch(
        prompt=mo.ui.text_area(),
        seed=mo.ui.number(),
    )
    .form()
)

PARAMETER	DESCRIPTION
`label`	A text label for the form. TYPE: `str` DEFAULT: `''`
`bordered`	Whether the form should have a border. TYPE: `bool` DEFAULT: `True`
`loading`	Whether the form should be in a loading state. TYPE: `bool` DEFAULT: `False`
`submit_button_label`	The label of the submit button. TYPE: `str` DEFAULT: `'Submit'`
`submit_button_tooltip`	The tooltip of the submit button. TYPE: `Optional[str]` DEFAULT: `None`
`submit_button_disabled`	Whether the submit button should be disabled. TYPE: `bool` DEFAULT: `False`
`clear_on_submit`	Whether the form should clear its contents after submitting. TYPE: `bool` DEFAULT: `False`
`show_clear_button`	Whether the form should show a clear button. TYPE: `bool` DEFAULT: `False`
`clear_button_label`	The label of the clear button. TYPE: `str` DEFAULT: `'Clear'`
`clear_button_tooltip`	The tooltip of the clear button. TYPE: `Optional[str]` DEFAULT: `None`
`validate`	A function that takes the form's value and returns an error message if invalid, or `None` if valid. TYPE: `Optional[Callable[[Optional[JSONType]], Optional[str]]]` DEFAULT: `None`
`on_change`	A callback that takes the form's value and returns an error message if invalid, or `None` if valid. TYPE: `Optional[Callable[[Optional[T]], None]]` DEFAULT: `None`

left ¶

left() -> Html

Left-justify.

Example

mo.md("# Hello, world").left()

RETURNS	DESCRIPTION
`Html`	An `Html` object.

right ¶

right() -> Html

Right-justify.

Example

mo.md("# Hello, world").right()

RETURNS	DESCRIPTION
`Html`	An `Html` object.

send_message ¶

send_message(
    message: Dict[str, object],
    buffers: Optional[Sequence[bytes]],
) -> None

Send a message to the element rendered on the frontend from the backend.

style ¶

style(
    style: Optional[dict[str, Any]] = None, **kwargs: Any
) -> Html

Wrap an object in a styled container.

Example

mo.md("...").style({"max-height": "300px", "overflow": "auto"})
mo.md("...").style(max_height="300px", overflow="auto")

PARAMETER	DESCRIPTION
`style`	an optional dict of CSS styles, keyed by property name TYPE: `Optional[dict[str, Any]]` DEFAULT: `None`
`**kwargs`	CSS styles as keyword arguments TYPE: `Any` DEFAULT: `{}`

Download Media¶

marimo.download ¶

text property ¶

value property writable ¶

batch ¶

callout ¶

center ¶

form ¶

left ¶

right ¶

send_message ¶

style ¶

text `property` ¶

value `property` `writable` ¶