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, description: str = '', script: 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) :param title: Title for the figure :param description: Description text with markdown support :param script: Optional script text used to generate the figure

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)
script – Optional script text used to generate the figure
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)[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.patch_figure(figure_url: str, *, admin_override: bool = False, interactive: bool = True, verbose: bool = True) → bool[source]

Patch a figure by updating its rendering code to the latest version

Parameters:

figure_url – The figpack URL to patch
admin_override – If True, allows admins to patch figures they don’t own
interactive – If True, prompts for user confirmation before proceeding
verbose – If True, prints status messages

Returns:

True if successful, False otherwise

Return type:

bool

figpack.revert_patch_figure(figure_url: str, admin_override: bool = False, interactive: bool = True, verbose: bool = True) → bool[source]

Revert a patched figure to its previous rendering code

Parameters:

figure_url – The figpack URL to revert
admin_override – If True, allows admins to revert figures they don’t own
interactive – If True, prompts for user confirmation before proceeding
verbose – If True, prints status messages

Returns:

True if successful, False otherwise

Return type:

bool

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, description: str = '', script: 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) :param title: Title for the figure :param description: Description text with markdown support :param script: Optional script text used to generate the figure

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)
script – Optional script text used to generate the figure
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_and_view_archive(url: str, port: int | None = None) → None[source]

Download a tar.gz/tgz archive from a URL and view it

Parameters:

url – URL to the tar.gz or tgz file
port – Optional port number to serve on

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

figpack.cli.patch_figure(figure_url: str, admin_override: bool = False) → None[source]

CLI wrapper for patching a figure by updating its rendering code to the latest version

Parameters:

figure_url – The figpack URL to patch
api_key – API key for authentication
admin_override – If True, allows admins to patch figures they don’t own

figpack.cli.revert_figure(figure_url: str, admin_override: bool = False) → None[source]

CLI wrapper for reverting a patched figure to its previous rendering code

Parameters:

figure_url – The figpack URL to revert
admin_override – If True, allows admins to revert figures they don’t own

Usage Examples

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