annie.pages.download

Save a generated document to the user’s machine, with their choice of folder and name.

Annie’s server runs where the data is — often inside a Docker container — so a server-side folder picker would browse the wrong filesystem. The browser is where the person is, so the save happens there: Chromium browsers (Chrome, Edge, Brave, …) open the operating system’s native Save as dialog through the File System Access API, starting in the user’s Documents folder with the suggested name prefilled. Browsers without it (Firefox, Safari) fall back to a normal download using the suggested name. The content is generated on the server, fetched by the browser from a small route, and written to disk there — server → browser → disk — so local runs and Docker behave identically.

Attributes

MIME_TYPES

Extension → MIME type for the formats Annie exports.

Functions

sanitize_filename(→ str)	Make name a safe file name that ends in .extension.
save_from_url_js(→ str)	Return a click handler that fetches url and saves it where the user picks.
attach_save(→ None)	Make clicking element open the native Save dialog straight away.
export_menu_item(→ nicegui.ui.menu_item)	Add a menu entry that opens the native Save dialog straight away when clicked.

Module Contents

annie.pages.download.MIME_TYPES: dict[str, str]

Extension → MIME type for the formats Annie exports.

annie.pages.download.sanitize_filename(name: str, *, extension: str, default_stem: str) → str

Make name a safe file name that ends in .extension.

Path separators and characters illegal on Windows are replaced, surrounding dots and spaces trimmed, an empty result falls back to default_stem, and the extension is forced (added if missing, never doubled).

Parameters:

• name – The name the user typed (may be empty or contain a path).

• extension – The required extension without the dot, e.g. "csv".

• default_stem – Stem to use when name has nothing usable.

Returns:

A file name such as annie_events_clip1.csv.

annie.pages.download.save_from_url_js(filename: str, url: str, mime: str) → str

Return a click handler that fetches url and saves it where the user picks.

The handler runs client-side inside the click: it fetches the file first (a local, millisecond request, well inside the browser’s transient-activation window), then opens the native Save dialog with filename prefilled and writes the file. A 204 response means “nothing to export” and shows a notice instead of an empty file. Cancelling the dialog is silent. Browsers without showSaveFilePicker (Firefox, Safari) fall back to a normal download under filename.

Parameters:

• filename – Suggested file name, already sanitised.

• url – Same-origin URL returning the file’s content (text or binary).

• mime – MIME type, e.g. "text/csv".

Returns:

A JavaScript arrow function (as a string) for Element.on(..., js_handler=...).

annie.pages.download.attach_save(element: nicegui.ui.element, *, filename: str, url: str, extension: str) → None

Make clicking element open the native Save dialog straight away.

Parameters:

• element – A button or menu item.

• filename – Default file name offered in the Save dialog.

• url – Same-origin URL serving the file (see save_from_url_js()).

• extension – File extension without the dot (selects the MIME type).

annie.pages.download.export_menu_item(label: str, *, filename: str, url: str, extension: str) → nicegui.ui.menu_item

Add a menu entry that opens the native Save dialog straight away when clicked.

Parameters:

• label – Menu text.

• filename – Default file name offered in the Save dialog.

• url – Same-origin URL serving the file (see save_from_url_js()).

• extension – File extension without the dot (selects the MIME type).

Returns:

The created menu item.