Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

feat: use variable name as download filename in dataframe viewer (#8811)

Sushit Lal Pakrashy92ff13c38cb1
diff --git a/frontend/src/components/data-table/TableActions.tsx b/frontend/src/components/data-table/TableActions.tsx
index bb956e6c08..d2f386abfc 100644
--- a/frontend/src/components/data-table/TableActions.tsx
+++ b/frontend/src/components/data-table/TableActions.tsx
@@ -29,7 +29,6 @@ interface TableActionsProps<TData> {
onRowSelectionChange?: (value: RowSelectionState) => void;
table: Table<TData>;
downloadAs?: DownloadActionProps["downloadAs"];
- downloadFileName?: string;
getRowIds?: GetRowIds;
toggleDisplayHeader?: () => void;
showChartBuilder?: boolean;
@@ -51,7 +50,6 @@ export const TableActions = <TData,>({
onRowSelectionChange,
table,
downloadAs,
- downloadFileName,
getRowIds,
toggleDisplayHeader,
showChartBuilder,
@@ -165,12 +163,7 @@ export const TableActions = <TData,>({
</span>
)}
<div className="ml-auto">
- {downloadAs && (
- <DownloadAs
- downloadAs={downloadAs}
- downloadFileName={downloadFileName}
- />
- )}
+ {downloadAs && <DownloadAs downloadAs={downloadAs} />}
</div>
</div>
);
diff --git a/frontend/src/components/data-table/data-table.tsx b/frontend/src/components/data-table/data-table.tsx
index 8d170ac38e..8f9bc52d39 100644
--- a/frontend/src/components/data-table/data-table.tsx
+++ b/frontend/src/components/data-table/data-table.tsx
@@ -127,7 +127,6 @@ const DataTableInternal = <TData,>({
paginationState,
setPaginationState,
downloadAs,
- downloadFileName,
manualPagination = false,
pagination = false,
onRowSelectionChange,
@@ -322,7 +321,6 @@ const DataTableInternal = <TData,>({
onRowSelectionChange={onRowSelectionChange}
table={table}
downloadAs={downloadAs}
- downloadFileName={downloadFileName}
getRowIds={getRowIds}
toggleDisplayHeader={toggleDisplayHeader}
showChartBuilder={showChartBuilder}
diff --git a/frontend/src/components/data-table/download-actions.tsx b/frontend/src/components/data-table/download-actions.tsx
index c9543556a3..91bb3c27a9 100644
--- a/frontend/src/components/data-table/download-actions.tsx
+++ b/frontend/src/components/data-table/download-actions.tsx
@@ -14,7 +14,6 @@ import { logNever } from "@/utils/assertNever";
import { copyToClipboard } from "@/utils/copy";
import { downloadByURL } from "@/utils/download";
import { prettyError } from "@/utils/errors";
-import { Filenames } from "@/utils/filenames";
import {
jsonParseWithSpecialChar,
jsonToMarkdown,
@@ -36,8 +35,9 @@ import { toast } from "../ui/use-toast";
type DownloadFormat = "csv" | "json" | "parquet";
export interface DownloadActionProps {
- downloadAs: (req: { format: DownloadFormat }) => Promise<string>;
- downloadFileName?: string;
+ downloadAs: (req: {
+ format: DownloadFormat;
+ }) => Promise<{ url: string; filename: string }>;
}
const options = [
@@ -99,7 +99,9 @@ export const DownloadAs: React.FC<DownloadActionProps> = (props) => {
</Button>
);
- const getDownloadUrl = (format: DownloadFormat) => {
+ const getDownloadResponse = (
+ format: DownloadFormat,
+ ): Promise<{ url: string; filename: string }> => {
return props.downloadAs({ format }).catch((error) => {
toast({
title: "Failed to download",
@@ -116,26 +118,26 @@ export const DownloadAs: React.FC<DownloadActionProps> = (props) => {
switch (format) {
case "tsv": {
- const downloadUrl = await getDownloadUrl("json");
- const json = await fetchJson(downloadUrl);
+ const { url } = await getDownloadResponse("json");
+ const json = await fetchJson(url);
text = jsonToTSV(json, locale);
break;
}
case "json": {
- const downloadUrl = await getDownloadUrl("json");
- const json = await fetchJson(downloadUrl);
+ const { url } = await getDownloadResponse("json");
+ const json = await fetchJson(url);
text = JSON.stringify(json, null, 2);
break;
}
case "csv": {
- const downloadUrl = await getDownloadUrl("csv");
- const csv = await fetchText(downloadUrl);
+ const { url } = await getDownloadResponse("csv");
+ const csv = await fetchText(url);
text = csv;
break;
}
case "markdown": {
- const downloadUrl = await getDownloadUrl("json");
- const json = await fetchJson(downloadUrl);
+ const { url } = await getDownloadResponse("json");
+ const json = await fetchJson(url);
text = jsonToMarkdown(json);
break;
}
@@ -158,12 +160,10 @@ export const DownloadAs: React.FC<DownloadActionProps> = (props) => {
<DropdownMenuItem
key={option.label}
onSelect={async () => {
- const downloadUrl = await getDownloadUrl(option.format);
- const ext = option.format;
- const rawName = (props.downloadFileName ?? "").trim();
- const baseName =
- Filenames.withoutExtension(rawName) || "download";
- downloadByURL(downloadUrl, `${baseName}.${ext}`);
+ const { url, filename } = await getDownloadResponse(
+ option.format,
+ );
+ downloadByURL(url, filename);
}}
>
<option.icon className="mo-dropdown-icon" />
diff --git a/frontend/src/components/data-table/schemas.ts b/frontend/src/components/data-table/schemas.ts
index a14104aad7..15790c5ffa 100644
--- a/frontend/src/components/data-table/schemas.ts
+++ b/frontend/src/components/data-table/schemas.ts
@@ -5,7 +5,7 @@ import { rpc } from "@/plugins/core/rpc";
export type DownloadAsArgs = (req: {
format: "csv" | "json" | "parquet";
-}) => Promise<string>;
+}) => Promise<{ url: string; filename: string }>;
export const DownloadAsSchema = rpc
.input(
@@ -13,4 +13,9 @@ export const DownloadAsSchema = rpc
format: z.enum(["csv", "json", "parquet"]),
}),
)
- .output(z.string());
+ .output(
+ z.object({
+ url: z.string(),
+ filename: z.string(),
+ }),
+ );
diff --git a/frontend/src/plugins/impl/DataTablePlugin.tsx b/frontend/src/plugins/impl/DataTablePlugin.tsx
index dbffad2772..74f854b77e 100644
--- a/frontend/src/plugins/impl/DataTablePlugin.tsx
+++ b/frontend/src/plugins/impl/DataTablePlugin.tsx
@@ -200,7 +200,6 @@ interface Data<T> {
hasStableRowId: boolean;
lazy: boolean;
cellHoverTexts?: Record<string, Record<string, string | null>> | null;
- downloadFileName?: string;
}
// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
@@ -286,7 +285,6 @@ export const DataTablePlugin = createPlugin<S>("marimo-table")
// If lazy, this will preload the first page of data
// without user confirmation.
preload: z.boolean().default(false),
- downloadFileName: z.string().optional(),
}),
)
.withFunctions<DataTableFunctions>({
@@ -822,7 +820,6 @@ const DataTableComponent = ({
cellStyles,
hoverTemplate,
cellHoverTexts,
- downloadFileName,
toggleDisplayHeader,
calculate_top_k_rows,
preview_column,
@@ -1077,7 +1074,6 @@ const DataTableComponent = ({
hoverTemplate={hoverTemplate}
cellHoverTexts={cellHoverTexts}
downloadAs={showDownload ? downloadAs : undefined}
- downloadFileName={downloadFileName}
enableSearch={enableSearch}
searchQuery={searchQuery}
onSearchQueryChange={setSearchQuery}
diff --git a/frontend/src/plugins/impl/data-frames/DataFramePlugin.tsx b/frontend/src/plugins/impl/data-frames/DataFramePlugin.tsx
index 35c79bf919..9ae985795f 100644
--- a/frontend/src/plugins/impl/data-frames/DataFramePlugin.tsx
+++ b/frontend/src/plugins/impl/data-frames/DataFramePlugin.tsx
@@ -329,7 +329,6 @@ export const DataFrameComponent = memo(
fieldTypes={field_types}
rowHeaders={row_headers || Arrays.EMPTY}
showDownload={showDownload}
- downloadFileName={dataframeName}
download_as={download_as}
enableSearch={false}
showFilters={false}
diff --git a/frontend/src/stories/dataframe.stories.tsx b/frontend/src/stories/dataframe.stories.tsx
index a181d5f238..e164167262 100644
--- a/frontend/src/stories/dataframe.stories.tsx
+++ b/frontend/src/stories/dataframe.stories.tsx
@@ -41,7 +41,7 @@ export const DataFrame: StoryObj = {
search={Functions.THROW}
host={document.body}
showDownload={false}
- download_as={async () => ""}
+ download_as={async () => ({ url: "", filename: "" })}
lazy={false}
/>
);
diff --git a/marimo/_plugins/ui/_impl/dataframes/dataframe.py b/marimo/_plugins/ui/_impl/dataframes/dataframe.py
index a4d50fe8fd..64da6fc72e 100644
--- a/marimo/_plugins/ui/_impl/dataframes/dataframe.py
+++ b/marimo/_plugins/ui/_impl/dataframes/dataframe.py
@@ -27,6 +27,7 @@ from marimo._plugins.ui._impl.dataframes.transforms.types import (
)
from marimo._plugins.ui._impl.table import (
DownloadAsArgs,
+ DownloadAsResponse,
SearchTableArgs,
SearchTableResponse,
SortArgs,
@@ -40,7 +41,10 @@ from marimo._plugins.ui._impl.tables.table_manager import (
from marimo._plugins.ui._impl.tables.utils import (
get_table_manager,
)
-from marimo._plugins.ui._impl.utils.dataframe import download_as
+from marimo._plugins.ui._impl.utils.dataframe import (
+ download_as,
+ get_bound_name,
+)
from marimo._plugins.validators import (
validate_no_integer_columns,
validate_page_size,
@@ -330,7 +334,7 @@ class dataframe(UIElement[dict[str, Any], DataFrameType]):
total_rows=result.get_num_rows(force=True) or 0,
)
- def _download_as(self, args: DownloadAsArgs) -> str:
+ def _download_as(self, args: DownloadAsArgs) -> DownloadAsResponse:
"""Download the transformed dataframe in the specified format.
Downloads the dataframe with all current transformations applied.
@@ -340,23 +344,25 @@ class dataframe(UIElement[dict[str, Any], DataFrameType]):
format must be one of 'csv', 'json', or 'parquet'.
Returns:
- str: URL to download the data file.
+ DownloadAsResponse: URL and filename for the downloaded file.
Raises:
ValueError: If format is not supported.
"""
- # Get transformed dataframe
df = self._value
-
- # Get the table manager for the transformed data
manager = self._get_cached_table_manager(df, self._limit)
- return download_as(
+
+ bound_filename = get_bound_name(self._id)
+
+ url, filename = download_as(
manager,
args.format,
csv_encoding=self._download_csv_encoding,
csv_separator=self._download_csv_separator,
json_ensure_ascii=self._download_json_ensure_ascii,
+ filename=bound_filename,
)
+ return DownloadAsResponse(url=url, filename=filename)
def _apply_filters_query_sort(
self,
diff --git a/marimo/_plugins/ui/_impl/table.py b/marimo/_plugins/ui/_impl/table.py
index 3bc4293762..5aed70b628 100644
--- a/marimo/_plugins/ui/_impl/table.py
+++ b/marimo/_plugins/ui/_impl/table.py
@@ -54,6 +54,7 @@ from marimo._plugins.ui._impl.utils.dataframe import (
ListOrTuple,
TableData,
download_as,
+ get_bound_name,
)
from marimo._plugins.validators import (
validate_no_integer_columns,
@@ -71,7 +72,6 @@ from marimo._utils.narwhals_utils import (
can_narwhalify_lazyframe,
unwrap_narwhals_dataframe,
)
-from marimo._utils.variable_name import infer_variable_name
if TYPE_CHECKING:
from collections.abc import Sequence
@@ -92,6 +92,12 @@ class DownloadAsArgs:
format: Literal["csv", "json", "parquet"]
+@dataclass
+class DownloadAsResponse:
+ url: str
+ filename: str
+
+
@dataclass
class ColumnSummariesArgs: ...
@@ -506,10 +512,6 @@ class table(
self._max_columns: Optional[int] = None
max_columns_arg: Union[int, str]
- # Infer the variable name before add_selection_column() mutates data,
- # so the identity check still matches the caller's original variable.
- download_file_name = infer_variable_name(data, "download")
-
has_stable_row_id = False
if selection is not None:
data, has_stable_row_id = add_selection_column(data)
@@ -742,7 +744,6 @@ class table(
"max-height": int(max_height)
if max_height is not None
else None,
- "download-file-name": download_file_name,
},
on_change=on_change,
functions=(
@@ -837,7 +838,7 @@ class table(
)
return unwrap_narwhals_dataframe(self._selected_manager.data) # type: ignore[no-any-return]
- def _download_as(self, args: DownloadAsArgs) -> str:
+ def _download_as(self, args: DownloadAsArgs) -> DownloadAsResponse:
"""Download the table data in the specified format.
For cell-selection modes ("single-cell"/"multi-cell"), selection is
@@ -851,7 +852,7 @@ class table(
format must be one of 'csv' or 'json'.
Returns:
- str: URL to download the data file.
+ DownloadAsResponse: URL and filename for the downloaded file.
Raises:
ValueError: If format is not 'csv' or 'json'.
@@ -872,11 +873,16 @@ class table(
else self._searched_manager
)
- # Remove the selection column before downloading
if isinstance(manager_candidate, TableManager):
- return download_as(
- manager_candidate, args.format, drop_marimo_index=True
+ bound_filename = get_bound_name(self._id)
+
+ url, filename = download_as(
+ manager_candidate,
+ args.format,
+ drop_marimo_index=True,
+ filename=bound_filename,
)
+ return DownloadAsResponse(url=url, filename=filename)
else:
raise NotImplementedError(
"Download is not supported for this table format."
diff --git a/marimo/_plugins/ui/_impl/utils/dataframe.py b/marimo/_plugins/ui/_impl/utils/dataframe.py
index 0d0fbad970..d275b32ed3 100644
--- a/marimo/_plugins/ui/_impl/utils/dataframe.py
+++ b/marimo/_plugins/ui/_impl/utils/dataframe.py
@@ -15,12 +15,34 @@ from marimo._runtime.context.types import (
ContextNotInitializedError,
get_context,
)
+from marimo._types.ids import UIElementId
LOGGER = _loggers.marimo_logger()
DEFAULT_CSV_ENCODING = "utf-8"
+def get_bound_name(element_id: UIElementId) -> str | None:
+ """Get the bound variable name for a UI element.
+
+ Looks up the element's bound names from the UI element registry
+ at runtime. Returns the first (alphabetically sorted) bound name,
+ or None if not found.
+
+ Args:
+ element_id: The unique ID of the UI element.
+
+ Returns:
+ The bound variable name, or None if not found.
+ """
+ try:
+ ctx = get_context()
+ bound = sorted(ctx.ui_element_registry.bound_names(element_id))
+ return bound[0] if bound else None
+ except ContextNotInitializedError:
+ return None
+
+
def get_default_csv_encoding() -> str:
"""Get the default CSV encoding from config.
@@ -58,7 +80,8 @@ def download_as(
csv_encoding: str | None = None,
csv_separator: str | None = None,
json_ensure_ascii: bool = True,
-) -> str:
+ filename: str | None = None,
+) -> tuple[str, str]:
"""Download the table data in the specified format.
Args:
@@ -73,13 +96,14 @@ def download_as(
Defaults to "," when not configured.
json_ensure_ascii (bool, optional): Whether to escape non-ASCII characters
in JSON output. Defaults to True.
+ filename (str | None, optional): The filename to use for the downloaded file.
+ Defaults to None, which uses a random filename.
Raises:
ValueError: If unrecognized format.
- NotImplementedError: If the table format is not supported.
Returns:
- str: The URL to download the table data.
+ tuple: (url, user-facing filename with extension) for the downloaded file.
"""
if drop_marimo_index:
# Remove the selection column if exists
@@ -91,17 +115,20 @@ def download_as(
if csv_encoding is not None
else get_default_csv_encoding()
)
- return mo_data.csv(
+ vfile = mo_data.csv(
manager.to_csv(encoding=encoding, separator=csv_separator)
- ).url
+ )
elif ext == "json":
# Use strict JSON to ensure compliance with JSON spec
- return mo_data.json(
+ vfile = mo_data.json(
manager.to_json(
encoding=None, ensure_ascii=json_ensure_ascii, strict_json=True
)
- ).url
+ )
elif ext == "parquet":
- return mo_data.parquet(manager.to_parquet()).url
+ vfile = mo_data.parquet(manager.to_parquet())
else:
raise ValueError("format must be one of 'csv', 'json', or 'parquet'.")
+
+ base_name = filename if filename is not None else "download"
+ return (vfile.url, f"{base_name}.{ext}")
diff --git a/tests/_plugins/ui/_impl/dataframes/test_dataframe.py b/tests/_plugins/ui/_impl/dataframes/test_dataframe.py
index fb66eea05c..56abf7a4e1 100644
--- a/tests/_plugins/ui/_impl/dataframes/test_dataframe.py
+++ b/tests/_plugins/ui/_impl/dataframes/test_dataframe.py
@@ -329,9 +329,8 @@ class TestDataframes:
df = pd.DataFrame({"A": [1, 2], "B": ["こんにちは", "世界"]})
subject = ui.dataframe(df)
- csv_url = subject._download_as(DownloadAsArgs(format="csv"))
+ csv_url = subject._download_as(DownloadAsArgs(format="csv")).url
csv_bytes = from_data_uri(csv_url)[1]
- # Check that BOM is not included
assert not csv_bytes.startswith(b"\xef\xbb\xbf")
@staticmethod
@@ -345,9 +344,9 @@ class TestDataframes:
download_csv_encoding="utf-8-sig",
)
- # CSV should include BOM
- csv_url = subject._download_as(DownloadAsArgs(format="csv"))
+ csv_url = subject._download_as(DownloadAsArgs(format="csv")).url
csv_bytes = from_data_uri(csv_url)[1]
+ # CSV should include BOM
assert csv_bytes.startswith(b"\xef\xbb\xbf")
assert "こんにちは" in csv_bytes.decode("utf-8-sig")
@@ -362,7 +361,7 @@ class TestDataframes:
download_csv_separator=";",
)
- csv_url = subject._download_as(DownloadAsArgs(format="csv"))
+ csv_url = subject._download_as(DownloadAsArgs(format="csv")).url
csv_text = from_data_uri(csv_url)[1].decode("utf-8")
assert "A;B" in csv_text
assert "1;x" in csv_text
@@ -378,8 +377,7 @@ class TestDataframes:
download_json_ensure_ascii=False,
)
- # JSON should preserve characters without BOM when ensure_ascii is False
- json_url = subject._download_as(DownloadAsArgs(format="json"))
+ json_url = subject._download_as(DownloadAsArgs(format="json")).url
json_bytes = from_data_uri(json_url)[1]
assert not json_bytes.startswith(b"\xef\xbb\xbf")
json_text = json_bytes.decode("utf-8")
@@ -401,8 +399,9 @@ class TestDataframes:
)
subject = ui.dataframe(df)
- # no transformations
- download_url = subject._download_as(DownloadAsArgs(format=format_type))
+ download_url = subject._download_as(
+ DownloadAsArgs(format=format_type)
+ ).url
assert download_url.startswith("data:")
data_bytes = from_data_uri(download_url)[1]
@@ -426,8 +425,7 @@ class TestDataframes:
# Apply some transformations (would be done through the UI)
subject._value = df[df["age"] > 27]
- # download with transformations applied
- download_url = subject._download_as(DownloadAsArgs(format="json"))
+ download_url = subject._download_as(DownloadAsArgs(format="json")).url
data_bytes = from_data_uri(download_url)[1]
json_data = json.loads(data_bytes.decode("utf-8"))
@@ -447,7 +445,7 @@ class TestDataframes:
df = pd.DataFrame({"A": [], "B": []})
subject = ui.dataframe(df)
- download_url = subject._download_as(DownloadAsArgs(format="csv"))
+ download_url = subject._download_as(DownloadAsArgs(format="csv")).url
data_bytes = from_data_uri(download_url)[1]
csv_content = data_bytes.decode("utf-8")
@@ -489,7 +487,7 @@ class TestDataframes:
try:
download_url = subject._download_as(
DownloadAsArgs(format=format_type)
- )
+ ).url
assert download_url.startswith("data:")
except Exception as e:
# Some backends might not support all formats
@@ -497,6 +495,49 @@ class TestDataframes:
assert type(subject.value) is type(df)
+ @staticmethod
+ @pytest.mark.skipif(
+ not HAS_DEPS, reason="optional dependencies not installed"
+ )
+ def test_dataframe_download_uses_bound_variable_name() -> None:
+ my_dataframe = pd.DataFrame({"A": [1, 2, 3], "B": ["x", "y", "z"]})
+ subject = ui.dataframe(my_dataframe)
+
+ mock_registry = Mock()
+ mock_registry.bound_names.return_value = {"my_dataframe"}
+
+ mock_ctx = Mock()
+ mock_ctx.ui_element_registry = mock_registry
+
+ mock_vfile = Mock()
+ mock_vfile.url = "data:text/csv;base64,dGVzdA=="
+ mock_vfile.filename = "random_name"
+
+ with (
+ patch(
+ "marimo._runtime.context.get_context",
+ return_value=mock_ctx,
+ ),
+ patch(
+ "marimo._plugins.ui._impl.utils.dataframe.get_context",
+ return_value=mock_ctx,
+ ),
+ patch(
+ "marimo._plugins.ui._impl.utils.dataframe.get_default_csv_encoding",
+ return_value="utf-8",
+ ),
+ patch(
+ "marimo._output.data.data.csv",
+ return_value=mock_vfile,
+ ),
+ ):
+ result = subject._download_as(DownloadAsArgs(format="csv"))
+
+ # The filename should be the bound variable name with extension
+ assert result.filename == "my_dataframe.csv"
+ # The URL should come from mo_data
+ assert result.url == "data:text/csv;base64,dGVzdA=="
+
@staticmethod
@pytest.mark.parametrize(
"df",
diff --git a/tests/_plugins/ui/_impl/test_table.py b/tests/_plugins/ui/_impl/test_table.py
index db4cc56294..c7b59a3932 100644
--- a/tests/_plugins/ui/_impl/test_table.py
+++ b/tests/_plugins/ui/_impl/test_table.py
@@ -1094,12 +1094,6 @@ class TestTableGetValueCounts:
assert value_counts == [ValueCount(value="1", count=2)]
-def test_table_download_file_name() -> None:
- my_data = {"a": [1, 2, 3]}
- t = ui.table(my_data)
- assert t._component_args["download-file-name"] == "my_data"
-
-
def test_table_with_frozen_columns() -> None:
data = {
"a": list(range(20)),
@@ -1276,7 +1270,7 @@ def test_download_as(df: Any) -> None:
"""Helper to download and convert table data to DataFrame."""
download_str = table_instance._download_as(
DownloadAsArgs(format=format_type)
- )
+ ).url
data_bytes = from_data_uri(download_str)[1]
buffer = io.BytesIO(data_bytes)
@@ -1360,7 +1354,7 @@ def test_download_as_ignores_cell_selection() -> None:
# Make a cell selection; download should still include the filtered view
table._convert_value([{"rowId": "0", "columnName": "a"}])
# Use JSON format to avoid optional dependencies
- url = table._download_as(DownloadAsArgs(format="json"))
+ url = table._download_as(DownloadAsArgs(format="json")).url
data_bytes = from_data_uri(url)[1]
rows = json.loads(data_bytes)
assert isinstance(rows, list)