API Reference

This section provides detailed API documentation for figpack.

Core Modules

figpack - A Python package for creating shareable, interactive visualizations in the browser

class figpack.ExtensionView(*, extension: FigpackExtension, view_type: str)[source]

Bases: FigpackView

Base class for views that are rendered by figpack extensions

write_to_zarr_group(group: Group) → None[source]

Write the extension view metadata to a Zarr group. Subclasses should call super().write_to_zarr_group(group) first, then add their own data.

Parameters:

group – Zarr group to write data into

class figpack.FigpackExtension(*, name: str, javascript_code: str, additional_files: Dict[str, str] | None = None, version: str = '1.0.0')[source]

Bases: object

Base class for figpack extensions that provide custom view components

get_additional_filenames() → Dict[str, str][source]

Get the filenames for additional JavaScript files

Returns:

Dictionary mapping original filenames to safe filenames

get_javascript_filename() → str[source]

Get the filename that should be used for this extension’s JavaScript file

Returns:

Filename for the extension JavaScript file

class figpack.FigpackView[source]

Bases: object

Base class for all figpack visualization components

save(output_path: str, *, title: str) → None[source]

Save as figure either to a folder or to a .tar.gz file :param output_path: Output path (destination folder or .tar.gz file path)

show(*, title: str, description: str | None = None, port: int | None = None, open_in_browser: bool | None = None, upload: bool | None = None, inline: bool | None = None, inline_height: int = 600, ephemeral: bool | None = None, allow_origin: str | None = None, wait_for_input: bool | None = None, _dev: bool | None = None)[source]

Display a figpack view component with intelligent environment detection and flexible display options. See https://flatironinstitute.github.io/figpack/show_function.html for complete documentation.

Automatically adapts behavior based on context (Jupyter, Colab, JupyterHub, standalone). Display modes include local browser, inline notebook, and remote upload with ephemeral options. Environment variables (FIGPACK_UPLOAD, FIGPACK_INLINE, FIGPACK_OPEN_IN_BROWSER) can control default behaviors.

Parameters:

  • title – Title for browser tab and figure (required)

  • description – Description text with markdown support (optional)

  • port – Local server port, random if None

  • open_in_browser – Auto-open in browser, auto-detects by environment

  • upload – Upload figure to figpack servers, auto-detects by environment

  • ephemeral – Use temporary figure for cloud notebooks, auto-detects

  • inline – Display inline in notebook, auto-detects by environment

  • inline_height – Height in pixels for inline display (default: 600)

  • allow_origin – CORS allow-origin header for local server

  • wait_for_input – Wait for Enter before continuing, auto-detects

  • _dev – Developer mode for figpack development

write_to_zarr_group(group: Group) → None[source]

Write the view data to a Zarr group. Must be implemented by subclasses.

Parameters:

group – Zarr group to write data into

class figpack.Group(zarr_group: Group)[source]

Bases: object

property attrs: Dict[str, Any]
create_dataset(name: str, *, data=<object object>, dtype=<object object>, chunks=<object object>, compressor=<object object>) → None[source]
create_group(name: str) → Group[source]
figpack.view_figure(figure_path: str, port: int | None = None) → None[source]

Extract and serve a figure archive locally

Parameters:

  • figure_path – Path to a .tar.gz archive file or a directory

  • port – Optional port number to serve on

Views

Core Views

Core Functionality

The core functionality includes the essential show() function used to display and share visualizations. For detailed documentation of this crucial function and all its configuration options, see the show() function reference.

class figpack.core.ExtensionView(*, extension: FigpackExtension, view_type: str)[source]

Bases: FigpackView

Base class for views that are rendered by figpack extensions

write_to_zarr_group(group: Group) → None[source]

Write the extension view metadata to a Zarr group. Subclasses should call super().write_to_zarr_group(group) first, then add their own data.

Parameters:

group – Zarr group to write data into

class figpack.core.FigpackExtension(*, name: str, javascript_code: str, additional_files: Dict[str, str] | None = None, version: str = '1.0.0')[source]

Bases: object

Base class for figpack extensions that provide custom view components

get_additional_filenames() → Dict[str, str][source]

Get the filenames for additional JavaScript files

Returns:

Dictionary mapping original filenames to safe filenames

get_javascript_filename() → str[source]

Get the filename that should be used for this extension’s JavaScript file

Returns:

Filename for the extension JavaScript file

class figpack.core.FigpackView[source]

Bases: object

Base class for all figpack visualization components

save(output_path: str, *, title: str) → None[source]

Save as figure either to a folder or to a .tar.gz file :param output_path: Output path (destination folder or .tar.gz file path)

show(*, title: str, description: str | None = None, port: int | None = None, open_in_browser: bool | None = None, upload: bool | None = None, inline: bool | None = None, inline_height: int = 600, ephemeral: bool | None = None, allow_origin: str | None = None, wait_for_input: bool | None = None, _dev: bool | None = None)[source]

Display a figpack view component with intelligent environment detection and flexible display options. See https://flatironinstitute.github.io/figpack/show_function.html for complete documentation.

Automatically adapts behavior based on context (Jupyter, Colab, JupyterHub, standalone). Display modes include local browser, inline notebook, and remote upload with ephemeral options. Environment variables (FIGPACK_UPLOAD, FIGPACK_INLINE, FIGPACK_OPEN_IN_BROWSER) can control default behaviors.

Parameters:

  • title – Title for browser tab and figure (required)

  • description – Description text with markdown support (optional)

  • port – Local server port, random if None

  • open_in_browser – Auto-open in browser, auto-detects by environment

  • upload – Upload figure to figpack servers, auto-detects by environment

  • ephemeral – Use temporary figure for cloud notebooks, auto-detects

  • inline – Display inline in notebook, auto-detects by environment

  • inline_height – Height in pixels for inline display (default: 600)

  • allow_origin – CORS allow-origin header for local server

  • wait_for_input – Wait for Enter before continuing, auto-detects

  • _dev – Developer mode for figpack development

write_to_zarr_group(group: Group) → None[source]

Write the view data to a Zarr group. Must be implemented by subclasses.

Parameters:

group – Zarr group to write data into

Command Line Interface

Command-line interface for figpack

figpack.cli.download_figure(figure_url: str, dest_path: str) → None[source]

Download a figure from a figpack URL and save as tar.gz

Parameters:

  • figure_url – The figpack URL

  • dest_path – Destination path for the tar.gz file

figpack.cli.download_file(base_url: str, file_info: Dict, temp_dir: Path) → Tuple[str, bool][source]

Download a single file from the figure

Parameters:

  • base_url – The base URL for the figure

  • file_info – Dictionary with ‘path’ and ‘size’ keys

  • temp_dir – Temporary directory to download to

Returns:

Tuple of (file_path, success)

figpack.cli.get_figure_base_url(figure_url: str) → str[source]

Get the base URL from any figpack URL

Parameters:

figure_url – Any figpack URL (may or may not end with /index.html)

Returns:

The base URL for the figure directory

Return type:

str

figpack.cli.handle_extensions_command(args)[source]

Handle extensions subcommands

figpack.cli.main()[source]

Main CLI entry point

Usage Examples

For practical examples of using the API, see the Examples section.