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 = '') → 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)

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, description: 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)

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_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.handle_find_by_source_url(args) → None[source]

Handle the find-by-source-url command

Queries the API for a figure URL by its source URL.

figpack.cli.handle_upload_from_source_url(args) → None[source]

Handle the upload-from-source-url command

Downloads a tar.gz/tgz file from a URL, extracts it, and uploads it as a new figure with the source URL set.

figpack.cli.main()[source]: Main CLI entry point

Usage Examples

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