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(export): support PDF output selection (#10376)

Péter Gyarmati9296864bd2d7
diff --git a/frontend/src/components/editor/actions/__tests__/pdf-export.test.ts b/frontend/src/components/editor/actions/__tests__/pdf-export.test.ts
index 5ea72a6f11..c325abacae 100644
--- a/frontend/src/components/editor/actions/__tests__/pdf-export.test.ts
+++ b/frontend/src/components/editor/actions/__tests__/pdf-export.test.ts
@@ -4,35 +4,58 @@ import { describe, expect, it, vi } from "vitest";
import { runServerSidePDFDownload } from "../pdf-export";
describe("runServerSidePDFDownload", () => {
- it("downloads document preset via backend PDF endpoint", async () => {
- const downloadPDF = vi.fn().mockResolvedValue(undefined);
+ it("captures current outputs before downloading the PDF", async () => {
+ const calls: string[] = [];
+ const captureOutputs = vi.fn(async () => {
+ calls.push("capture:start");
+ await Promise.resolve();
+ calls.push("capture:end");
+ });
+ const downloadPDF = vi.fn(async () => {
+ calls.push("download");
+ });
await runServerSidePDFDownload({
- preset: "document",
+ exportOptions: {
+ webpdf: false,
+ preset: "document",
+ includeInputs: true,
+ includeOutputs: true,
+ },
+ captureOutputs,
downloadPDF,
});
+ expect(calls).toEqual(["capture:start", "capture:end", "download"]);
expect(downloadPDF).toHaveBeenCalledWith({
webpdf: false,
preset: "document",
includeInputs: true,
- rasterServer: "static",
+ includeOutputs: true,
});
});
- it("downloads slides preset via backend PDF endpoint", async () => {
+ it("skips browser capture when outputs are excluded", async () => {
+ const captureOutputs = vi.fn().mockResolvedValue(undefined);
const downloadPDF = vi.fn().mockResolvedValue(undefined);
await runServerSidePDFDownload({
- preset: "slides",
+ exportOptions: {
+ webpdf: true,
+ preset: "slides",
+ includeInputs: false,
+ includeOutputs: false,
+ },
+ captureOutputs,
downloadPDF,
});
+ expect(captureOutputs).not.toHaveBeenCalled();
expect(downloadPDF).toHaveBeenCalledWith({
- webpdf: false,
+ webpdf: true,
preset: "slides",
- includeInputs: true,
- rasterServer: "static",
+ includeInputs: false,
+ includeOutputs: false,
});
});
});
diff --git a/frontend/src/components/editor/actions/pdf-export.ts b/frontend/src/components/editor/actions/pdf-export.ts
index f540074db0..37412f3224 100644
--- a/frontend/src/components/editor/actions/pdf-export.ts
+++ b/frontend/src/components/editor/actions/pdf-export.ts
@@ -1,23 +1,23 @@
/* Copyright 2026 Marimo. All rights reserved. */
type Preset = "document" | "slides";
-type DownloadPDF = (opts: {
+interface PDFExportOptions {
webpdf: boolean;
preset: Preset;
includeInputs: boolean;
- rasterServer: "live" | "static";
-}) => Promise<void>;
+ includeOutputs: boolean;
+}
+type DownloadPDF = (opts: PDFExportOptions) => Promise<void>;
export async function runServerSidePDFDownload(opts: {
- preset: Preset;
+ exportOptions: PDFExportOptions;
+ captureOutputs: () => Promise<void>;
downloadPDF: DownloadPDF;
}): Promise<void> {
- const { preset, downloadPDF } = opts;
+ const { exportOptions, captureOutputs, downloadPDF } = opts;
- await downloadPDF({
- webpdf: false,
- preset,
- includeInputs: true,
- rasterServer: "static",
- });
+ if (exportOptions.includeOutputs) {
+ await captureOutputs();
+ }
+ await downloadPDF(exportOptions);
}
diff --git a/frontend/src/components/editor/actions/useNotebookActions.tsx b/frontend/src/components/editor/actions/useNotebookActions.tsx
index 66771f8141..0d416e5dca 100644
--- a/frontend/src/components/editor/actions/useNotebookActions.tsx
+++ b/frontend/src/components/editor/actions/useNotebookActions.tsx
@@ -193,12 +193,18 @@ export function useNotebookActions() {
}
const runDownload = async (progress: ProgressState) => {
- await updateCellOutputsWithScreenshots({
- takeScreenshots: () => takeScreenshots({ progress }),
- updateCellOutputs,
- });
await runServerSidePDFDownload({
- preset,
+ exportOptions: {
+ webpdf: false,
+ preset,
+ includeInputs: true,
+ includeOutputs: true,
+ },
+ captureOutputs: () =>
+ updateCellOutputsWithScreenshots({
+ takeScreenshots: () => takeScreenshots({ progress }),
+ updateCellOutputs,
+ }),
downloadPDF: downloadAsPDF,
});
};
diff --git a/frontend/src/core/export/__tests__/hooks.test.ts b/frontend/src/core/export/__tests__/hooks.test.ts
index e94abd1d2a..0c1a7b4d7d 100644
--- a/frontend/src/core/export/__tests__/hooks.test.ts
+++ b/frontend/src/core/export/__tests__/hooks.test.ts
@@ -648,8 +648,7 @@ describe("updateCellOutputsWithScreenshots", () => {
);
expect(toast).toHaveBeenCalledWith({
title: "Failed to capture cell outputs",
- description:
- "Some outputs may not appear in the PDF. Continuing with export.",
+ description: "Some outputs may be missing from the export. Continuing.",
variant: "danger",
});
});
@@ -679,8 +678,7 @@ describe("updateCellOutputsWithScreenshots", () => {
);
expect(toast).toHaveBeenCalledWith({
title: "Failed to capture cell outputs",
- description:
- "Some outputs may not appear in the PDF. Continuing with export.",
+ description: "Some outputs may be missing from the export. Continuing.",
variant: "danger",
});
});
diff --git a/frontend/src/core/export/hooks.ts b/frontend/src/core/export/hooks.ts
index e622583209..dc0905c1a4 100644
--- a/frontend/src/core/export/hooks.ts
+++ b/frontend/src/core/export/hooks.ts
@@ -112,7 +112,9 @@ interface UseEnrichCellOutputsOptions {
}
/**
- * Take screenshots of cells with HTML outputs. These images will be sent to the backend to be exported to IPYNB.
+ * Capture browser-rendered cell outputs for current-session exports.
+ *
+ * The caller uploads these PNG representations before requesting an export.
* @returns A map of cell IDs to their screenshots data.
*/
export function useEnrichCellOutputs(): (
@@ -221,8 +223,7 @@ export async function updateCellOutputsWithScreenshots(opts: {
Logger.error("Error updating cell outputs with screenshots:", error);
toast({
title: "Failed to capture cell outputs",
- description:
- "Some outputs may not appear in the PDF. Continuing with export.",
+ description: "Some outputs may be missing from the export. Continuing.",
variant: "danger",
});
}
diff --git a/frontend/src/utils/__tests__/download.test.tsx b/frontend/src/utils/__tests__/download.test.tsx
index 74aa680769..121929bb9e 100644
--- a/frontend/src/utils/__tests__/download.test.tsx
+++ b/frontend/src/utils/__tests__/download.test.tsx
@@ -205,9 +205,26 @@ describe("downloadAsPDF", () => {
webpdf: false,
preset: "slides",
includeInputs: true,
- rasterizeOutputs: true,
- rasterScale: 4,
- rasterServer: "static",
+ includeOutputs: true,
+ });
+ });
+
+ it("should send input and output selections", async () => {
+ mockExportAsPDF.mockRejectedValue(new Error("network"));
+
+ await expect(
+ downloadAsPDF({
+ webpdf: true,
+ includeInputs: false,
+ includeOutputs: false,
+ }),
+ ).rejects.toThrow("network");
+
+ expect(mockExportAsPDF).toHaveBeenCalledWith({
+ webpdf: true,
+ preset: "document",
+ includeInputs: false,
+ includeOutputs: false,
});
});
});
diff --git a/frontend/src/utils/download.ts b/frontend/src/utils/download.ts
index d15197c88f..546e1781b2 100644
--- a/frontend/src/utils/download.ts
+++ b/frontend/src/utils/download.ts
@@ -211,18 +211,14 @@ export async function downloadAsPDF(opts: {
webpdf: boolean;
preset?: PDFExportPreset;
includeInputs?: boolean;
- rasterizeOutputs?: boolean;
- rasterScale?: number;
- rasterServer?: "static" | "live";
+ includeOutputs?: boolean;
}) {
const client = getRequestClient();
const {
webpdf,
preset = "document",
includeInputs = true,
- rasterizeOutputs = true,
- rasterScale = 4,
- rasterServer = "static",
+ includeOutputs = true,
} = opts;
try {
@@ -230,9 +226,7 @@ export async function downloadAsPDF(opts: {
webpdf,
preset,
includeInputs,
- rasterizeOutputs,
- rasterScale,
- rasterServer,
+ includeOutputs,
});
downloadExportedFile(exportedFile);
diff --git a/marimo/_schemas/export.py b/marimo/_schemas/export.py
index e0dd6b5dea..8d295cd510 100644
--- a/marimo/_schemas/export.py
+++ b/marimo/_schemas/export.py
@@ -13,7 +13,7 @@ from marimo._schemas.export_options import (
IPYNBExportOptions,
IPYNBSortMode,
MarkdownExportOptions,
- PDFRasterServer,
+ PDFExportOptions,
ServerExportFormat,
)
from marimo._types.ids import CellId_t
@@ -82,9 +82,17 @@ class ExportAsPDFRequest(msgspec.Struct, rename="camel"):
webpdf: bool
preset: ExportPDFPreset = "document"
include_inputs: bool = False
- rasterize_outputs: bool = True
- raster_scale: float = 4.0
- raster_server: PDFRasterServer = "static"
+ include_outputs: bool = True
+
+
+def to_pdf_export_options(
+ request: ExportAsPDFRequest,
+) -> PDFExportOptions:
+ return PDFExportOptions(
+ webpdf=request.webpdf,
+ preset=request.preset,
+ include_inputs=request.include_inputs,
+ )
class ExportedFile(msgspec.Struct, rename="camel"):
diff --git a/marimo/_server/api/endpoints/export.py b/marimo/_server/api/endpoints/export.py
index 61bf121033..c79d420eda 100644
--- a/marimo/_server/api/endpoints/export.py
+++ b/marimo/_server/api/endpoints/export.py
@@ -48,12 +48,12 @@ from marimo._schemas.export import (
to_html_export_options,
to_ipynb_export_options,
to_markdown_export_options,
+ to_pdf_export_options,
)
from marimo._schemas.export_options import (
SERVER_EXPORT_FORMATS,
IPYNBExportOptions,
MarkdownExportOptions,
- PDFExportOptions,
)
from marimo._server.api.deps import AppState
from marimo._server.api.utils import (
@@ -625,12 +625,8 @@ async def export_as_pdf(*, request: Request) -> Response:
export_request = PDFExportRequest(
app=session.app_file_manager.app,
- session_view=session.session_view,
- options=PDFExportOptions(
- webpdf=body.webpdf,
- preset=body.preset,
- include_inputs=body.include_inputs,
- ),
+ session_view=session.session_view if body.include_outputs else None,
+ options=to_pdf_export_options(body),
)
pdf_data = await render_pdf(export_request)
if pdf_data is None:
diff --git a/packages/openapi/api.yaml b/packages/openapi/api.yaml
index 8a19c255aa..b750db0d9c 100644
--- a/packages/openapi/api.yaml
+++ b/packages/openapi/api.yaml
@@ -1785,22 +1785,14 @@ components:
includeInputs:
default: false
type: boolean
+ includeOutputs:
+ default: true
+ type: boolean
preset:
default: document
enum:
- document
- slides
- rasterScale:
- default: 4.0
- type: number
- rasterServer:
- default: static
- enum:
- - live
- - static
- rasterizeOutputs:
- default: true
- type: boolean
webpdf:
type: boolean
required:
diff --git a/packages/openapi/src/api.ts b/packages/openapi/src/api.ts
index d8ab6fc50e..bee1b91950 100644
--- a/packages/openapi/src/api.ts
+++ b/packages/openapi/src/api.ts
@@ -4689,20 +4689,13 @@ export interface components {
ExportAsPDFRequest: {
/** @default false */
includeInputs?: boolean;
+ /** @default true */
+ includeOutputs?: boolean;
/**
* @default document
* @enum {unknown}
*/
preset?: "document" | "slides";
- /** @default 4 */
- rasterScale?: number;
- /**
- * @default static
- * @enum {unknown}
- */
- rasterServer?: "live" | "static";
- /** @default true */
- rasterizeOutputs?: boolean;
webpdf: boolean;
};
/** ExportAsScriptRequest */
diff --git a/tests/_server/api/endpoints/test_export.py b/tests/_server/api/endpoints/test_export.py
index dcd7f43765..0e50c572ed 100644
--- a/tests/_server/api/endpoints/test_export.py
+++ b/tests/_server/api/endpoints/test_export.py
@@ -16,10 +16,11 @@ from marimo import App, __version__
from marimo._ast.app import InternalApp
from marimo._convert.markdown.flavor.base import MarkdownFlavorName
from marimo._dependencies.dependencies import DependencyManager
-from marimo._export.requests import PDFExportRequest, PDFRasterizationRequest
+from marimo._export.requests import PDFExportRequest
from marimo._messaging.cell_output import CellChannel, CellOutput
from marimo._messaging.notification import CellNotification
from marimo._output.utils import uri_encode_component
+from marimo._schemas.export_options import PDFExportOptions
from marimo._session.model import SessionMode
from marimo._types.ids import CellId_t, SessionId
from marimo._utils.platform import is_windows
@@ -66,10 +67,6 @@ def _ipynb_export_app() -> InternalApp:
return InternalApp(app)
-class _CollectorNotWired(Exception):
- pass
-
-
def test_export_availability_requires_auth(client: TestClient) -> None:
response = client.get("/api/export/availability")
@@ -1020,19 +1017,8 @@ def test_update_cell_outputs_empty_request(client: TestClient) -> None:
assert response.json() == {"success": True}
- reason="endpoint does not yet wire up collect_pdf_png_fallbacks",
- raises=_CollectorNotWired,
- strict=True,
-)
- not DependencyManager.nbformat.has()
- or not DependencyManager.nbconvert.has(),
- reason="nbformat or nbconvert not installed",
-)
@with_session(SESSION_ID)
def test_export_pdf_endpoint(client: TestClient) -> None:
- """Test PDF export endpoint."""
from unittest.mock import AsyncMock, patch
session = get_session_manager(client).get_session(SESSION_ID)
@@ -1040,17 +1026,9 @@ def test_export_pdf_endpoint(client: TestClient) -> None:
session.app_file_manager.filename = "test.py"
render_pdf_mock = AsyncMock(return_value=b"mock_pdf_content")
- collect_mock = AsyncMock(return_value={})
-
- with (
- patch(
- "marimo._server.api.endpoints.export.render_pdf",
- render_pdf_mock,
- ),
- patch(
- "marimo._export._pdf_raster.collect_pdf_png_fallbacks",
- collect_mock,
- ),
+ with patch(
+ "marimo._server.api.endpoints.export.render_pdf",
+ render_pdf_mock,
):
response = client.post(
"/api/export/pdf",
@@ -1065,79 +1043,21 @@ def test_export_pdf_endpoint(client: TestClient) -> None:
response.headers["content-disposition"]
== "attachment; filename*=UTF-8''test.pdf"
)
- render_request = render_pdf_mock.await_args.args[0]
- assert isinstance(render_request, PDFExportRequest)
- assert render_request.options.include_inputs is False
- if collect_mock.await_count == 0:
- raise _CollectorNotWired
- collect_mock.assert_awaited_once()
- assert render_request.png_fallbacks == {}
-
-
- reason="endpoint does not yet wire up collect_pdf_png_fallbacks",
- raises=_CollectorNotWired,
- strict=True,
-)
- not DependencyManager.nbformat.has()
- or not DependencyManager.nbconvert.has(),
- reason="nbformat or nbconvert not installed",
-)
-@with_session(SESSION_ID)
-def test_export_pdf_endpoint_webpdf_mode(client: TestClient) -> None:
- """Test PDF export endpoint with webpdf mode."""
- from unittest.mock import AsyncMock, patch
-
- session = get_session_manager(client).get_session(SESSION_ID)
- assert session
- session.app_file_manager.filename = "test.py"
-
- render_pdf_mock = AsyncMock(return_value=b"mock_webpdf_content")
- collect_mock = AsyncMock(return_value={})
-
- with (
- patch(
- "marimo._server.api.endpoints.export.render_pdf",
- render_pdf_mock,
- ),
- patch(
- "marimo._export._pdf_raster.collect_pdf_png_fallbacks",
- collect_mock,
- ),
- ):
- response = client.post(
- "/api/export/pdf",
- headers=HEADERS,
- json={"webpdf": True},
+ render_pdf_mock.assert_awaited_once_with(
+ PDFExportRequest(
+ app=session.app_file_manager.app,
+ session_view=session.session_view,
+ options=PDFExportOptions(
+ webpdf=False,
+ preset="document",
+ include_inputs=False,
+ ),
)
+ )
+
- assert response.status_code == 200
- assert response.content == b"mock_webpdf_content"
- # Verify webpdf=True was passed to exporter
- render_pdf_mock.assert_awaited_once()
- render_request = render_pdf_mock.await_args.args[0]
- assert isinstance(render_request, PDFExportRequest)
- assert render_request.options.webpdf is True
- assert render_request.options.include_inputs is False
- if collect_mock.await_count == 0:
- raise _CollectorNotWired
- collect_mock.assert_awaited_once()
- assert render_request.png_fallbacks == {}
-
-
- reason="endpoint does not yet wire up collect_pdf_png_fallbacks",
- raises=_CollectorNotWired,
- strict=True,
-)
- not DependencyManager.nbformat.has()
- or not DependencyManager.nbconvert.has(),
- reason="nbformat or nbconvert not installed",
-)
@with_session(SESSION_ID)
-def test_export_pdf_endpoint_preserves_slides_preset(
+def test_export_pdf_endpoint_uses_requested_options(
client: TestClient,
) -> None:
from unittest.mock import AsyncMock, patch
@@ -1146,99 +1066,95 @@ def test_export_pdf_endpoint_preserves_slides_preset(
assert session
session.app_file_manager.filename = "test.py"
- render_pdf_mock = AsyncMock(return_value=b"mock_slides_content")
- collect_mock = AsyncMock(
- return_value={"1": "data:image/png;base64,ZmFrZQ=="}
- )
-
- with (
- patch(
- "marimo._server.api.endpoints.export.render_pdf",
- render_pdf_mock,
- ),
- patch(
- "marimo._export._pdf_raster.collect_pdf_png_fallbacks",
- collect_mock,
- ),
+ render_pdf_mock = AsyncMock(return_value=b"mock_pdf_content")
+ with patch(
+ "marimo._server.api.endpoints.export.render_pdf",
+ render_pdf_mock,
):
response = client.post(
"/api/export/pdf",
headers=HEADERS,
- json={"webpdf": False, "preset": "slides"},
+ json={
+ "webpdf": True,
+ "preset": "slides",
+ "includeInputs": False,
+ "includeOutputs": False,
+ },
)
assert response.status_code == 200
- assert response.content == b"mock_slides_content"
- render_pdf_mock.assert_awaited_once()
- render_request = render_pdf_mock.await_args.args[0]
- assert isinstance(render_request, PDFExportRequest)
- assert render_request.options.preset == "slides"
- assert render_request.options.include_inputs is False
- if collect_mock.await_count == 0:
- raise _CollectorNotWired
- collect_mock.assert_awaited_once()
- assert render_request.png_fallbacks == {
- "1": "data:image/png;base64,ZmFrZQ=="
- }
+ render_pdf_mock.assert_awaited_once_with(
+ PDFExportRequest(
+ app=session.app_file_manager.app,
+ session_view=None,
+ options=PDFExportOptions(
+ webpdf=True,
+ preset="slides",
+ include_inputs=False,
+ ),
+ )
+ )
- reason="endpoint does not yet wire up collect_pdf_png_fallbacks",
- raises=_CollectorNotWired,
- strict=True,
-)
- not DependencyManager.nbformat.has()
- or not DependencyManager.nbconvert.has(),
- reason="nbformat or nbconvert not installed",
-)
@with_session(SESSION_ID)
-def test_export_pdf_endpoint_live_raster_uses_live_server_mode(
+def test_export_pdf_endpoint_uses_browser_captured_outputs(
client: TestClient,
) -> None:
from unittest.mock import AsyncMock, patch
- from urllib.parse import parse_qs, urlparse
session = get_session_manager(client).get_session(SESSION_ID)
assert session
- session.app_file_manager.filename = "/tmp/test.py"
+ session.app_file_manager.filename = "test.py"
+ cell_id = CellId_t("test_cell")
+ session.session_view.cell_notifications[cell_id] = CellNotification(
+ cell_id=cell_id,
+ output=CellOutput(
+ channel=CellChannel.OUTPUT,
+ mimetype="text/html",
+ data="<div>current output</div>",
+ ),
+ status="idle",
+ )
- collect_mock = AsyncMock(return_value={})
- render_pdf_mock = AsyncMock(return_value=b"mock_pdf_content")
+ capture_response = client.post(
+ "/api/export/update_cell_outputs",
+ headers=HEADERS,
+ json={
+ "cellIdsToOutput": {
+ cell_id: ["image/png", "data:image/png;base64,ZmFrZQ=="]
+ }
+ },
+ )
+ assert capture_response.status_code == 200
- with (
- patch(
- "marimo._server.api.endpoints.export.render_pdf",
- render_pdf_mock,
- ),
- patch(
- "marimo._export._pdf_raster.collect_pdf_png_fallbacks",
- collect_mock,
- ),
+ render_pdf_mock = AsyncMock(return_value=b"mock_pdf_content")
+ with patch(
+ "marimo._server.api.endpoints.export.render_pdf",
+ render_pdf_mock,
):
response = client.post(
"/api/export/pdf",
headers=HEADERS,
- json={"webpdf": False, "rasterServer": "live"},
+ json={"webpdf": False, "includeOutputs": True},
)
assert response.status_code == 200
render_request = render_pdf_mock.await_args.args[0]
assert isinstance(render_request, PDFExportRequest)
- if collect_mock.await_count == 0:
- raise _CollectorNotWired
- collect_mock.assert_awaited_once()
- raster_request = collect_mock.await_args.args[0]
- assert isinstance(raster_request, PDFRasterizationRequest)
- assert raster_request.options.server_mode == "live"
- assert raster_request.live_page_url is not None
- with raster_request.live_page_url() as live_page_url:
- parsed = urlparse(live_page_url)
- params = parse_qs(parsed.query)
- assert params["session_id"] == [SESSION_ID]
- assert params["kiosk"] == ["true"]
- assert params["file"] == ["/tmp/test.py"]
- assert params["access_token"]
+ assert render_request.session_view is session.session_view
+ captured_output = render_request.session_view.cell_notifications[
+ cell_id
+ ].output
+ assert captured_output is not None
+ assert captured_output == CellOutput(
+ channel=CellChannel.OUTPUT,
+ mimetype="application/vnd.marimo+mimebundle",
+ data={
+ "text/html": "<div>current output</div>",
+ "image/png": "data:image/png;base64,ZmFrZQ==",
+ },
+ timestamp=captured_output.timestamp,
+ )
@with_session(SESSION_ID)
@@ -1254,15 +1170,9 @@ def test_export_pdf_endpoint_returns_error_on_failure(
render_pdf_mock = AsyncMock(return_value=None)
- with (
- patch(
- "marimo._server.api.endpoints.export.render_pdf",
- render_pdf_mock,
- ),
- patch(
- "marimo._export._pdf_raster.collect_pdf_png_fallbacks",
- AsyncMock(return_value={}),
- ),
+ with patch(
+ "marimo._server.api.endpoints.export.render_pdf",
+ render_pdf_mock,
):
response = client.post(
"/api/export/pdf",