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

figpack/__init__.py

@@ -2,4 +2,4 @@
 figpack - A Python package for creating shareable, interactive visualizations in the browser
 """
 
-__version__ = "0.2.1"
+__version__ = "0.2.3"

figpack/cli.py

@@ -13,13 +13,13 @@ import threading
 import webbrowser
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
-from typing import Dict, List, Optional, Tuple, Union
-from urllib.parse import urljoin, urlparse
+from typing import Dict, Tuple, Union
+from urllib.parse import urljoin
 
 import requests
 
 from . import __version__
-from .core._show_view import serve_files
+from .core._server_manager import CORSRequestHandler
 
 MAX_WORKERS_FOR_DOWNLOAD = 16
 
@@ -216,6 +216,63 @@ def download_figure(figure_url: str, dest_path: str) -> None:
         print(f"Archive saved to: {dest_path}")
 
 
+def serve_files(
+    tmpdir: str,
+    *,
+    port: Union[int, None],
+    open_in_browser: bool = False,
+    allow_origin: Union[str, None] = None,
+):
+    """
+    Serve files from a directory using a simple HTTP server.
+
+    Args:
+        tmpdir: Directory to serve
+        port: Port number for local server
+        open_in_browser: Whether to open in browser automatically
+        allow_origin: CORS allow origin header
+    """
+    # if port is None, find a free port
+    if port is None:
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            s.bind(("", 0))
+            port = s.getsockname()[1]
+
+    tmpdir = pathlib.Path(tmpdir)
+    tmpdir = tmpdir.resolve()
+    if not tmpdir.exists() or not tmpdir.is_dir():
+        raise SystemExit(f"Directory not found: {tmpdir}")
+
+    # Configure handler with directory and allow_origin
+    def handler_factory(*args, **kwargs):
+        return CORSRequestHandler(
+            *args, directory=str(tmpdir), allow_origin=allow_origin, **kwargs
+        )
+
+    httpd = ThreadingHTTPServer(("0.0.0.0", port), handler_factory)
+    print(f"Serving {tmpdir} at http://localhost:{port} (CORS → {allow_origin})")
+    thread = threading.Thread(target=httpd.serve_forever, daemon=True)
+    thread.start()
+
+    if open_in_browser:
+        webbrowser.open(f"http://localhost:{port}")
+        print(f"Opening http://localhost:{port} in your browser.")
+    else:
+        print(
+            f"Open http://localhost:{port} in your browser to view the visualization."
+        )
+
+    try:
+        input("Press Enter to stop...\n")
+    except (KeyboardInterrupt, EOFError):
+        pass
+    finally:
+        print("Shutting down server...")
+        httpd.shutdown()
+        httpd.server_close()
+        thread.join()
+
+
 def view_figure(archive_path: str, port: Union[int, None] = None) -> None:
     """
     Extract and serve a figure archive locally

figpack/core/_server_manager.py

@@ -0,0 +1,304 @@
+import atexit
+import json
+import os
+import pathlib
+import psutil
+import shutil
+import socket
+import tempfile
+import threading
+import time
+import uuid
+from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
+from typing import Optional, Union
+
+
+class CORSRequestHandler(SimpleHTTPRequestHandler):
+    def __init__(self, *args, allow_origin=None, **kwargs):
+        self.allow_origin = allow_origin
+        super().__init__(*args, **kwargs)
+
+    def end_headers(self):
+        if self.allow_origin is not None:
+            self.send_header("Access-Control-Allow-Origin", self.allow_origin)
+            self.send_header("Vary", "Origin")
+            self.send_header("Access-Control-Allow-Methods", "GET, HEAD, OPTIONS")
+            self.send_header("Access-Control-Allow-Headers", "Content-Type, Range")
+            self.send_header(
+                "Access-Control-Expose-Headers",
+                "Accept-Ranges, Content-Encoding, Content-Length, Content-Range",
+            )
+        super().end_headers()
+
+    def do_OPTIONS(self):
+        self.send_response(204, "No Content")
+        self.end_headers()
+
+    def log_message(self, fmt, *args):
+        pass
+
+
+def _is_process_alive(pid: int) -> bool:
+    """Check if a process with the given PID is still alive."""
+    try:
+        return psutil.pid_exists(pid)
+    except Exception:
+        return False
+
+
+def _is_port_in_use(port: int) -> bool:
+    """Check if a port is currently in use."""
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            s.settimeout(1)
+            result = s.connect_ex(("localhost", port))
+            return result == 0
+    except Exception:
+        return False
+
+
+def _cleanup_orphaned_directories():
+    """Clean up orphaned figpack process directories."""
+    temp_root = pathlib.Path(tempfile.gettempdir())
+
+    for item in temp_root.iterdir():
+        if item.is_dir() and item.name.startswith("figpack_process_"):
+            process_info_file = item / "process_info.json"
+
+            if process_info_file.exists():
+                try:
+                    with open(process_info_file, "r") as f:
+                        info = json.load(f)
+
+                    pid = info.get("pid")
+                    port = info.get("port")
+
+                    # Check if process is dead or port is not in use
+                    process_dead = pid is None or not _is_process_alive(pid)
+                    port_free = port is None or not _is_port_in_use(port)
+
+                    if process_dead or port_free:
+                        print(f"Cleaning up orphaned directory: {item}")
+                        shutil.rmtree(item)
+
+                except Exception as e:
+                    # If we can't read the process info, assume it's orphaned
+                    print(f"Cleaning up unreadable directory: {item} (error: {e})")
+                    try:
+                        shutil.rmtree(item)
+                    except Exception:
+                        pass
+            else:
+                # No process info file, likely orphaned
+                print(f"Cleaning up directory without process info: {item}")
+                try:
+                    shutil.rmtree(item)
+                except Exception:
+                    pass
+
+
+class ProcessServerManager:
+    """
+    Manages a single server and temporary directory per process.
+    """
+
+    _instance: Optional["ProcessServerManager"] = None
+    _lock = threading.Lock()
+
+    def __init__(self):
+        self._temp_dir: Optional[pathlib.Path] = None
+        self._server: Optional[ThreadingHTTPServer] = None
+        self._server_thread: Optional[threading.Thread] = None
+        self._port: Optional[int] = None
+        self._allow_origin: Optional[str] = None
+        self._monitor_thread: Optional[threading.Thread] = None
+        self._stop_monitoring = threading.Event()
+
+        # Register cleanup on process exit
+        atexit.register(self._cleanup)
+
+    @classmethod
+    def get_instance(cls) -> "ProcessServerManager":
+        """Get the singleton instance of the server manager."""
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = cls()
+        return cls._instance
+
+    def get_temp_dir(self) -> pathlib.Path:
+        """Get or create the process-level temporary directory."""
+        if self._temp_dir is None:
+            # Clean up orphaned directories before creating new one
+            _cleanup_orphaned_directories()
+
+            self._temp_dir = pathlib.Path(tempfile.mkdtemp(prefix="figpack_process_"))
+
+            # Create process info file
+            self._create_process_info_file()
+        return self._temp_dir
+
+    def create_figure_subdir(self) -> pathlib.Path:
+        """Create a unique subdirectory for a figure within the process temp dir."""
+        temp_dir = self.get_temp_dir()
+        figure_id = str(uuid.uuid4())[:8]  # Short unique ID
+        figure_dir = temp_dir / f"figure_{figure_id}"
+        figure_dir.mkdir(exist_ok=True)
+        return figure_dir
+
+    def start_server(
+        self, port: Optional[int] = None, allow_origin: Optional[str] = None
+    ) -> tuple[str, int]:
+        """
+        Start the server if not already running, or return existing server info.
+
+        Returns:
+            tuple: (base_url, port)
+        """
+        # If server is already running with compatible settings, return existing info
+        if (
+            self._server is not None
+            and self._server_thread is not None
+            and self._server_thread.is_alive()
+            and (allow_origin is None or self._allow_origin == allow_origin)
+        ):
+            return f"http://localhost:{self._port}", self._port
+
+        # Stop existing server if settings are incompatible
+        if self._server is not None:
+            self._stop_server()
+
+        # Find available port if not specified
+        if port is None:
+            import socket
+
+            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+                s.bind(("", 0))
+                port = s.getsockname()[1]
+
+        temp_dir = self.get_temp_dir()
+
+        # Configure handler with directory and allow_origin
+        def handler_factory(*args, **kwargs):
+            return CORSRequestHandler(
+                *args, directory=str(temp_dir), allow_origin=allow_origin, **kwargs
+            )
+
+        self._server = ThreadingHTTPServer(("0.0.0.0", port), handler_factory)
+        self._port = port
+        self._allow_origin = allow_origin
+
+        # Start server in daemon thread
+        self._server_thread = threading.Thread(
+            target=self._server.serve_forever, daemon=True
+        )
+        self._server_thread.start()
+
+        # Update process info file with port information
+        self._update_process_info_file()
+
+        # Start directory monitoring thread
+        self._start_directory_monitor()
+
+        print(f"Started figpack server at http://localhost:{port} serving {temp_dir}")
+
+        return f"http://localhost:{port}", port
+
+    def _stop_server(self):
+        """Stop the current server."""
+        if self._server is not None:
+            self._server.shutdown()
+            self._server.server_close()
+            if self._server_thread is not None:
+                self._server_thread.join(timeout=1.0)
+            self._server = None
+            self._server_thread = None
+            self._port = None
+            self._allow_origin = None
+
+    def _create_process_info_file(self):
+        """Create the process info file in the temporary directory."""
+        if self._temp_dir is not None:
+            process_info = {
+                "pid": os.getpid(),
+                "port": self._port,
+                "created_at": time.time(),
+            }
+
+            process_info_file = self._temp_dir / "process_info.json"
+            try:
+                with open(process_info_file, "w") as f:
+                    json.dump(process_info, f, indent=2)
+            except Exception as e:
+                print(f"Warning: Failed to create process info file: {e}")
+
+    def _update_process_info_file(self):
+        """Update the process info file with current port information."""
+        if self._temp_dir is not None:
+            process_info_file = self._temp_dir / "process_info.json"
+            try:
+                # Read existing info
+                if process_info_file.exists():
+                    with open(process_info_file, "r") as f:
+                        process_info = json.load(f)
+                else:
+                    process_info = {"pid": os.getpid(), "created_at": time.time()}
+
+                # Update with current port
+                process_info["port"] = self._port
+                process_info["updated_at"] = time.time()
+
+                # Write back
+                with open(process_info_file, "w") as f:
+                    json.dump(process_info, f, indent=2)
+            except Exception as e:
+                print(f"Warning: Failed to update process info file: {e}")
+
+    def _start_directory_monitor(self):
+        """Start monitoring thread to detect if directory is deleted."""
+        if self._monitor_thread is None or not self._monitor_thread.is_alive():
+            self._stop_monitoring.clear()
+            self._monitor_thread = threading.Thread(
+                target=self._monitor_directory, daemon=True
+            )
+            self._monitor_thread.start()
+
+    def _monitor_directory(self):
+        """Monitor the temporary directory and stop server if it's deleted."""
+        while not self._stop_monitoring.is_set():
+            try:
+                if self._temp_dir is not None and not self._temp_dir.exists():
+                    print(
+                        f"Temporary directory {self._temp_dir} was deleted, stopping server"
+                    )
+                    self._stop_server()
+                    self._stop_monitoring.set()
+                    break
+
+                # Check every 5 seconds
+                self._stop_monitoring.wait(5.0)
+
+            except Exception as e:
+                print(f"Warning: Error in directory monitor: {e}")
+                break
+
+    def _cleanup(self):
+        """Cleanup server and temporary directory on process exit."""
+        # Stop monitoring
+        self._stop_monitoring.set()
+        if self._monitor_thread is not None:
+            self._monitor_thread.join(timeout=1.0)
+
+        # Stop server
+        self._stop_server()
+
+        # Remove temporary directory
+        if self._temp_dir is not None and self._temp_dir.exists():
+            try:
+                shutil.rmtree(self._temp_dir)
+            except Exception as e:
+                # Don't raise exceptions during cleanup
+                print(
+                    f"Warning: Failed to cleanup temporary directory {self._temp_dir}: {e}"
+                )
+            self._temp_dir = None

figpack/core/_show_view.py

@@ -1,15 +1,83 @@
 import os
 import pathlib
 import tempfile
-import threading
 import webbrowser
-from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
 from typing import Union
 
 from ._bundle_utils import prepare_figure_bundle
+from ._server_manager import ProcessServerManager
 from ._upload_bundle import _upload_bundle
 from .figpack_view import FigpackView
 
+
+def _is_in_notebook() -> bool:
+    """
+    Detect if we are running in a Jupyter notebook environment.
+
+    Returns:
+        bool: True if running in a notebook, False otherwise
+    """
+    try:
+        # Check if IPython is available and we're in a notebook
+        from IPython import get_ipython
+
+        ipython = get_ipython()
+        if ipython is None:
+            return False
+
+        # Check if we're in a notebook environment
+        if hasattr(ipython, "kernel"):
+            return True
+
+        # Additional check for notebook-specific attributes
+        if "ipykernel" in str(type(ipython)):
+            return True
+
+        return False
+    except ImportError:
+        return False
+
+
+def _is_in_colab():
+    try:
+        import google.colab  # type: ignore
+
+        return True
+    except ImportError:
+        return False
+
+
+def _is_in_jupyterhub():
+    return "JUPYTERHUB_USER" in os.environ
+
+
+def _display_inline_iframe(url: str, height: int) -> None:
+    """
+    Display an iframe inline in a Jupyter notebook.
+
+    Args:
+        url: URL to display in the iframe
+        height: Height of the iframe in pixels
+    """
+    try:
+        from IPython.display import HTML, display
+
+        iframe_html = f"""
+        <iframe src="{url}" 
+                width="100%" 
+                height="{height}px" 
+                frameborder="0"
+                style="border: 1px solid #ccc; border-radius: 4px;">
+        </iframe>
+        """
+
+        display(HTML(iframe_html))
+
+    except ImportError:
+        print(f"IPython not available. Please install IPython to use inline display.")
+        print(f"Alternatively, open {url} in your browser.")
+
+
 thisdir = pathlib.Path(__file__).parent.resolve()
 
 
@@ -20,113 +88,81 @@ def _show_view(
     port: Union[int, None] = None,
     allow_origin: Union[str, None] = None,
     upload: bool = False,
+    ephemeral: bool = False,
     title: Union[str, None] = None,
     description: Union[str, None] = None,
+    inline: Union[bool, None] = None,
+    inline_height: int = 600,
 ):
-    with tempfile.TemporaryDirectory(prefix="figpack_") as tmpdir:
-        prepare_figure_bundle(view, tmpdir, title=title, description=description)
-
-        if upload:
-            # Check for required environment variable
+    # Determine if we should use inline display
+    use_inline = inline
+    if inline is None:
+        # Auto-detect: use inline if we're in a notebook
+        use_inline = _is_in_notebook()
+
+    if upload:
+        # Upload behavior: create temporary directory for this upload only
+        with tempfile.TemporaryDirectory(prefix="figpack_upload_") as tmpdir:
+            prepare_figure_bundle(view, tmpdir, title=title, description=description)
+
+            # Check for API key - required for regular uploads, optional for ephemeral
             api_key = os.environ.get("FIGPACK_API_KEY")
-            if not api_key:
+            if not ephemeral and not api_key:
                 raise EnvironmentError(
                     "FIGPACK_API_KEY environment variable must be set to upload views."
                 )
 
             # Upload the bundle
-            print("Starting upload...")
-            figure_url = _upload_bundle(tmpdir, api_key, title=title)
+            figure_url = _upload_bundle(
+                tmpdir, api_key, title=title, ephemeral=ephemeral
+            )
 
-            if open_in_browser:
-                webbrowser.open(figure_url)
-                print(f"Opening {figure_url} in browser.")
-                # wait until user presses Enter
-                input("Press Enter to continue...")
+            if use_inline:
+                # For uploaded figures, display the remote URL inline and continue
+                _display_inline_iframe(figure_url, inline_height)
             else:
-                print(f"View the figure at: {figure_url}")
+                # Not in notebook environment
+                if open_in_browser:
+                    webbrowser.open(figure_url)
+                    print(f"Opening {figure_url} in browser.")
+                else:
+                    print(f"View the figure at: {figure_url}")
+                # Wait until user presses Enter
+                input("Press Enter to continue...")
 
             return figure_url
-        else:
-            serve_files(
-                tmpdir,
-                port=port,
-                open_in_browser=open_in_browser,
-                allow_origin=allow_origin,
-            )
-
-
-class CORSRequestHandler(SimpleHTTPRequestHandler):
-    def __init__(self, *args, allow_origin=None, **kwargs):
-        self.allow_origin = allow_origin
-        super().__init__(*args, **kwargs)
-
-    # Serve only GET/HEAD/OPTIONS; add CORS headers on every response
-    def end_headers(self):
-        if self.allow_origin is not None:
-            self.send_header("Access-Control-Allow-Origin", self.allow_origin)
-            self.send_header("Vary", "Origin")
-            self.send_header("Access-Control-Allow-Methods", "GET, HEAD, OPTIONS")
-            self.send_header("Access-Control-Allow-Headers", "Content-Type, Range")
-            self.send_header(
-                "Access-Control-Expose-Headers",
-                "Accept-Ranges, Content-Encoding, Content-Length, Content-Range",
-            )
-        super().end_headers()
-
-    def do_OPTIONS(self):
-        self.send_response(204, "No Content")
-        self.end_headers()
+    else:
+        # Local server behavior: use process-level server manager
+        server_manager = ProcessServerManager.get_instance()
 
-    def log_message(self, fmt, *args):
-        pass
+        # Create figure subdirectory in process temp directory
+        figure_dir = server_manager.create_figure_subdir()
 
+        # Prepare the figure bundle in the subdirectory
+        prepare_figure_bundle(
+            view, str(figure_dir), title=title, description=description
+        )
 
-def serve_files(
-    tmpdir: str,
-    *,
-    port: Union[int, None],
-    open_in_browser: bool = False,
-    allow_origin: Union[str, None] = None,
-):
-    # if port is None, find a free port
-    if port is None:
-        import socket
-
-        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
-            s.bind(("", 0))
-            port = s.getsockname()[1]
-
-    tmpdir = pathlib.Path(tmpdir)
-    tmpdir = tmpdir.resolve()
-    if not tmpdir.exists() or not tmpdir.is_dir():
-        raise SystemExit(f"Directory not found: {tmpdir}")
-
-    # Configure handler with directory and allow_origin
-    def handler_factory(*args, **kwargs):
-        return CORSRequestHandler(
-            *args, directory=str(tmpdir), allow_origin=allow_origin, **kwargs
+        # Start or get existing server
+        base_url, server_port = server_manager.start_server(
+            port=port, allow_origin=allow_origin
         )
 
-    httpd = ThreadingHTTPServer(("0.0.0.0", port), handler_factory)
-    print(f"Serving {tmpdir} at http://localhost:{port} (CORS → {allow_origin})")
-    thread = threading.Thread(target=httpd.serve_forever, daemon=True)
-    thread.start()
+        # Construct URL to the specific figure subdirectory
+        figure_subdir_name = figure_dir.name
+        figure_url = f"{base_url}/{figure_subdir_name}"
 
-    if open_in_browser:
-        webbrowser.open(f"http://localhost:{port}")
-        print(f"Opening http://localhost:{port} in your browser.")
-    else:
-        print(
-            f"Open http://localhost:{port} in your browser to view the visualization."
-        )
+        if use_inline:
+            # Display inline and continue (don't block)
+            _display_inline_iframe(figure_url, inline_height)
+        else:
+            # Not in notebook environment
+            if open_in_browser:
+                webbrowser.open(figure_url)
+                print(f"Opening {figure_url} in browser.")
+            else:
+                print(f"Open {figure_url} in your browser to view the visualization.")
+            # Wait until user presses Enter
+            input("Press Enter to continue...")
 
-    try:
-        input("Press Enter to stop...\n")
-    except (KeyboardInterrupt, EOFError):
-        pass
-    finally:
-        print("Shutting down server...")
-        httpd.shutdown()
-        httpd.server_close()
-        thread.join()
+        return figure_url