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.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
Unify CSV and TSV export through the backend (#9750)
Kiran Gadhave4cdc57c31098
diff --git a/frontend/src/components/data-table/export-actions.tsx b/frontend/src/components/data-table/export-actions.tsxindex dd6e389364..b44e90a358 100644--- a/frontend/src/components/data-table/export-actions.tsx+++ b/frontend/src/components/data-table/export-actions.tsx@@ -9,7 +9,6 @@ import {TableIcon,} from "lucide-react";import React from "react";-import { useLocale } from "react-aria";import { downloadSizeLimitAtom } from "./download-policy/atoms";import { logNever } from "@/utils/assertNever";import { cn } from "@/utils/cn";@@ -20,7 +19,6 @@ import { Filenames } from "@/utils/filenames";import {jsonParseWithSpecialChar,jsonToMarkdown,- jsonToTSV,} from "@/utils/json/json-parser";import { MissingPackagePrompt } from "../datasources/missing-package-prompt";import { Button } from "../ui/button";@@ -68,7 +66,12 @@ const FILE_TYPES = {},} as const;-const downloadOptions = [FILE_TYPES.CSV, FILE_TYPES.JSON, FILE_TYPES.PARQUET];+const downloadOptions = [+ FILE_TYPES.CSV,+ FILE_TYPES.TSV,+ FILE_TYPES.JSON,+ FILE_TYPES.PARQUET,+];const copyOptions = [FILE_TYPES.TSV,FILE_TYPES.JSON,@@ -79,6 +82,15 @@ const copyOptions = [type DownloadFormat = (typeof downloadOptions)[number]["format"];type CopyFormat = (typeof copyOptions)[number]["format"];+// Each clipboard-copy format fetches from a backend download format, then+// transforms the payload client-side as needed.+const COPY_SOURCE_FORMAT: Record<CopyFormat, DownloadFormat> = {+ csv: "csv",+ tsv: "tsv",+ json: "json",+ markdown: "json",+};+export interface ExportActionProps {downloadAs: (req: { format: DownloadFormat }) => Promise<{url: string;@@ -100,7 +112,6 @@ const labelForCopyFormat = (format: CopyFormat): string =>copyOptions.find((opt) => opt.format === format)?.label ?? format;export const ExportMenu: React.FC<ExportActionProps> = (props) => {- const { locale } = useLocale();const [downloadMenuOpen, setDownloadMenuOpen] = React.useState(false);const policy = useAtomValue(downloadSizeLimitAtom);const overLimit = !!(@@ -213,7 +224,7 @@ export const ExportMenu: React.FC<ExportActionProps> = (props) => {await withLoadingToast(`Preparing ${labelForCopyFormat(format)} for clipboard...`,async () => {- const sourceFormat: DownloadFormat = format === "csv" ? "csv" : "json";+ const sourceFormat = COPY_SOURCE_FORMAT[format];const result = await resolveDownloadUrl(sourceFormat, () => {void handleClipboardCopy(format);});@@ -223,19 +234,15 @@ export const ExportMenu: React.FC<ExportActionProps> = (props) => {let text: string;switch (format) {- case "tsv": {- const json = await fetchJson(result.url);- text = jsonToTSV(json, locale);+ case "tsv":+ case "csv":+ text = await fetchText(result.url);break;- }case "json": {const json = await fetchJson(result.url);text = JSON.stringify(json, null, 2);break;}- case "csv":- text = await fetchText(result.url);- break;case "markdown": {const json = await fetchJson(result.url);text = jsonToMarkdown(json);diff --git a/frontend/src/components/data-table/schemas.ts b/frontend/src/components/data-table/schemas.tsindex 54a43e6f5d..d56ce10b14 100644--- a/frontend/src/components/data-table/schemas.ts+++ b/frontend/src/components/data-table/schemas.ts@@ -4,7 +4,7 @@ import z from "zod";import { rpc } from "@/plugins/core/rpc";export type DownloadAsArgs = (req: {- format: "csv" | "json" | "parquet";+ format: "csv" | "json" | "parquet" | "tsv";}) => Promise<{url: string;filename: string;@@ -15,7 +15,7 @@ export type DownloadAsArgs = (req: {export const DownloadAsSchema = rpc.input(z.object({- format: z.enum(["csv", "json", "parquet"]),+ format: z.enum(["csv", "json", "parquet", "tsv"]),}),).output(diff --git a/frontend/src/utils/__tests__/json-parser.test.ts b/frontend/src/utils/__tests__/json-parser.test.tsindex ce2eccd496..bf101f6aea 100644--- a/frontend/src/utils/__tests__/json-parser.test.ts+++ b/frontend/src/utils/__tests__/json-parser.test.ts@@ -1,10 +1,6 @@/* Copyright 2026 Marimo. All rights reserved. */import { expect, it } from "vitest";-import {- jsonParseWithSpecialChar,- jsonToMarkdown,- jsonToTSV,-} from "../json/json-parser";+import { jsonParseWithSpecialChar, jsonToMarkdown } from "../json/json-parser";it("can jsonParseWithSpecialChar happy path", () => {expect(jsonParseWithSpecialChar('"hello"')).toEqual("hello");@@ -72,70 +68,6 @@ it("can parse bigInts", () => {});});-it("can convert json to tsv with en-US locale", () => {- const locale = "en-US";-- expect(jsonToTSV([], locale)).toEqual("");-- expect(jsonToTSV([{ a: 1, b: 2 }], locale)).toEqual("a\tb\n1\t2");-- expect(- jsonToTSV(- [- { a: 1, b: 2 },- { a: 3, b: 4 },- ],- locale,- ),- ).toEqual("a\tb\n1\t2\n3\t4");-- // Does not handle sparse arrays- expect(jsonToTSV([{ a: 1 }, { a: 2, b: 3 }], locale)).toMatchInlineSnapshot(- '"a\n1\n2"',- );-- // Handles special characters- expect(- jsonToTSV([{ a: "hello\tworld", b: "new\nline" }], locale),- ).toMatchInlineSnapshot('"a\tb\nhello\tworld\tnew\nline"');-- // Handles floats with en-US locale (uses . as decimal separator)- expect(jsonToTSV([{ a: 1.5, b: 2.7 }], locale)).toEqual("a\tb\n1.5\t2.7");-});--it("can convert json to tsv with de-DE locale", () => {- const locale = "de-DE";-- // Handles floats with de-DE locale (uses , as decimal separator)- expect(jsonToTSV([{ a: 1.5, b: 2.7 }], locale)).toEqual("a\tb\n1,5\t2,7");-- // Handles integers (no change)- expect(jsonToTSV([{ a: 1, b: 2 }], locale)).toEqual("a\tb\n1\t2");-});--it("can convert json to tsv with fr-FR locale", () => {- const locale = "fr-FR";-- // Handles floats with fr-FR locale (uses , as decimal separator)- expect(jsonToTSV([{ a: 3.14, b: 2.123_45 }], locale)).toEqual(- "a\tb\n3,14\t2,12345",- );-});--it("handles null and undefined values in TSV", () => {- const locale = "en-US";-- expect(jsonToTSV([{ a: null, b: undefined, c: 1 }], locale)).toEqual(- "a\tb\tc\n\t\t1",- );-});--it("handles NaN values in TSV", () => {- const locale = "en-US";-- expect(jsonToTSV([{ a: Number.NaN, b: 1 }], locale)).toEqual("a\tb\nNaN\t1");-});-it("can convert json to markdown - basic table", () => {expect(jsonToMarkdown([])).toMatchInlineSnapshot(`""`);diff --git a/frontend/src/utils/json/json-parser.ts b/frontend/src/utils/json/json-parser.tsindex 20024a1ae0..0fcd17ed62 100644--- a/frontend/src/utils/json/json-parser.ts+++ b/frontend/src/utils/json/json-parser.ts@@ -66,36 +66,6 @@ export function jsonParseWithSpecialChar<T = unknown>(}}-/**- * Formats a value for TSV export, respecting user's locale for numbers- */-function formatValueForTSV(value: unknown, locale: string): string {- if (value === null || value === undefined) {- return "";- }- if (typeof value === "number" && !Number.isNaN(value)) {- // Use toLocaleString to format numbers according to user's locale- // This will use the appropriate decimal separator (e.g., "," in European locales)- return value.toLocaleString(locale, {- useGrouping: false,- maximumFractionDigits: 20,- });- }- return String(value);-}--export function jsonToTSV(json: Record<string, unknown>[], locale: string) {- if (json.length === 0) {- return "";- }-- const keys = Object.keys(json[0]);- const values = json.map((row) =>- keys.map((key) => formatValueForTSV(row[key], locale)).join("\t"),- );- return `${keys.join("\t")}\n${values.join("\n")}`;-}-/*** Converts JSON data to a Markdown table format* Detects URLs and converts them to markdown links [url](url)diff --git a/marimo/_plugins/ui/_impl/dataframes/dataframe.py b/marimo/_plugins/ui/_impl/dataframes/dataframe.pyindex 8fdc41674f..d7a41748aa 100644--- a/marimo/_plugins/ui/_impl/dataframes/dataframe.py+++ b/marimo/_plugins/ui/_impl/dataframes/dataframe.py@@ -41,6 +41,9 @@ from marimo._plugins.ui._impl.tables.utils import (get_table_manager,)from marimo._plugins.ui._impl.utils.dataframe import (+ DelimitedOptions,+ DownloadOptions,+ JsonOptions,download_as,get_bound_name,)@@ -348,7 +351,7 @@ class dataframe(UIElement[dict[str, Any], DataFrameType]):Args:args (DownloadAsArgs): Arguments specifying the download format.- format must be one of 'csv', 'json', or 'parquet'.+ format must be one of 'csv', 'tsv', 'json', or 'parquet'.Returns:DownloadAsResponse: URL and filename for the downloaded file.@@ -364,9 +367,15 @@ class dataframe(UIElement[dict[str, Any], DataFrameType]):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,+ options=DownloadOptions(+ delimited=DelimitedOptions(+ encoding=self._download_csv_encoding,+ separator=self._download_csv_separator,+ ),+ json=JsonOptions(+ ensure_ascii=self._download_json_ensure_ascii+ ),+ ),filename=bound_filename,)return DownloadAsResponse(url=url, filename=filename)diff --git a/marimo/_plugins/ui/_impl/table.py b/marimo/_plugins/ui/_impl/table.pyindex e8a06ad1d9..b23c599672 100644--- a/marimo/_plugins/ui/_impl/table.py+++ b/marimo/_plugins/ui/_impl/table.py@@ -92,7 +92,7 @@ class TableSearchError(Exception):@dataclassclass DownloadAsArgs:- format: Literal["csv", "json", "parquet"]+ format: Literal["csv", "tsv", "json", "parquet"]@dataclass@@ -976,7 +976,7 @@ class table(Args:args (DownloadAsArgs): The requested download format. Must be- one of `'csv'`, `'json'`, or `'parquet'`.+ one of `'csv'`, `'tsv'`, `'json'`, or `'parquet'`.Returns:DownloadAsResponse: Either a success response with `url` anddiff --git a/marimo/_plugins/ui/_impl/utils/dataframe.py b/marimo/_plugins/ui/_impl/utils/dataframe.pyindex a724bc0cbe..2ef12554d8 100644--- a/marimo/_plugins/ui/_impl/utils/dataframe.py+++ b/marimo/_plugins/ui/_impl/utils/dataframe.py@@ -1,7 +1,8 @@# Copyright 2026 Marimo. All rights reserved.from __future__ import annotations-from typing import Any, TypeVar, Union+from dataclasses import dataclass, field+from typing import TYPE_CHECKING, Any, TypeVar, Unionfrom narwhals.typing import IntoDataFrame, IntoLazyFrame@@ -17,6 +18,9 @@ from marimo._runtime.context.types import ()from marimo._types.ids import UIElementId+if TYPE_CHECKING:+ from collections.abc import Callable+LOGGER = _loggers.marimo_logger()DEFAULT_CSV_ENCODING = "utf-8"@@ -77,31 +81,108 @@ TableData = Union[]+@dataclass(frozen=True)+class DelimitedOptions:+ """Output options shared by delimited-text formats (CSV, TSV).++ Attributes:+ encoding: Text encoding for the output bytes. Falls back to the+ runtime config value (or "utf-8") when None.+ separator: Field separator. Ignored by formats that pin their own+ separator (e.g. TSV always uses a tab).+ """++ encoding: str | None = None+ separator: str | None = None+++@dataclass(frozen=True)+class JsonOptions:+ """Output options for the JSON format.++ Attributes:+ ensure_ascii: Whether to escape non-ASCII characters.+ """++ ensure_ascii: bool = True+++@dataclass(frozen=True)+class DownloadOptions:+ """Per-format output options for `download_as`."""++ delimited: DelimitedOptions = field(default_factory=DelimitedOptions)+ json: JsonOptions = field(default_factory=JsonOptions)+++@dataclass(frozen=True)+class _ExportFormat:+ extension: str+ serialize: Callable[[TableManager[Any], DownloadOptions], bytes]+++def _serialize_delimited(+ separator_override: str | None,+) -> Callable[[TableManager[Any], DownloadOptions], bytes]:+ def serialize(+ manager: TableManager[Any], options: DownloadOptions+ ) -> bytes:+ encoding = options.delimited.encoding or get_default_csv_encoding()+ separator = (+ separator_override+ if separator_override is not None+ else options.delimited.separator+ )+ return manager.to_csv(encoding=encoding, separator=separator)++ return serialize+++def _serialize_json(+ manager: TableManager[Any], options: DownloadOptions+) -> bytes:+ # Use strict JSON to ensure compliance with JSON spec+ return manager.to_json(+ encoding=None,+ ensure_ascii=options.json.ensure_ascii,+ strict_json=True,+ )+++def _serialize_parquet(+ manager: TableManager[Any], _options: DownloadOptions+) -> bytes:+ return manager.to_parquet()+++_EXPORT_FORMATS: dict[str, _ExportFormat] = {+ "csv": _ExportFormat("csv", _serialize_delimited(None)),+ "tsv": _ExportFormat("tsv", _serialize_delimited("\t")),+ "json": _ExportFormat("json", _serialize_json),+ "parquet": _ExportFormat("parquet", _serialize_parquet),+}++def download_as(manager: TableManager[Any],ext: str,drop_marimo_index: bool = False,- csv_encoding: str | None = None,- csv_separator: str | None = None,- json_ensure_ascii: bool = True,+ options: DownloadOptions | None = None,filename: str | None = None,) -> tuple[str, str]:"""Download the table data in the specified format.Args:manager (TableManager[Any]): The table manager to download.- ext (str): The format to download the table data in.- drop_marimo_index (bool, optional): Whether to drop the marimo selection column.- Defaults to False.- csv_encoding (str | None, optional): Encoding used when generating CSV bytes.- Defaults to the runtime config value (or "utf-8" if not configured).- Ignored for non-CSV formats.- csv_separator (str | None, optional): Separator used in CSV downloads.- 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.+ ext (str): The format to download the table data in. One of+ `csv`, `tsv`, `json`, or `parquet`.+ drop_marimo_index (bool, optional): Whether to drop the marimo+ selection column. Defaults to False.+ options (DownloadOptions | None, optional): Per-format output+ options (delimited encoding/separator, JSON ascii escaping).+ Defaults to each format's defaults.+ filename (str | None, optional): The filename to use for the+ downloaded file. Defaults to None, which uses a random filename.Returns:tuple: (url, user-facing filename with extension) for the downloaded file.@@ -109,29 +190,18 @@ def download_as(Raises:ValueError: If unrecognized format."""+ options = options or DownloadOptions()if drop_marimo_index:# Remove the selection column if existsmanager = manager.drop_columns([INDEX_COLUMN_NAME])- if ext == "csv":- encoding = (- csv_encoding- if csv_encoding is not None- else get_default_csv_encoding()- )- payload = manager.to_csv(encoding=encoding, separator=csv_separator)- vfile = mo_data.csv(payload)- elif ext == "json":- # Use strict JSON to ensure compliance with JSON spec- payload = manager.to_json(- encoding=None, ensure_ascii=json_ensure_ascii, strict_json=True- )- vfile = mo_data.json(payload)- elif ext == "parquet":- payload = manager.to_parquet()- vfile = mo_data.parquet(payload)- else:- raise ValueError("format must be one of 'csv', 'json', or 'parquet'.")+ fmt = _EXPORT_FORMATS.get(ext)+ if fmt is None:+ allowed = ", ".join(map(repr, _EXPORT_FORMATS))+ raise ValueError(f"format must be one of {allowed}.")+ vfile = mo_data.any_data(+ fmt.serialize(manager, options), ext=fmt.extension+ )base_name = filename if filename is not None else "download"- return (vfile.url, f"{base_name}.{ext}")+ return (vfile.url, f"{base_name}.{fmt.extension}")diff --git a/tests/_plugins/ui/_impl/dataframes/test_dataframe.py b/tests/_plugins/ui/_impl/dataframes/test_dataframe.pyindex 666e3de949..da83e25dc8 100644--- a/tests/_plugins/ui/_impl/dataframes/test_dataframe.py+++ b/tests/_plugins/ui/_impl/dataframes/test_dataframe.py@@ -392,7 +392,7 @@ class TestDataframes:@pytest.mark.skipif(not HAS_DEPS, reason="optional dependencies not installed")- @pytest.mark.parametrize("format_type", ["csv", "json", "parquet"])+ @pytest.mark.parametrize("format_type", ["csv", "tsv", "json", "parquet"])def test_dataframe_download_formats(format_type) -> None:df = pd.DataFrame({@@ -411,6 +411,25 @@ class TestDataframes:assert len(data_bytes) > 0assert type(subject.value) is type(df)+ @staticmethod+ @pytest.mark.skipif(+ not HAS_DEPS, reason="optional dependencies not installed"+ )+ def test_dataframe_download_tsv_ignores_csv_separator() -> None:+ # download_csv_separator configures CSV only; TSV always uses a tab.+ df = pd.DataFrame({"a": [1, 2], "b": [3, 4]})+ subject = ui.dataframe(df, download_csv_separator=";")++ tsv = from_data_uri(+ subject._download_as(DownloadAsArgs(format="tsv")).url+ )[1].decode("utf-8")+ csv = from_data_uri(+ subject._download_as(DownloadAsArgs(format="csv")).url+ )[1].decode("utf-8")++ assert tsv.splitlines()[0] == "a\tb"+ assert csv.splitlines()[0] == "a;b"+@staticmethod@pytest.mark.skipif(not HAS_DEPS, reason="optional dependencies not installed"@@ -466,9 +485,7 @@ class TestDataframes:with pytest.raises(ValueError) as exc_info:subject._download_as(DownloadAsArgs(format="xml"))- assert "format must be one of 'csv', 'json', or 'parquet'" in str(- exc_info.value- )+ assert "format must be one of" in str(exc_info.value)assert type(subject.value) is type(df)@staticmethod@@ -485,7 +502,7 @@ class TestDataframes:subject = ui.dataframe(df)# Test that download works with different dataframe backends- for format_type in ["csv", "json", "parquet"]:+ for format_type in ["csv", "tsv", "json", "parquet"]:try:download_url = subject._download_as(DownloadAsArgs(format=format_type)@@ -529,7 +546,7 @@ class TestDataframes:return_value="utf-8",),patch(- "marimo._output.data.data.csv",+ "marimo._output.data.data.any_data",return_value=mock_vfile,),):diff --git a/tests/_plugins/ui/_impl/test_table.py b/tests/_plugins/ui/_impl/test_table.pyindex dde9c1c0ce..557231e21e 100644--- a/tests/_plugins/ui/_impl/test_table.py+++ b/tests/_plugins/ui/_impl/test_table.py@@ -1423,7 +1423,7 @@ def test_show_download(df: Any) -> None:assert table_false._component_args["show-download"] is False-DOWNLOAD_FORMATS = ["csv", "json", "parquet"]+DOWNLOAD_FORMATS = ["csv", "tsv", "json", "parquet"]# Parquet export requires pandas+pyarrow or polars (see the `_download_as`# short-circuit in `table.py`). In environments without those — e.g. the@@ -1432,7 +1432,7 @@ _CAN_EXPORT_PARQUET = DependencyManager.polars.has() or (DependencyManager.pandas.has() and DependencyManager.pyarrow.has())_TESTABLE_DOWNLOAD_FORMATS = (- DOWNLOAD_FORMATS if _CAN_EXPORT_PARQUET else ["csv", "json"]+ DOWNLOAD_FORMATS if _CAN_EXPORT_PARQUET else ["csv", "tsv", "json"])@@ -1506,6 +1506,22 @@ def test_download_as(df: Any) -> None:import pyarrow.csv as pacsvreturn pacsv.read_csv(buffer)+ elif format_type == "tsv":+ if DependencyManager.pandas.has():+ import pandas as pd++ return pd.read_csv(buffer, sep="\t")+ elif DependencyManager.polars.has():+ import polars as pl++ return pl.read_csv(buffer, separator="\t")+ elif DependencyManager.pyarrow.has():+ import pyarrow.csv as pacsv++ return pacsv.read_csv(+ buffer,+ parse_options=pacsv.ParseOptions(delimiter="\t"),+ )raise ValueError(f"Unsupported format: {format_type}")# Test base downloads (full data)@@ -1655,7 +1671,7 @@ def test_download_as_for_supported_cell_selection() -> None:)@pytest.mark.parametrize("fmt",- ["csv", "json", "parquet"],+ ["csv", "tsv", "json", "parquet"],)def test_download_as_for_dataframes(df: Any, fmt: str) -> None:table = ui.table(df)diff --git a/tests/_plugins/ui/_impl/utils/test_dataframe_utils.py b/tests/_plugins/ui/_impl/utils/test_dataframe_utils.pyindex b6a2a5c0bd..7e7f3fb319 100644--- a/tests/_plugins/ui/_impl/utils/test_dataframe_utils.py+++ b/tests/_plugins/ui/_impl/utils/test_dataframe_utils.py@@ -95,6 +95,48 @@ def test_get_default_csv_encoding():assert get_default_csv_encoding() == DEFAULT_CSV_ENCODING+def test_download_as_tsv_uses_tab_separator() -> None:+ from marimo._plugins.ui._impl.tables.default_table import (+ DefaultTableManager,+ )+ from marimo._plugins.ui._impl.utils.dataframe import download_as+ from marimo._utils.data_uri import from_data_uri++ manager = DefaultTableManager([{"a": 1, "b": 2}, {"a": 3, "b": 4}])+ url, filename = download_as(manager, "tsv")++ assert filename.endswith(".tsv")+ mimetype, payload = from_data_uri(url)+ # The virtual file carries the tsv mimetype, not csv.+ assert mimetype == "text/tab-separated-values"+ text = payload.decode("utf-8")+ assert text.splitlines()[0] == "a\tb"+ assert "1\t2" in text+++def test_download_as_csv_honors_separator_option() -> None:+ from marimo._plugins.ui._impl.tables.default_table import (+ DefaultTableManager,+ )+ from marimo._plugins.ui._impl.utils.dataframe import (+ DelimitedOptions,+ DownloadOptions,+ download_as,+ )+ from marimo._utils.data_uri import from_data_uri++ manager = DefaultTableManager([{"a": 1, "b": 2}])+ url, filename = download_as(+ manager,+ "csv",+ options=DownloadOptions(delimited=DelimitedOptions(separator=";")),+ )++ assert filename.endswith(".csv")+ text = from_data_uri(url)[1].decode("utf-8")+ assert text.splitlines()[0] == "a;b"++def test_union_tolerates_string_type_aliases() -> None:"""Verify that Union[] handles string-valued type aliases (narwhals compat).