figpack 0.2.1__tar.gz → 0.2.3__tar.gz

{figpack-0.2.1/figpack.egg-info → figpack-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: figpack
-Version: 0.2.1
+Version: 0.2.3
 Summary: A Python package for creating shareable, interactive visualizations in the browser
 Author-email: Jeremy Magland <jmagland@flatironinstitute.org>
 License: Apache-2.0
@@ -25,8 +25,9 @@ Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy
-Requires-Dist: zarr
+Requires-Dist: zarr<3
 Requires-Dist: requests
+Requires-Dist: psutil
 Provides-Extra: test
 Requires-Dist: pytest>=7.0; extra == "test"
 Requires-Dist: pytest-cov>=4.0; extra == "test"

{figpack-0.2.1 → figpack-0.2.3}/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-0.2.1 → figpack-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-0.2.3/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-0.2.3/figpack/core/_show_view.py

@@ -0,0 +1,168 @@
+import os
+import pathlib
+import tempfile
+import webbrowser
+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()
+
+
+def _show_view(
+    view: FigpackView,
+    *,
+    open_in_browser: bool = False,
+    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,
+):
+    # 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 ephemeral and not api_key:
+                raise EnvironmentError(
+                    "FIGPACK_API_KEY environment variable must be set to upload views."
+                )
+
+            # Upload the bundle
+            figure_url = _upload_bundle(
+                tmpdir, api_key, title=title, ephemeral=ephemeral
+            )
+
+            if use_inline:
+                # For uploaded figures, display the remote URL inline and continue
+                _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"View the figure at: {figure_url}")
+                # Wait until user presses Enter
+                input("Press Enter to continue...")
+
+            return figure_url
+    else:
+        # Local server behavior: use process-level server manager
+        server_manager = ProcessServerManager.get_instance()
+
+        # 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
+        )
+
+        # Start or get existing server
+        base_url, server_port = server_manager.start_server(
+            port=port, allow_origin=allow_origin
+        )
+
+        # Construct URL to the specific figure subdirectory
+        figure_subdir_name = figure_dir.name
+        figure_url = f"{base_url}/{figure_subdir_name}"
+
+        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...")
+
+        return figure_url

{figpack-0.2.1 → figpack-0.2.3}/figpack/core/_upload_bundle.py

@@ -133,33 +133,45 @@ def _create_or_get_figure(
     total_files: int = None,
     total_size: int = None,
     title: str = None,
+    ephemeral: bool = False,
 ) -> dict:
     """
     Create a new figure or get existing figure information
 
     Args:
         figure_hash: The hash of the figure
-        api_key: The API key for authentication
+        api_key: The API key for authentication (required for non-ephemeral)
         total_files: Optional total number of files
         total_size: Optional total size of files
         title: Optional title for the figure
+        ephemeral: Whether to create an ephemeral figure
 
     Returns:
         dict: Figure information from the API
     """
+    # Validate API key requirement
+    if not ephemeral and api_key is None:
+        raise ValueError("API key is required for non-ephemeral figures")
+
     payload = {
         "figureHash": figure_hash,
-        "apiKey": api_key,
         "figpackVersion": __version__,
     }
 
+    # API key is optional for ephemeral figures
+    if api_key is not None:
+        payload["apiKey"] = api_key
+
     if total_files is not None:
         payload["totalFiles"] = total_files
     if total_size is not None:
         payload["totalSize"] = total_size
     if title is not None:
         payload["title"] = title
+    if ephemeral:
+        payload["ephemeral"] = True
 
+    # Use the same endpoint for both regular and ephemeral figures
     response = requests.post(f"{FIGPACK_API_BASE_URL}/api/figures/create", json=payload)
 
     if not response.ok:
@@ -212,16 +224,16 @@ def _finalize_figure(figure_url: str, api_key: str) -> dict:
     return response_data
 
 
-def _upload_bundle(tmpdir: str, api_key: str, title: str = None) -> str:
+def _upload_bundle(
+    tmpdir: str, api_key: str, title: str = None, ephemeral: bool = False
+) -> str:
     """
     Upload the prepared bundle to the cloud using the new database-driven approach
     """
     tmpdir_path = pathlib.Path(tmpdir)
 
     # Compute deterministic figure ID based on file contents
-    print("Computing deterministic figure ID...")
     figure_hash = _compute_deterministic_figure_hash(tmpdir_path)
-    print(f"Figure hash: {figure_hash}")
 
     # Collect all files to upload
     all_files = []
@@ -239,17 +251,15 @@ def _upload_bundle(tmpdir: str, api_key: str, title: str = None) -> str:
 
     # Find available figure ID and create/get figure in database with metadata
     result = _create_or_get_figure(
-        figure_hash, api_key, total_files, total_size, title=title
+        figure_hash, api_key, total_files, total_size, title=title, ephemeral=ephemeral
     )
     figure_info = result.get("figure", {})
     figure_url = figure_info.get("figureUrl")
 
     if figure_info["status"] == "completed":
-        print(f"Figure already exists at: {figure_url}")
+        print(f"Figure already exists. No upload needed.")
         return figure_url
 
-    print(f"Using figure URL: {figure_url}")
-
     files_to_upload = all_files
     total_files_to_upload = len(files_to_upload)