figpack 0.2.3__py3-none-any.whl → 0.2.5__py3-none-any.whl

figpack/core/figpack_view.py

@@ -2,6 +2,9 @@
 Base view class for figpack visualization components
 """
 
+import os
+import random
+import string
 from typing import Union
 
 import zarr
@@ -15,31 +18,38 @@ class FigpackView:
     def show(
         self,
         *,
+        title: str,
+        description: Union[str, None] = None,
         port: Union[int, None] = None,
-        open_in_browser: bool = False,
-        allow_origin: Union[str, None] = None,
+        open_in_browser: Union[bool, None] = None,
         upload: Union[bool, None] = None,
-        ephemeral: Union[bool, None] = None,
-        _dev: bool = False,
-        title: Union[str, None] = None,
-        description: Union[str, None] = None,
         inline: Union[bool, None] = None,
         inline_height: int = 600,
+        ephemeral: Union[bool, None] = None,
+        allow_origin: Union[str, None] = None,
+        wait_for_input: Union[bool, None] = None,
+        _dev: Union[bool, None] = None,
     ):
         """
-        Display the visualization component
+        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.
 
         Args:
-            port: Port number for local server
-            open_in_browser: Whether to open in browser automatically
-            allow_origin: CORS allow origin header
-            upload: Whether to upload the figure
-            ephemeral: Whether to upload as ephemeral figure (None=auto-detect, True=force ephemeral, False=force regular)
-            _dev: Development mode flag
-            title: Title for the browser tab and figure
-            description: Description text (markdown supported) for the figure
-            inline: Whether to display inline in notebook (None=auto-detect, True=force inline, False=force browser)
-            inline_height: Height in pixels for inline iframe display (default: 600)
+            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
         """
         from ._show_view import (
             _show_view,
@@ -48,25 +58,55 @@ class FigpackView:
             _is_in_jupyterhub,
         )
 
-        if ephemeral is None and upload is None:
-            # If we haven't specified both, then let's check if we're in a notebook in a non-local environment
+        # determine upload
+        if upload is None:
+            upload = os.environ.get("FIGPACK_UPLOAD") == "1"
+        else:
+            if upload is True and ephemeral is True:
+                # ephemeral is reserved for the case where we don't specify upload
+                # and we are in a notebook in a remote environment such as
+                # colab or jupyterhub
+                raise ValueError("ephemeral cannot be set if upload is set")
+
+        # determine inline
+        if inline is None:
+            inline = _is_in_notebook() or os.environ.get("FIGPACK_INLINE") == "1"
+
+        # determine open_in_browser
+        if open_in_browser is None:
+            open_in_browser = os.environ.get("FIGPACK_OPEN_IN_BROWSER") == "1"
+
+        # determine ephemeral
+        if ephemeral is None:
+            ephemeral = False  # default to False
             if _is_in_notebook():
                 if _is_in_colab():
                     # if we are in a notebook and in colab, we should show as uploaded ephemeral
                     print("Detected Google Colab notebook environment.")
                     upload = True
                     ephemeral = True
-                if _is_in_jupyterhub():
+                elif _is_in_jupyterhub():
                     # if we are in a notebook and in jupyterhub, we should show as uploaded ephemeral
                     print("Detected JupyterHub notebook environment.")
                     upload = True
                     ephemeral = True
 
+        # determine _dev
+        if _dev is None:
+            _dev = os.environ.get("FIGPACK_DEV") == "1"
+
+        # determine wait_for_input
+        if wait_for_input is None:
+            wait_for_input = not _is_in_notebook()
+
         # Validate ephemeral parameter
         if ephemeral and not upload:
             raise ValueError("ephemeral=True requires upload=True to be set")
 
         if _dev:
+            if open_in_browser:
+                print("** Note: In dev mode, open_in_browser is forced to False **")
+                open_in_browser = False
             if port is None:
                 port = 3004
             if allow_origin is not None:
@@ -75,10 +115,15 @@ class FigpackView:
             if upload:
                 raise ValueError("Cannot upload when _dev is True.")
 
+            # make a random figure name
+            _local_figure_name = "fig_" + "".join(
+                random.choices(string.ascii_lowercase + string.digits, k=8)
+            )
+            print("** Development mode **")
             print(
-                f"For development, run figpack-gui in dev mode and use http://localhost:5173?data=http://localhost:{port}/data.zarr"
+                f"For development, run figpack-gui in dev mode and use http://localhost:5173?data=http://localhost:{port}/{_local_figure_name}/data.zarr"
             )
-            open_in_browser = False
+            print("")
 
         _show_view(
             self,
@@ -91,8 +136,20 @@ class FigpackView:
             description=description,
             inline=inline,
             inline_height=inline_height,
+            wait_for_input=wait_for_input,
+            _local_figure_name=_local_figure_name if _dev else None,
         )
 
+    def save(self, output_path: str) -> None:
+        """
+        Save as figure either to a folder or to a .tar.gz file
+        Args:
+            output_path: Output path (destination folder or .tar.gz file path)
+        """
+        from ._save_figure import _save_figure
+
+        _save_figure(self, output_path)
+
     def _write_to_zarr_group(self, group: zarr.Group) -> None:
         """
         Write the view data to a Zarr group. Must be implemented by subclasses.