figpack 0.1.1__py3-none-any.whl → 0.1.2__py3-none-any.whl

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/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/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/core/{_upload_view.py → _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/core/figpack_view.py

@@ -18,38 +18,46 @@ class FigpackView:
         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
-        """
-        from ._show_view import _show_view
-
-        _show_view(
-            self, port=port, open_in_browser=open_in_browser, allow_origin=allow_origin
-        )
 
-    def upload(self) -> str:
+        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
         """
-        Upload the visualization to the cloud
-
-        Returns:
-            str: URL where the uploaded figure can be viewed
+        from ._show_view import _show_view
 
-        Raises:
-            EnvironmentError: If FIGPACK_UPLOAD_PASSCODE is not set
-            Exception: If upload fails
-        """
-        from ._upload_view import _upload_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.")
 
-        return _upload_view(self)
+            print(
+                f"For development, run figpack-gui in dev mode and use http://localhost:5173?data=http://localhost:{port}/data.zarr"
+            )
 
-    def dev(self):
-        port = 3004
-        print(
-            f"For development, run figpack-gui in dev mode and use http://localhost:5173?data=http://localhost:{port}/data.zarr"
-        )
-        self.show(
-            port=port, open_in_browser=False, allow_origin="http://localhost:5173"
+        _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:

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}}