figpack 0.2.35__tar.gz → 0.2.37__tar.gz

{figpack-0.2.35/figpack.egg-info → figpack-0.2.37}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: figpack
-Version: 0.2.35
+Version: 0.2.37
 Summary: A Python package for creating shareable, interactive visualizations in the browser
 Author-email: Jeremy Magland <jmagland@flatironinstitute.org>
 License: Apache-2.0
@@ -114,6 +114,27 @@ graph.show(open_in_browser=True, title="Quick Start Example")
 
 Apache-2.0
 
+## Citation
+
+If you use figpack in your research, please cite it:
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.17419621.svg)](https://doi.org/10.5281/zenodo.17419621)
+
+```bibtex
+@software{magland_figpack_2025,
+  author       = {Magland, Jeremy},
+  title        = {figpack},
+  year         = 2025,
+  publisher    = {Zenodo},
+  doi          = {10.5281/zenodo.17419621},
+  url          = {https://doi.org/10.5281/zenodo.17419621}
+}
+```
+
+Or in APA format:
+
+> Magland, J. (2025). figpack (Version 0.2.37) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.17419621
+
 ## Contributing
 
 Visit the [GitHub repository](https://github.com/flatironinstitute/figpack) for issues, contributions, and the latest updates.

{figpack-0.2.35 → figpack-0.2.37}/README.md

@@ -38,6 +38,27 @@ graph.show(open_in_browser=True, title="Quick Start Example")
 
 Apache-2.0
 
+## Citation
+
+If you use figpack in your research, please cite it:
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.17419621.svg)](https://doi.org/10.5281/zenodo.17419621)
+
+```bibtex
+@software{magland_figpack_2025,
+  author       = {Magland, Jeremy},
+  title        = {figpack},
+  year         = 2025,
+  publisher    = {Zenodo},
+  doi          = {10.5281/zenodo.17419621},
+  url          = {https://doi.org/10.5281/zenodo.17419621}
+}
+```
+
+Or in APA format:
+
+> Magland, J. (2025). figpack (Version 0.2.37) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.17419621
+
 ## Contributing
 
 Visit the [GitHub repository](https://github.com/flatironinstitute/figpack) for issues, contributions, and the latest updates.

{figpack-0.2.35 → figpack-0.2.37}/figpack/__init__.py

@@ -2,7 +2,7 @@
 figpack - A Python package for creating shareable, interactive visualizations in the browser
 """
 
-__version__ = "0.2.35"
+__version__ = "0.2.37"
 
 from .cli import view_figure
 from .core import FigpackView, FigpackExtension, ExtensionView

{figpack-0.2.35 → figpack-0.2.37}/figpack/cli.py

@@ -18,6 +18,7 @@ import requests
 from . import __version__
 from .core._server_manager import CORSRequestHandler
 from .core._view_figure import serve_files, view_figure
+from .core._upload_bundle import _upload_bundle, get_figure_by_source_url
 from .extensions import ExtensionManager
 
 MAX_WORKERS_FOR_DOWNLOAD = 16
@@ -249,6 +250,188 @@ def handle_extensions_command(args):
         print("Use 'figpack extensions <command> --help' for more information.")
 
 
+def handle_upload_from_source_url(args) -> None:
+    """
+    Handle the upload-from-source-url command
+
+    Downloads a tar.gz/tgz file from a URL, extracts it, and uploads it as a new figure
+    with the source URL set.
+    """
+    import os
+
+    source_url = args.source_url
+    title = args.title if hasattr(args, "title") else None
+
+    # Get API key from environment variable
+    api_key = os.environ.get("FIGPACK_API_KEY")
+    if not api_key:
+        print(
+            "Error: FIGPACK_API_KEY environment variable must be set to upload figures."
+        )
+        sys.exit(1)
+
+    # Validate URL format
+    if not (source_url.endswith(".tar.gz") or source_url.endswith(".tgz")):
+        print(f"Error: Source URL must point to a .tar.gz or .tgz file: {source_url}")
+        sys.exit(1)
+
+    print(f"Downloading archive from: {source_url}")
+
+    try:
+        # Download the archive
+        response = requests.get(source_url, timeout=120, stream=True)
+        response.raise_for_status()
+
+        # Create temporary file for the archive
+        with tempfile.NamedTemporaryFile(
+            suffix=".tar.gz", delete=False
+        ) as temp_archive:
+            archive_path = temp_archive.name
+
+            # Download with progress indication
+            total_size = int(response.headers.get("content-length", 0))
+            downloaded_size = 0
+
+            for chunk in response.iter_content(chunk_size=8192):
+                if chunk:
+                    temp_archive.write(chunk)
+                    downloaded_size += len(chunk)
+                    if total_size > 0:
+                        progress = (downloaded_size / total_size) * 100
+                        print(
+                            f"Downloaded: {downloaded_size / (1024*1024):.2f} MB ({progress:.1f}%)",
+                            end="\r",
+                        )
+
+            if total_size > 0:
+                print()  # New line after progress
+            print(f"Download complete: {downloaded_size / (1024*1024):.2f} MB")
+
+        # Extract archive to temporary directory
+        print("Extracting archive...")
+        with tempfile.TemporaryDirectory() as extract_dir:
+            extract_path = pathlib.Path(extract_dir)
+
+            try:
+                with tarfile.open(archive_path, "r:gz") as tar:
+                    tar.extractall(path=extract_path)
+                print(f"Extracted to temporary directory")
+            except Exception as e:
+                print(f"Error: Failed to extract archive: {e}")
+                sys.exit(1)
+            finally:
+                # Clean up downloaded archive
+                import os
+
+                try:
+                    os.unlink(archive_path)
+                except Exception:
+                    pass
+
+            # Upload the extracted files
+            print(f"Uploading figure with source URL: {source_url}")
+            try:
+                figure_url = _upload_bundle(
+                    str(extract_path),
+                    api_key=api_key,
+                    title=title,
+                    source_url=source_url,
+                )
+                print(f"\nFigure uploaded successfully!")
+                print(f"Figure URL: {figure_url}")
+            except Exception as e:
+                print(f"Error: Failed to upload figure: {e}")
+                sys.exit(1)
+
+    except requests.exceptions.RequestException as e:
+        print(f"Error: Failed to download archive from {source_url}: {e}")
+        sys.exit(1)
+    except Exception as e:
+        print(f"Error: {e}")
+        sys.exit(1)
+
+
+def handle_find_by_source_url(args) -> None:
+    """
+    Handle the find-by-source-url command
+
+    Queries the API for a figure URL by its source URL.
+    """
+    source_url = args.source_url
+
+    print(f"Querying for figure with source URL: {source_url}")
+
+    try:
+        figure_url = get_figure_by_source_url(source_url)
+
+        if figure_url:
+            print(f"Figure found: {figure_url}")
+        else:
+            print(f"No figure found with source URL: {source_url}")
+            sys.exit(1)
+    except Exception as e:
+        print(f"Error: {e}")
+        sys.exit(1)
+
+
+def download_and_view_archive(url: str, port: int = None) -> None:
+    """
+    Download a tar.gz/tgz archive from a URL and view it
+
+    Args:
+        url: URL to the tar.gz or tgz file
+        port: Optional port number to serve on
+    """
+    if not (url.endswith(".tar.gz") or url.endswith(".tgz")):
+        print(f"Error: URL must point to a .tar.gz or .tgz file: {url}")
+        sys.exit(1)
+
+    print(f"Downloading archive from: {url}")
+
+    try:
+        response = requests.get(url, timeout=60, stream=True)
+        response.raise_for_status()
+
+        # Create a temporary file to store the downloaded archive
+        with tempfile.NamedTemporaryFile(suffix=".tar.gz", delete=False) as temp_file:
+            temp_path = temp_file.name
+
+            # Download with progress indication
+            total_size = int(response.headers.get("content-length", 0))
+            downloaded_size = 0
+
+            for chunk in response.iter_content(chunk_size=8192):
+                if chunk:
+                    temp_file.write(chunk)
+                    downloaded_size += len(chunk)
+                    if total_size > 0:
+                        progress = (downloaded_size / total_size) * 100
+                        print(
+                            f"Downloaded: {downloaded_size / (1024*1024):.2f} MB ({progress:.1f}%)",
+                            end="\r",
+                        )
+
+            if total_size > 0:
+                print()  # New line after progress
+            print(f"Download complete: {downloaded_size / (1024*1024):.2f} MB")
+
+        # Now view the downloaded file
+        try:
+            view_figure(temp_path, port=port)
+        finally:
+            # Clean up the temporary file after viewing
+            import os
+
+            try:
+                os.unlink(temp_path)
+            except Exception:
+                pass
+
+    except requests.exceptions.RequestException as e:
+        print(f"Error: Failed to download archive from {url}: {e}")
+        sys.exit(1)
+
+
 def main():
     """Main CLI entry point"""
     parser = argparse.ArgumentParser(
@@ -270,7 +453,7 @@ def main():
     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("archive", help="Path or URL to the tar.gz archive file")
     view_parser.add_argument(
         "--port", type=int, help="Port number to serve on (default: auto-select)"
     )
@@ -312,14 +495,43 @@ def main():
         "extensions", nargs="+", help="Extension package names to uninstall"
     )
 
+    # Upload from URL command
+    upload_from_source_url_parser = subparsers.add_parser(
+        "upload-from-source-url",
+        help="Download a tar.gz/tgz file and upload it as a new figure",
+    )
+    upload_from_source_url_parser.add_argument(
+        "source_url",
+        help="URL to the tar.gz or tgz file (will be set as the figure's source URL)",
+    )
+    upload_from_source_url_parser.add_argument(
+        "--title", help="Optional title for the figure"
+    )
+
+    # Find by source URL command
+    find_by_source_url_parser = subparsers.add_parser(
+        "find-by-source-url", help="Get the figure URL for a given source URL"
+    )
+    find_by_source_url_parser.add_argument(
+        "source_url", help="The source URL to search for"
+    )
+
     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)
+        # Check if archive argument is a URL
+        if args.archive.startswith("http://") or args.archive.startswith("https://"):
+            download_and_view_archive(args.archive, port=args.port)
+        else:
+            view_figure(args.archive, port=args.port)
     elif args.command == "extensions":
         handle_extensions_command(args)
+    elif args.command == "upload-from-source-url":
+        handle_upload_from_source_url(args)
+    elif args.command == "find-by-source-url":
+        handle_find_by_source_url(args)
     else:
         parser.print_help()
 

{figpack-0.2.35 → figpack-0.2.37}/figpack/core/_bundle_utils.py

@@ -1,7 +1,7 @@
 import os
 import pathlib
 import json
-from typing import Set
+from typing import Optional, List
 
 import zarr
 
@@ -14,7 +14,7 @@ thisdir = pathlib.Path(__file__).parent.resolve()
 
 
 def prepare_figure_bundle(
-    view: FigpackView, tmpdir: str, *, title: str, description: str = None
+    view: FigpackView, tmpdir: str, *, title: str, description: Optional[str] = None
 ) -> None:
     """
     Prepare a figure bundle in the specified temporary directory.
@@ -51,8 +51,8 @@ def prepare_figure_bundle(
     # because we only support version 2 on the frontend right now.
 
     if _check_zarr_version() == 3:
-        old_default_zarr_format = zarr.config.get("default_zarr_format")
-        zarr.config.set({"default_zarr_format": 2})
+        old_default_zarr_format = zarr.config.get("default_zarr_format")  # type: ignore
+        zarr.config.set({"default_zarr_format": 2})  # type: ignore
 
     try:
         # Write the view data to the Zarr group
@@ -80,7 +80,7 @@ def prepare_figure_bundle(
         _remove_metadata_files_except_consolidated(pathlib.Path(tmpdir) / "data.zarr")
     finally:
         if _check_zarr_version() == 3:
-            zarr.config.set({"default_zarr_format": old_default_zarr_format})
+            zarr.config.set({"default_zarr_format": old_default_zarr_format})  # type: ignore
 
 
 def _remove_metadata_files_except_consolidated(zarr_dir: pathlib.Path) -> None:
@@ -107,7 +107,7 @@ def _remove_metadata_files_except_consolidated(zarr_dir: pathlib.Path) -> None:
                     print(f"Warning: could not remove file {file_path}: {e}")
 
 
-def _discover_required_extensions(view: FigpackView) -> Set[str]:
+def _discover_required_extensions(view: FigpackView) -> List[str]:
     """
     Recursively discover all extensions required by a view and its children
 

{figpack-0.2.35 → figpack-0.2.37}/figpack/core/_file_handler.py

@@ -187,6 +187,6 @@ class FileUploadCORSRequestHandler(CORSRequestHandler):
             self.send_error(500, f"Internal Server Error: {str(e)}")
             return False
 
-    def log_message(self, fmt, *args):
+    def log_message(self, format, *args):
         """Override to suppress default logging (same as parent class)."""
         pass

{figpack-0.2.35 → figpack-0.2.37}/figpack/core/_save_figure.py

@@ -15,9 +15,9 @@ def _save_figure(
         view: FigpackView instance to save
         output_path: Output path (destination folder or .tar.gz file path)
     """
-    output_path = pathlib.Path(output_path)
-    if (output_path.suffix == ".gz" and output_path.suffixes[-2] == ".tar") or (
-        output_path.suffix == ".tgz"
+    output_path_2 = pathlib.Path(output_path)
+    if (output_path_2.suffix == ".gz" and output_path_2.suffixes[-2] == ".tar") or (
+        output_path_2.suffix == ".tgz"
     ):
         # It's a .tar.gz file
         with tempfile.TemporaryDirectory(prefix="figpack_save_") as tmpdir:
@@ -25,11 +25,11 @@ def _save_figure(
             # Create tar.gz file
             import tarfile
 
-            with tarfile.open(output_path, "w:gz") as tar:
+            with tarfile.open(output_path_2, "w:gz") as tar:
                 tar.add(tmpdir, arcname=".")
     else:
         # It's a folder
-        output_path.mkdir(parents=True, exist_ok=True)
+        output_path_2.mkdir(parents=True, exist_ok=True)
         prepare_figure_bundle(
-            view, str(output_path), title=title, description=description
+            view, str(output_path_2), title=title, description=description
         )

{figpack-0.2.35 → figpack-0.2.37}/figpack/core/_server_manager.py

@@ -45,7 +45,7 @@ class CORSRequestHandler(SimpleHTTPRequestHandler):
         """Reject PUT requests when file upload is not enabled."""
         self.send_error(405, "Method Not Allowed")
 
-    def log_message(self, fmt, *args):
+    def log_message(self, format, *args):
         pass
 
 
@@ -189,6 +189,7 @@ class ProcessServerManager:
             and self._server_thread.is_alive()
             and (allow_origin is None or self._allow_origin == allow_origin)
         ):
+            assert self._port is not None
             return f"http://localhost:{self._port}", self._port
 
         # Stop existing server if settings are incompatible
@@ -209,7 +210,7 @@ class ProcessServerManager:
         if enable_file_upload:
             from ._file_handler import FileUploadCORSRequestHandler
 
-            def handler_factory(*args, **kwargs):
+            def handler_factory_enable_upload(*args, **kwargs):
                 return FileUploadCORSRequestHandler(
                     *args,
                     directory=str(temp_dir),
@@ -219,6 +220,11 @@ class ProcessServerManager:
                     **kwargs,
                 )
 
+            assert port is not None
+            self._server = ThreadingHTTPServer(
+                ("0.0.0.0", port), handler_factory_enable_upload
+            )
+
         else:
 
             def handler_factory(*args, **kwargs):
@@ -226,7 +232,8 @@ class ProcessServerManager:
                     *args, directory=str(temp_dir), allow_origin=allow_origin, **kwargs
                 )
 
-        self._server = ThreadingHTTPServer(("0.0.0.0", port), handler_factory)
+            assert port is not None
+            self._server = ThreadingHTTPServer(("0.0.0.0", port), handler_factory)
         self._port = port
         self._allow_origin = allow_origin
 

{figpack-0.2.35 → figpack-0.2.37}/figpack/core/_show_view.py

@@ -19,7 +19,7 @@ def _is_in_notebook() -> bool:
     """
     try:
         # Check if IPython is available and we're in a notebook
-        from IPython import get_ipython
+        from IPython import get_ipython  # type: ignore
 
         ipython = get_ipython()
         if ipython is None:

{figpack-0.2.35 → figpack-0.2.37}/figpack/core/_upload_bundle.py

@@ -1,3 +1,4 @@
+from typing import Optional, Union
 import hashlib
 import json
 import pathlib
@@ -114,62 +115,31 @@ def _upload_single_file_with_signed_url(
         else:
             break
 
+    assert last_exception is not None
     raise last_exception
 
 
 MAX_WORKERS_FOR_UPLOAD = 16
 
 
-def _compute_deterministic_figure_hash(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 _create_or_get_figure(
-    figure_hash: str,
-    api_key: str,
-    total_files: int = None,
-    total_size: int = None,
-    title: str = None,
+    api_key: Optional[str],
+    total_files: Optional[int] = None,
+    total_size: Optional[int] = None,
+    title: Optional[str] = None,
     ephemeral: bool = False,
+    source_url: Optional[str] = None,
 ) -> 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 (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
+        source_url: Optional source URL for the figure (must be unique)
 
     Returns:
         dict: Figure information from the API
@@ -178,8 +148,7 @@ def _create_or_get_figure(
     if not ephemeral and api_key is None:
         raise ValueError("API key is required for non-ephemeral figures")
 
-    payload = {
-        "figureHash": figure_hash,
+    payload: dict[str, Union[str, int]] = {
         "figpackVersion": __version__,
         "bucket": FIGPACK_BUCKET,
     }
@@ -196,6 +165,8 @@ def _create_or_get_figure(
         payload["title"] = title
     if ephemeral:
         payload["ephemeral"] = True
+    if source_url is not None:
+        payload["sourceUrl"] = source_url
 
     # Use the same endpoint for both regular and ephemeral figures
     response = requests.post(f"{FIGPACK_API_BASE_URL}/api/figures/create", json=payload)
@@ -206,12 +177,12 @@ def _create_or_get_figure(
             error_msg = error_data.get("message", "Unknown error")
         except:
             error_msg = f"HTTP {response.status_code}"
-        raise Exception(f"Failed to create figure {figure_hash}: {error_msg}")
+        raise Exception(f"Failed to create figure: {error_msg}")
 
     response_data = response.json()
     if not response_data.get("success"):
         raise Exception(
-            f"Failed to create figure {figure_hash}: {response_data.get('message', 'Unknown error')}"
+            f"Failed to create figure: {response_data.get('message', 'Unknown error')}"
         )
 
     return response_data
@@ -252,10 +223,11 @@ def _finalize_figure(figure_url: str, api_key: str) -> dict:
 
 def _upload_bundle(
     tmpdir: str,
-    api_key: str,
-    title: str = None,
+    api_key: Optional[str],
+    title: Optional[str] = None,
     ephemeral: bool = False,
     use_consolidated_metadata_only: bool = False,
+    source_url: Optional[str] = None,
 ) -> str:
     """
     Upload the prepared bundle to the cloud using the new database-driven approach
@@ -267,12 +239,10 @@ def _upload_bundle(
         ephemeral: Whether to create an ephemeral figure
         use_consolidated_metadata_only: If True, excludes individual zarr metadata files
             (.zgroup, .zarray, .zattrs) since they are included in .zmetadata
+        source_url: Optional source URL for the figure (must be unique)
     """
     tmpdir_path = pathlib.Path(tmpdir)
 
-    # Compute deterministic figure ID based on file contents
-    figure_hash = _compute_deterministic_figure_hash(tmpdir_path)
-
     # Collect all files to upload
     all_files = []
     for file_path in tmpdir_path.rglob("*"):
@@ -293,7 +263,12 @@ def _upload_bundle(
 
     # 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, ephemeral=ephemeral
+        api_key,
+        total_files,
+        total_size,
+        title=title,
+        ephemeral=ephemeral,
+        source_url=source_url,
     )
     figure_info = result.get("figure", {})
     figure_url = figure_info.get("figureUrl")
@@ -329,7 +304,9 @@ def _upload_bundle(
 
             # Get signed URLs for this batch
             try:
-                signed_urls_map = _get_batch_signed_urls(figure_url, batch, api_key)
+                signed_urls_map = _get_batch_signed_urls(
+                    figure_url, batch, api_key if api_key else ""
+                )
             except Exception as e:
                 print(f"Failed to get signed URLs for batch {batch_num}: {e}")
                 raise
@@ -400,7 +377,9 @@ def _upload_bundle(
     try:
         # Use batch API for manifest
         manifest_batch = [("manifest.json", temp_file_path)]
-        signed_urls_map = _get_batch_signed_urls(figure_url, manifest_batch, api_key)
+        signed_urls_map = _get_batch_signed_urls(
+            figure_url, manifest_batch, api_key if api_key else ""
+        )
 
         if "manifest.json" not in signed_urls_map:
             raise Exception("No signed URL returned for manifest.json")
@@ -418,12 +397,45 @@ def _upload_bundle(
 
     # Finalize the figure upload
     print("Finalizing figure...")
-    _finalize_figure(figure_url, api_key)
+    _finalize_figure(figure_url, api_key if api_key else "")
     print("Upload completed successfully")
 
     return figure_url
 
 
+def get_figure_by_source_url(source_url: str) -> Optional[str]:
+    """
+    Query the API for a figure URL by its source URL
+
+    Args:
+        source_url: The source URL to search for
+
+    Returns:
+        Optional[str]: The figure URL if found, None otherwise
+    """
+    payload = {"sourceUrl": source_url}
+
+    response = requests.post(
+        f"{FIGPACK_API_BASE_URL}/api/figures/find-by-source-url", json=payload
+    )
+
+    if not response.ok:
+        if response.status_code == 404:
+            return None
+        try:
+            error_data = response.json()
+            error_msg = error_data.get("message", "Unknown error")
+        except:
+            error_msg = f"HTTP {response.status_code}"
+        raise Exception(f"Failed to query figure by source URL: {error_msg}")
+
+    response_data = response.json()
+    if not response_data.get("success"):
+        return None
+
+    return response_data.get("figureUrl")
+
+
 def _determine_content_type(file_path: str) -> str:
     """
     Determine content type for upload based on file extension