figpack 0.1.1__tar.gz → 0.1.2__tar.gz

figpack-0.1.2/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: figpack
+Version: 0.1.2
+Summary: A Python package for creating shareable, interactive visualizations in the browser
+Author-email: Jeremy Magland <jmagland@flatironinstitute.org>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/magland/figpack
+Project-URL: Repository, https://github.com/magland/figpack
+Project-URL: Documentation, https://github.com/magland/figpack#readme
+Project-URL: Bug Tracker, https://github.com/magland/figpack/issues
+Keywords: visualization,plotting,timeseries,interactive
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: zarr
+Requires-Dist: requests
+Dynamic: license-file
+
+# figpack
+
+A Python package for creating shareable, interactive visualizations in the browser.
+
+## Overview
+
+figpack enables you to create interactive data visualizations that can be displayed in a web browser and optionally shared online. The package focuses on timeseries data visualization with support for complex, nested layouts.
+
+### Key Features
+
+- **Interactive timeseries graphs** with line series, markers, and interval plots
+- **Flexible layout system** with boxes, splitters, and tab layouts
+- **Web-based rendering** that works in any modern browser
+- **Shareable visualizations** that can be uploaded and shared via URLs
+- **Zarr-based data storage** for efficient handling of large datasets
+
+## Installation
+
+Install figpack using pip:
+
+```bash
+pip install figpack
+```
+
+## Quick Start
+
+```python
+import numpy as np
+import figpack.views as vv
+
+# Create a timeseries graph
+graph = vv.TimeseriesGraph(y_label="Signal")
+
+# Add some data
+t = np.linspace(0, 10, 1000)
+y = np.sin(2 * np.pi * t)
+graph.add_line_series(name="sine wave", t=t, y=y, color="blue")
+
+# Display the visualization
+graph.show(open_in_browser=True)
+```
+
+## Examples
+
+See the `examples/` directory.
+
+## Usage Modes
+
+### Local Development
+
+```python
+view.show(open_in_browser=True)
+```
+
+### Sharing Online
+
+Set the `FIGPACK_UPLOAD_PASSCODE` environment variable and use:
+
+```python
+view.show(upload=True, open_in_browser=True)
+```
+
+### Development Mode
+
+Set `_dev=True` in the call to show() to enable development mode, which allows for live updates and debugging with figpack-gui.
+
+## License
+
+Apache-2.0
+
+## Contributing
+
+Visit the [GitHub repository](https://github.com/magland/figpack) for issues, contributions, and the latest updates.

figpack-0.1.2/README.md

@@ -0,0 +1,73 @@
+# figpack
+
+A Python package for creating shareable, interactive visualizations in the browser.
+
+## Overview
+
+figpack enables you to create interactive data visualizations that can be displayed in a web browser and optionally shared online. The package focuses on timeseries data visualization with support for complex, nested layouts.
+
+### Key Features
+
+- **Interactive timeseries graphs** with line series, markers, and interval plots
+- **Flexible layout system** with boxes, splitters, and tab layouts
+- **Web-based rendering** that works in any modern browser
+- **Shareable visualizations** that can be uploaded and shared via URLs
+- **Zarr-based data storage** for efficient handling of large datasets
+
+## Installation
+
+Install figpack using pip:
+
+```bash
+pip install figpack
+```
+
+## Quick Start
+
+```python
+import numpy as np
+import figpack.views as vv
+
+# Create a timeseries graph
+graph = vv.TimeseriesGraph(y_label="Signal")
+
+# Add some data
+t = np.linspace(0, 10, 1000)
+y = np.sin(2 * np.pi * t)
+graph.add_line_series(name="sine wave", t=t, y=y, color="blue")
+
+# Display the visualization
+graph.show(open_in_browser=True)
+```
+
+## Examples
+
+See the `examples/` directory.
+
+## Usage Modes
+
+### Local Development
+
+```python
+view.show(open_in_browser=True)
+```
+
+### Sharing Online
+
+Set the `FIGPACK_UPLOAD_PASSCODE` environment variable and use:
+
+```python
+view.show(upload=True, open_in_browser=True)
+```
+
+### Development Mode
+
+Set `_dev=True` in the call to show() to enable development mode, which allows for live updates and debugging with figpack-gui.
+
+## License
+
+Apache-2.0
+
+## Contributing
+
+Visit the [GitHub repository](https://github.com/magland/figpack) for issues, contributions, and the latest updates.

{figpack-0.1.1 → figpack-0.1.2}/figpack/__init__.py

@@ -1,5 +1,5 @@
 """
-figpack - A Python package for creating interactive visualizations
+figpack - A Python package for creating shareable, interactive visualizations in the browser
 """
 
 __version__ = "0.1.0"

{figpack-0.1.1 → figpack-0.1.2}/figpack/core/_bundle_utils.py

@@ -6,7 +6,9 @@ from .figpack_view import FigpackView
 thisdir = pathlib.Path(__file__).parent.resolve()
 
 
-def prepare_figure_bundle(view: FigpackView, tmpdir: str) -> None:
+def prepare_figure_bundle(
+    view: FigpackView, tmpdir: str, *, title: str = None, description: str = None
+) -> None:
     """
     Prepare a figure bundle in the specified temporary directory.
 
@@ -18,6 +20,8 @@ def prepare_figure_bundle(view: FigpackView, tmpdir: str) -> None:
     Args:
         view: The figpack view to prepare
         tmpdir: The temporary directory to prepare the bundle in
+        title: Optional title for the figure
+        description: Optional description for the figure (markdown supported)
     """
     html_dir = thisdir / ".." / "figpack-gui-dist"
     if not os.path.exists(html_dir):
@@ -43,4 +47,10 @@ def prepare_figure_bundle(view: FigpackView, tmpdir: str) -> None:
     )
     view._write_to_zarr_group(zarr_group)
 
+    # Add title and description as attributes on the top-level zarr group
+    if title is not None:
+        zarr_group.attrs["title"] = title
+    if description is not None:
+        zarr_group.attrs["description"] = description
+
     zarr.consolidate_metadata(zarr_group.store)

{figpack-0.1.1 → figpack-0.1.2}/figpack/core/_show_view.py

@@ -12,6 +12,7 @@ from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
 
 from .figpack_view import FigpackView
 from ._bundle_utils import prepare_figure_bundle
+from ._upload_bundle import _upload_bundle
 
 thisdir = pathlib.Path(__file__).parent.resolve()
 
@@ -22,16 +23,41 @@ def _show_view(
     open_in_browser: bool = False,
     port: Union[int, None] = None,
     allow_origin: Union[str, None] = None,
+    upload: bool = False,
+    title: Union[str, None] = None,
+    description: Union[str, None] = None,
 ):
     with tempfile.TemporaryDirectory(prefix="figpack_") as tmpdir:
-        prepare_figure_bundle(view, tmpdir)
-
-        serve_files(
-            tmpdir,
-            port=port,
-            open_in_browser=open_in_browser,
-            allow_origin=allow_origin,
-        )
+        prepare_figure_bundle(view, tmpdir, title=title, description=description)
+
+        if upload:
+            # Check for required environment variable
+            passcode = os.environ.get("FIGPACK_UPLOAD_PASSCODE")
+            if not passcode:
+                raise EnvironmentError(
+                    "FIGPACK_UPLOAD_PASSCODE environment variable must be set to upload views."
+                )
+
+            # Upload the bundle
+            print("Starting upload...")
+            figure_url = _upload_bundle(tmpdir, passcode)
+
+            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...")
+            else:
+                print(f"View the figure at: {figure_url}")
+
+            return figure_url
+        else:
+            serve_files(
+                tmpdir,
+                port=port,
+                open_in_browser=open_in_browser,
+                allow_origin=allow_origin,
+            )
 
 
 class CORSRequestHandler(SimpleHTTPRequestHandler):

figpack-0.1.1/figpack/core/_upload_view.py → figpack-0.1.2/figpack/core/_upload_bundle.py

@@ -1,62 +1,18 @@
-import os
 import time
 import json
 import uuid
-import tempfile
 import pathlib
 import requests
 import threading
+import hashlib
+from .. import __version__
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from datetime import datetime, timedelta, timezone
 
-from .figpack_view import FigpackView
-from ._bundle_utils import prepare_figure_bundle
-
 thisdir = pathlib.Path(__file__).parent.resolve()
 
 FIGPACK_API_BASE_URL = "https://figpack-api.vercel.app"
-TEMPORY_BASE_URL = "https://tempory.net/figpack/figures"
-
-
-def _upload_view(view: FigpackView) -> str:
-    """
-    Upload a figpack view to the cloud
-
-    Args:
-        view: The figpack view to upload
-
-    Returns:
-        str: URL where the uploaded figure can be viewed
-
-    Raises:
-        EnvironmentError: If FIGPACK_UPLOAD_PASSCODE is not set
-        Exception: If upload fails
-    """
-    # Check for required environment variable
-    passcode = os.environ.get("FIGPACK_UPLOAD_PASSCODE")
-    if not passcode:
-        raise EnvironmentError(
-            "FIGPACK_UPLOAD_PASSCODE environment variable must be set"
-        )
-
-    # Generate random figure ID
-    figure_id = str(uuid.uuid4())
-    print(f"Generated figure ID: {figure_id}")
-
-    with tempfile.TemporaryDirectory(prefix="figpack_upload_") as tmpdir:
-        # Prepare the figure bundle (reuse logic from _show_view)
-        print("Preparing figure bundle...")
-        prepare_figure_bundle(view, tmpdir)
-
-        # Upload the bundle
-        print("Starting upload...")
-        _upload_bundle(tmpdir, figure_id, passcode)
-
-        # Return the final URL
-        figure_url = f"{TEMPORY_BASE_URL}/{figure_id}/index.html"
-        print(f"Upload completed successfully!")
-        print(f"Figure available at: {figure_url}")
-        return figure_url
+TEMPORY_BASE_URL = "https://tempory.net/figpack/default/figures"
 
 
 def _upload_single_file(
@@ -83,12 +39,121 @@ def _upload_single_file(
 MAX_WORKERS_FOR_UPLOAD = 16
 
 
-def _upload_bundle(tmpdir: str, figure_id: str, passcode: str) -> None:
+def _compute_deterministic_figure_id(tmpdir_path: pathlib.Path) -> str:
+    """
+    Compute a deterministic figure ID based on SHA1 hashes of all files
+
+    Returns:
+        str: 40-character SHA1 hash representing the content of all files
+    """
+    file_hashes = []
+
+    # Collect all files and their hashes
+    for file_path in sorted(tmpdir_path.rglob("*")):
+        if file_path.is_file():
+            relative_path = file_path.relative_to(tmpdir_path)
+
+            # Compute SHA1 hash of file content
+            sha1_hash = hashlib.sha1()
+            with open(file_path, "rb") as f:
+                for chunk in iter(lambda: f.read(4096), b""):
+                    sha1_hash.update(chunk)
+
+            # Include both the relative path and content hash to ensure uniqueness
+            file_info = f"{relative_path}:{sha1_hash.hexdigest()}"
+            file_hashes.append(file_info)
+
+    # Create final hash from all file hashes
+    combined_hash = hashlib.sha1()
+    for file_hash in file_hashes:
+        combined_hash.update(file_hash.encode("utf-8"))
+
+    return combined_hash.hexdigest()
+
+
+def _check_existing_figure(figure_id: str) -> dict:
+    """
+    Check if a figure already exists and return its status
+
+    Returns:
+        dict: Contains 'exists' (bool) and 'status' (str) if exists
+    """
+    figpack_url = f"{TEMPORY_BASE_URL}/{figure_id}/figpack.json"
+
+    try:
+        response = requests.get(figpack_url, timeout=10)
+        if response.ok:
+            figpack_data = response.json()
+            return {"exists": True, "status": figpack_data.get("status", "unknown")}
+        else:
+            return {"exists": False}
+    except Exception:
+        return {"exists": False}
+
+
+def _find_available_figure_id(base_figure_id: str) -> tuple:
+    """
+    Find an available figure ID by checking base_figure_id, then base_figure_id-1, base_figure_id-2, etc.
+
+    Returns:
+        tuple: (figure_id_to_use, completed_figure_id) where:
+               - figure_id_to_use is None if upload should be skipped
+               - completed_figure_id is the ID of the completed figure if one exists
+    """
+    # First check the base figure ID
+    result = _check_existing_figure(base_figure_id)
+    if not result["exists"]:
+        return (base_figure_id, None)
+    elif result["status"] == "completed":
+        print(
+            f"Figure {base_figure_id} already exists and is completed. Skipping upload."
+        )
+        return (None, base_figure_id)  # Signal to skip upload, return completed ID
+
+    # If exists but not completed, try with suffixes
+    suffix = 1
+    while True:
+        candidate_id = f"{base_figure_id}-{suffix}"
+        result = _check_existing_figure(candidate_id)
+
+        if not result["exists"]:
+            print(f"Using figure ID: {candidate_id}")
+            return (candidate_id, None)
+        elif result["status"] == "completed":
+            print(
+                f"Figure {candidate_id} already exists and is completed. Skipping upload."
+            )
+            return (None, candidate_id)  # Signal to skip upload, return completed ID
+
+        suffix += 1
+        if suffix > 100:  # Safety limit
+            raise Exception(
+                "Too many existing figure variants, unable to find available ID"
+            )
+
+
+def _upload_bundle(tmpdir: str, passcode: str) -> None:
     """
     Upload the prepared bundle to the cloud using parallel uploads
     """
     tmpdir_path = pathlib.Path(tmpdir)
 
+    # Compute deterministic figure ID based on file contents
+    print("Computing deterministic figure ID...")
+    base_figure_id = _compute_deterministic_figure_id(tmpdir_path)
+    print(f"Base figure ID: {base_figure_id}")
+
+    # Find available figure ID (check for existing uploads)
+    figure_id, completed_figure_id = _find_available_figure_id(base_figure_id)
+
+    # If figure_id is None, it means we found a completed upload and should skip
+    if figure_id is None:
+        figure_url = f"{TEMPORY_BASE_URL}/{completed_figure_id}/index.html"
+        print(f"Figure already exists at: {figure_url}")
+        return figure_url
+
+    print(f"Using figure ID: {figure_id}")
+
     # First, upload initial figpack.json with "uploading" status
     print("Uploading initial status...")
     figpack_json = {
@@ -96,6 +161,7 @@ def _upload_bundle(tmpdir: str, figure_id: str, passcode: str) -> None:
         "upload_started": datetime.now(timezone.utc).isoformat(),
         "upload_updated": datetime.now(timezone.utc).isoformat(),
         "figure_id": figure_id,
+        "figpack_version": __version__,
     }
     _upload_small_file(
         figure_id, "figpack.json", json.dumps(figpack_json, indent=2), passcode
@@ -179,8 +245,27 @@ def _upload_bundle(tmpdir: str, figure_id: str, passcode: str) -> None:
                     print(f"Failed to upload {relative_path}: {e}")
                     raise  # Re-raise the exception to stop the upload process
 
+    # Create and upload manifest.json
+    print("Creating manifest.json...")
+    manifest = {
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "files": [],
+        "total_size": 0,
+        "total_files": len(files_to_upload),
+    }
+
+    for rel_path, file_path in files_to_upload:
+        file_size = file_path.stat().st_size
+        manifest["files"].append({"path": rel_path, "size": file_size})
+        manifest["total_size"] += file_size
+
+    _upload_small_file(
+        figure_id, "manifest.json", json.dumps(manifest, indent=2), passcode
+    )
+    print("Uploaded manifest.json")
+    print(f"Total size: {manifest['total_size'] / (1024 * 1024):.2f} MB")
+
     # Finally, upload completion status
-    print("Uploading completion status...")
     figpack_json = {
         **figpack_json,
         "status": "completed",
@@ -188,10 +273,16 @@ def _upload_bundle(tmpdir: str, figure_id: str, passcode: str) -> None:
         "expiration": (datetime.now(timezone.utc) + timedelta(days=1)).isoformat(),
         "figure_id": figure_id,
         "total_files": len(all_files),
+        "total_size": manifest["total_size"],
+        "figpack_version": __version__,
     }
     _upload_small_file(
         figure_id, "figpack.json", json.dumps(figpack_json, indent=2), passcode
     )
+    print("Upload completed successfully")
+
+    figure_url = f"{TEMPORY_BASE_URL}/{figure_id}/index.html"
+    return figure_url
 
 
 def _determine_file_type(file_path: str) -> str:

figpack-0.1.2/figpack/core/figpack_view.py

@@ -0,0 +1,70 @@
+"""
+Base view class for figpack visualization components
+"""
+
+from typing import Union
+
+import zarr
+
+
+class FigpackView:
+    """
+    Base class for all figpack visualization components
+    """
+
+    def show(
+        self,
+        *,
+        port: Union[int, None] = None,
+        open_in_browser: bool = False,
+        allow_origin: Union[str, None] = None,
+        upload: bool = False,
+        _dev: bool = False,
+        title: Union[str, None] = None,
+        description: Union[str, None] = None,
+    ):
+        """
+        Display the visualization component
+
+        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
+            _dev: Development mode flag
+            title: Title for the browser tab and figure
+            description: Description text (markdown supported) for the figure
+        """
+        from ._show_view import _show_view
+
+        if _dev:
+            if port is None:
+                port = 3004
+            if allow_origin is not None:
+                raise ValueError("Cannot set allow_origin when _dev is True.")
+            allow_origin = "http://localhost:5173"
+            if upload:
+                raise ValueError("Cannot upload when _dev is True.")
+
+            print(
+                f"For development, run figpack-gui in dev mode and use http://localhost:5173?data=http://localhost:{port}/data.zarr"
+            )
+
+        _show_view(
+            self,
+            port=port,
+            open_in_browser=open_in_browser,
+            allow_origin=allow_origin,
+            upload=upload,
+            title=title,
+            description=description,
+        )
+
+    def _write_to_zarr_group(self, group: zarr.Group) -> None:
+        """
+        Write the view data to a Zarr group. Must be implemented by subclasses.
+
+        Args:
+            group: Zarr group to write data into
+        """
+        raise NotImplementedError("Subclasses must implement _write_to_zarr_group")

figpack-0.1.2/figpack/figpack-gui-dist/assets/index-BA_v5Jep.css

@@ -0,0 +1 @@
+:root{font-family:system-ui,Avenir,Helvetica,Arial,sans-serif;line-height:1.5;font-weight:400;font-synthesis:none;text-rendering:optimizeLegibility;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}a{font-weight:500;color:#646cff;text-decoration:inherit}a:hover{color:#535bf2}body{margin:0;overflow:hidden}h1{font-size:3.2em;line-height:1.1}button{border-radius:8px;border:1px solid transparent;padding:.6em 1.2em;font-size:1em;font-weight:500;font-family:inherit;background-color:#1a1a1a;cursor:pointer;transition:border-color .25s}button:hover{border-color:#646cff}button:focus,button:focus-visible{outline:4px auto -webkit-focus-ring-color}.status-bar{position:fixed;bottom:0;left:0;right:0;height:30px;background-color:#2a2a2a;color:#fff;display:flex;align-items:center;padding:0 12px;font-size:12px;border-top:1px solid #444;z-index:1000}.status-bar.warning{background-color:#ff9800;color:#000}.status-bar.error{background-color:#f44336;color:#fff}.status-bar.expired{background-color:#d32f2f;color:#fff}.manage-button{background-color:#444;color:#fff;border:none;padding:4px 8px;border-radius:4px;cursor:pointer;font-size:11px;height:22px;margin-left:12px;transition:background-color .2s}.manage-button:hover{background-color:#666}.about-button{background-color:#444;color:#fff;border:none;padding:4px 8px;border-radius:4px;cursor:pointer;font-size:11px;height:22px;margin-left:12px;transition:background-color .2s}.about-button:hover{background-color:#666}.about-dialog-overlay{position:fixed;inset:0;background-color:#00000080;display:flex;justify-content:center;align-items:center;z-index:2000}.about-dialog{background-color:#2a2a2a;color:#fff;border-radius:8px;max-width:600px;max-height:80vh;width:90%;box-shadow:0 4px 20px #0000004d;overflow:hidden}.about-dialog-header{display:flex;justify-content:space-between;align-items:center;padding:16px 20px;border-bottom:1px solid #444}.about-dialog-header h2{margin:0;font-size:18px;font-weight:600}.about-dialog-close{background:none;border:none;color:#fff;font-size:24px;cursor:pointer;padding:0;width:30px;height:30px;display:flex;align-items:center;justify-content:center;border-radius:4px;transition:background-color .2s}.about-dialog-close:hover{background-color:#444}.about-dialog-content{padding:20px;overflow-y:auto;max-height:calc(80vh - 80px)}.about-dialog-description{line-height:1.6}.about-dialog-description h1,.about-dialog-description h2,.about-dialog-description h3{margin-top:0;margin-bottom:12px}.about-dialog-description p{margin-bottom:12px}.about-dialog-description code{background-color:#444;padding:2px 4px;border-radius:3px;font-family:Courier New,monospace;font-size:.9em}.about-dialog-description pre{background-color:#444;padding:12px;border-radius:4px;overflow-x:auto;margin-bottom:12px}.about-dialog-description ul,.about-dialog-description ol{margin-bottom:12px;padding-left:20px}.about-dialog-description blockquote{border-left:4px solid #666;padding-left:16px;margin:12px 0;font-style:italic}@media (prefers-color-scheme: light){:root{color:#213547;background-color:#fff}a:hover{color:#747bff}button{background-color:#f9f9f9}.status-bar{background-color:#f5f5f5;color:#333;border-top:1px solid #ddd}.status-bar.warning{background-color:#fff3cd;color:#856404;border-top:1px solid #ffeaa7}.status-bar.error,.status-bar.expired{background-color:#f8d7da;color:#721c24;border-top:1px solid #f5c6cb}.manage-button{background-color:#e0e0e0;color:#333;border:1px solid #ccc}.manage-button:hover{background-color:#d0d0d0}.about-button{background-color:#e0e0e0;color:#333;border:1px solid #ccc}.about-button:hover{background-color:#d0d0d0}.about-dialog{background-color:#fff;color:#333;box-shadow:0 4px 20px #00000026}.about-dialog-header{border-bottom:1px solid #ddd}.about-dialog-close{color:#333}.about-dialog-close:hover{background-color:#f0f0f0}.about-dialog-description code,.about-dialog-description pre{background-color:#f5f5f5;color:#333}.about-dialog-description blockquote{border-left:4px solid #ccc}}