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

figpack/__init__.py

@@ -1,7 +1,9 @@
 """
-figpack - A Python package for creating interactive visualizations
+figpack - A Python package for creating shareable, interactive visualizations in the browser
 """
 
 __version__ = "0.1.0"
 __author__ = "Jeremy Magland"
 __email__ = "jmagland@flatironinstitute.org"
+
+from . import spike_sorting

figpack/cli.py

@@ -0,0 +1,312 @@
+"""
+Command-line interface for figpack
+"""
+
+import argparse
+import sys
+import pathlib
+import tempfile
+import tarfile
+import json
+import requests
+import threading
+import webbrowser
+import socket
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from urllib.parse import urlparse, urljoin
+from typing import Dict, List, Tuple, Optional, Union
+from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
+
+from . import __version__
+from .core._show_view import serve_files
+
+MAX_WORKERS_FOR_DOWNLOAD = 16
+
+
+def get_figure_base_url(figure_url: str) -> str:
+    """
+    Get the base URL from any figpack URL
+
+    Args:
+        figure_url: Any figpack URL (may or may not end with /index.html)
+
+    Returns:
+        str: The base URL for the figure directory
+    """
+    # Handle URLs that end with /index.html
+    if figure_url.endswith("/index.html"):
+        base_url = figure_url[:-11]  # Remove "/index.html"
+    elif figure_url.endswith("/"):
+        base_url = figure_url[:-1]  # Remove trailing slash
+    else:
+        # Assume it's already a directory URL
+        base_url = figure_url
+
+    # Ensure it ends with a slash for urljoin to work properly
+    if not base_url.endswith("/"):
+        base_url += "/"
+
+    return base_url
+
+
+def download_file(
+    base_url: str, file_info: Dict, temp_dir: pathlib.Path
+) -> Tuple[str, bool]:
+    """
+    Download a single file from the figure
+
+    Args:
+        base_url: The base URL for the figure
+        file_info: Dictionary with 'path' and 'size' keys
+        temp_dir: Temporary directory to download to
+
+    Returns:
+        Tuple of (file_path, success)
+    """
+    file_path = file_info["path"]
+    file_url = urljoin(base_url, file_path)
+
+    try:
+        response = requests.get(file_url, timeout=30)
+        response.raise_for_status()
+
+        # Create directory structure if needed
+        local_file_path = temp_dir / file_path
+        local_file_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Write file content
+        if file_path.endswith(
+            (
+                ".json",
+                ".html",
+                ".css",
+                ".js",
+                ".zattrs",
+                ".zgroup",
+                ".zarray",
+                ".zmetadata",
+            )
+        ):
+            # Text files
+            local_file_path.write_text(response.text, encoding="utf-8")
+        else:
+            # Binary files
+            local_file_path.write_bytes(response.content)
+
+        return file_path, True
+
+    except Exception as e:
+        print(f"Failed to download {file_path}: {e}")
+        return file_path, False
+
+
+def download_figure(figure_url: str, dest_path: str) -> None:
+    """
+    Download a figure from a figpack URL and save as tar.gz
+
+    Args:
+        figure_url: The figpack URL
+        dest_path: Destination path for the tar.gz file
+    """
+    print(f"Downloading figure from: {figure_url}")
+
+    # Get base URL
+    base_url = get_figure_base_url(figure_url)
+    print(f"Base URL: {base_url}")
+
+    # Check if manifest.json exists
+    manifest_url = urljoin(base_url, "manifest.json")
+    print("Checking for manifest.json...")
+
+    try:
+        response = requests.get(manifest_url, timeout=10)
+        response.raise_for_status()
+        manifest = response.json()
+        print(f"Found manifest with {len(manifest['files'])} files")
+    except requests.exceptions.RequestException as e:
+        print(f"Error: Could not retrieve manifest.json from {manifest_url}: {e}")
+        print("Make sure the URL points to a valid figpack figure with a manifest.")
+        sys.exit(1)
+    except json.JSONDecodeError as e:
+        print(f"Error: Invalid manifest.json format: {e}")
+        sys.exit(1)
+
+    # Create temporary directory for downloads
+    with tempfile.TemporaryDirectory() as temp_dir:
+        temp_path = pathlib.Path(temp_dir)
+
+        # Download all files in parallel
+        print(
+            f"Downloading {len(manifest['files'])} files with up to {MAX_WORKERS_FOR_DOWNLOAD} concurrent downloads..."
+        )
+
+        downloaded_count = 0
+        failed_files = []
+        count_lock = threading.Lock()
+
+        with ThreadPoolExecutor(max_workers=MAX_WORKERS_FOR_DOWNLOAD) as executor:
+            # Submit all download tasks
+            future_to_file = {
+                executor.submit(
+                    download_file, base_url, file_info, temp_path
+                ): file_info["path"]
+                for file_info in manifest["files"]
+            }
+
+            # Process completed downloads
+            for future in as_completed(future_to_file):
+                file_path = future_to_file[future]
+                try:
+                    downloaded_path, success = future.result()
+
+                    with count_lock:
+                        if success:
+                            downloaded_count += 1
+                            print(
+                                f"Downloaded {downloaded_count}/{len(manifest['files'])}: {downloaded_path}"
+                            )
+                        else:
+                            failed_files.append(downloaded_path)
+
+                except Exception as e:
+                    with count_lock:
+                        failed_files.append(file_path)
+                        print(f"Failed to download {file_path}: {e}")
+
+        if failed_files:
+            print(f"Warning: Failed to download {len(failed_files)} files:")
+            for failed_file in failed_files:
+                print(f"  - {failed_file}")
+
+            if len(failed_files) == len(manifest["files"]):
+                print("Error: Failed to download any files. Aborting.")
+                sys.exit(1)
+
+        # Save manifest.json to temp directory
+        manifest_path = temp_path / "manifest.json"
+        manifest_path.write_text(json.dumps(manifest, indent=2))
+        print("Added manifest.json to bundle")
+
+        # Create tar.gz file
+        print(f"Creating tar.gz archive: {dest_path}")
+        dest_pathlib = pathlib.Path(dest_path)
+        dest_pathlib.parent.mkdir(parents=True, exist_ok=True)
+
+        with tarfile.open(dest_path, "w:gz") as tar:
+            # Add all downloaded files (excluding figpack.json if it exists)
+            for file_path in temp_path.rglob("*"):
+                if file_path.is_file():
+                    arcname = file_path.relative_to(temp_path)
+                    # Skip figpack.json as requested
+                    if str(arcname) != "figpack.json":
+                        tar.add(file_path, arcname=arcname)
+
+        # Count files in archive (excluding directories)
+        archive_files = [
+            f for f in temp_path.rglob("*") if f.is_file() and f.name != "figpack.json"
+        ]
+        total_size = sum(f.stat().st_size for f in archive_files)
+
+        print(f"Archive created successfully!")
+        print(
+            f"Total files: {len(archive_files)} (including manifest.json, excluding figpack.json)"
+        )
+        print(f"Total size: {total_size / (1024 * 1024):.2f} MB")
+        print(f"Archive saved to: {dest_path}")
+
+
+def view_figure(archive_path: str, port: Union[int, None] = None) -> None:
+    """
+    Extract and serve a figure archive locally
+
+    Args:
+        archive_path: Path to the tar.gz archive
+        port: Optional port number to serve on
+    """
+    archive_pathlib = pathlib.Path(archive_path)
+
+    if not archive_pathlib.exists():
+        print(f"Error: Archive file not found: {archive_path}")
+        sys.exit(1)
+
+    if not archive_pathlib.suffix.lower() in [".gz", ".tgz"] or not str(
+        archive_pathlib
+    ).endswith(".tar.gz"):
+        print(f"Error: Expected a .tar.gz file, got: {archive_path}")
+        sys.exit(1)
+
+    print(f"Extracting figure archive: {archive_path}")
+
+    # Create temporary directory and extract files
+    with tempfile.TemporaryDirectory(prefix="figpack_view_") as temp_dir:
+        temp_path = pathlib.Path(temp_dir)
+
+        try:
+            with tarfile.open(archive_path, "r:gz") as tar:
+                tar.extractall(temp_path)
+
+            # Count extracted files
+            extracted_files = list(temp_path.rglob("*"))
+            file_count = len([f for f in extracted_files if f.is_file()])
+            print(f"Extracted {file_count} files")
+
+            # Check if index.html exists
+            index_html = temp_path / "index.html"
+            if not index_html.exists():
+                print("Warning: No index.html found in archive")
+                print("Available files:")
+                for f in sorted(extracted_files):
+                    if f.is_file():
+                        print(f"  {f.relative_to(temp_path)}")
+
+            # Serve the files
+            serve_files(
+                str(temp_path),
+                port=port,
+                open_in_browser=True,
+                allow_origin=None,
+            )
+
+        except tarfile.TarError as e:
+            print(f"Error: Failed to extract archive: {e}")
+            sys.exit(1)
+
+
+def main():
+    """Main CLI entry point"""
+    parser = argparse.ArgumentParser(
+        description="figpack - A Python package for creating shareable, interactive visualizations",
+        prog="figpack",
+    )
+    parser.add_argument("--version", action="version", version=f"figpack {__version__}")
+
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # Download command
+    download_parser = subparsers.add_parser(
+        "download", help="Download a figure from a figpack URL"
+    )
+    download_parser.add_argument("figure_url", help="The figpack URL to download")
+    download_parser.add_argument("dest", help="Destination path for the tar.gz file")
+
+    # View command
+    view_parser = subparsers.add_parser(
+        "view", help="Extract and serve a figure archive locally"
+    )
+    view_parser.add_argument("archive", help="Path to the tar.gz archive file")
+    view_parser.add_argument(
+        "--port", type=int, help="Port number to serve on (default: auto-select)"
+    )
+
+    args = parser.parse_args()
+
+    if args.command == "download":
+        download_figure(args.figure_url, args.dest)
+    elif args.command == "view":
+        view_figure(args.archive, port=args.port)
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

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: