figpack 0.2.17__py3-none-any.whl → 0.2.40__py3-none-any.whl

figpack/core/_zarr_consolidate.py

@@ -0,0 +1,185 @@
+import os
+import pathlib
+import json
+from typing import Dict, List, Tuple
+
+
+def consolidate_zarr_chunks(
+    zarr_dir: pathlib.Path, max_file_size: int = 100_000_000
+) -> None:
+    """
+    Consolidate zarr chunk files into larger files to reduce the number of files
+    that need to be uploaded. Updates the .zmetadata file with refs mapping.
+
+    Args:
+        zarr_dir: Path to the zarr directory
+        max_file_size: Maximum size for each consolidated file in bytes (default: 100 MB)
+    """
+    if not zarr_dir.is_dir():
+        raise ValueError(f"Expected a directory, got: {zarr_dir}")
+
+    # Read the existing .zmetadata file
+    zmetadata_path = zarr_dir / ".zmetadata"
+    if not zmetadata_path.exists():
+        raise ValueError(f"No .zmetadata file found at {zmetadata_path}")
+
+    with open(zmetadata_path, "r") as f:
+        zmetadata = json.load(f)
+
+    # Collect all chunk files (non-metadata files)
+    chunk_files = _collect_chunk_files(zarr_dir)
+
+    if not chunk_files:
+        # No chunk files to consolidate
+        return
+
+    # Group chunk files into consolidated files
+    consolidated_groups = _group_files_by_size(chunk_files, max_file_size)
+
+    # Create consolidated files and build refs mapping
+    refs: Dict[str, List] = {}
+    for group_idx, file_group in enumerate(consolidated_groups):
+        consolidated_filename = f"_consolidated_{group_idx}.dat"
+        consolidated_path = zarr_dir / consolidated_filename
+
+        # Write the consolidated file and track byte offsets
+        current_offset = 0
+        with open(consolidated_path, "wb") as consolidated_file:
+            for file_path, relative_path in file_group:
+                # Read the chunk file
+                with open(file_path, "rb") as chunk_file:
+                    chunk_data = chunk_file.read()
+
+                # Write to consolidated file
+                consolidated_file.write(chunk_data)
+
+                # Add to refs mapping
+                refs[relative_path] = [
+                    consolidated_filename,
+                    current_offset,
+                    len(chunk_data),
+                ]
+
+                # Update offset
+                current_offset += len(chunk_data)
+
+    # Update .zmetadata with refs
+    zmetadata["refs"] = refs
+
+    # Write updated .zmetadata
+    with open(zmetadata_path, "w") as f:
+        json.dump(zmetadata, f, indent=2)
+
+    # Delete original chunk files
+    for file_path, _ in chunk_files:
+        try:
+            file_path.unlink()
+        except Exception as e:
+            print(f"Warning: could not remove file {file_path}: {e}")
+
+    # Clean up empty directories
+    _remove_empty_directories(zarr_dir)
+
+
+def _collect_chunk_files(zarr_dir: pathlib.Path) -> List[Tuple[pathlib.Path, str]]:
+    """
+    Collect all chunk files in the zarr directory (excluding metadata files).
+
+    Args:
+        zarr_dir: Path to the zarr directory
+
+    Returns:
+        List of tuples (absolute_path, relative_path) for each chunk file
+    """
+    chunk_files = []
+    metadata_files = {".zmetadata", ".zarray", ".zgroup", ".zattrs"}
+
+    for root, dirs, files in os.walk(zarr_dir):
+        for file in files:
+            # Skip metadata files
+            if file in metadata_files or file.startswith("_consolidated_"):
+                continue
+
+            file_path = pathlib.Path(root) / file
+            # Get relative path from zarr_dir
+            relative_path = file_path.relative_to(zarr_dir).as_posix()
+
+            chunk_files.append((file_path, relative_path))
+
+    return chunk_files
+
+
+def _group_files_by_size(
+    files: List[Tuple[pathlib.Path, str]], max_size: int
+) -> List[List[Tuple[pathlib.Path, str]]]:
+    """
+    Group files into bins where each bin's total size is <= max_size.
+
+    Uses a simple first-fit bin packing algorithm.
+
+    Args:
+        files: List of (file_path, relative_path) tuples
+        max_size: Maximum total size for each group in bytes
+
+    Returns:
+        List of groups, where each group is a list of (file_path, relative_path) tuples
+    """
+    # Get file sizes
+    files_with_sizes = []
+    for file_path, relative_path in files:
+        try:
+            size = file_path.stat().st_size
+            files_with_sizes.append((file_path, relative_path, size))
+        except Exception as e:
+            print(f"Warning: could not get size of {file_path}: {e}")
+            continue
+
+    # Sort by size (largest first) for better packing
+    files_with_sizes.sort(key=lambda x: x[2], reverse=True)
+
+    # First-fit bin packing
+    groups: List[List[Tuple[pathlib.Path, str]]] = []
+    group_sizes: List[int] = []
+
+    for file_path, relative_path, size in files_with_sizes:
+        # If file is larger than max_size, put it in its own group
+        if size > max_size:
+            groups.append([(file_path, relative_path)])
+            group_sizes.append(size)
+            continue
+
+        # Try to fit into existing group
+        placed = False
+        for i, group_size in enumerate(group_sizes):
+            if group_size + size <= max_size:
+                groups[i].append((file_path, relative_path))
+                group_sizes[i] += size
+                placed = True
+                break
+
+        # If doesn't fit anywhere, create new group
+        if not placed:
+            groups.append([(file_path, relative_path)])
+            group_sizes.append(size)
+
+    return groups
+
+
+def _remove_empty_directories(zarr_dir: pathlib.Path) -> None:
+    """
+    Remove empty directories within the zarr directory.
+
+    Args:
+        zarr_dir: Path to the zarr directory
+    """
+    # Walk bottom-up so we can remove empty parent directories
+    for root, dirs, files in os.walk(zarr_dir, topdown=False):
+        for dir_name in dirs:
+            dir_path = pathlib.Path(root) / dir_name
+            try:
+                # Only remove if directory is empty
+                if not any(dir_path.iterdir()):
+                    dir_path.rmdir()
+            except Exception:
+                # Directory not empty or other error, skip
+                pass

figpack/core/extension_view.py

@@ -2,9 +2,13 @@
 Base class for views that use figpack extensions
 """
 
+from typing import TYPE_CHECKING
+
 from .figpack_view import FigpackView
-from .figpack_extension import FigpackExtension
-from ..core.zarr import Group
+
+if TYPE_CHECKING:
+    from .figpack_extension import FigpackExtension
+    from .zarr import Group
 
 
 class ExtensionView(FigpackView):
@@ -12,7 +16,7 @@ class ExtensionView(FigpackView):
     Base class for views that are rendered by figpack extensions
     """
 
-    def __init__(self, *, extension: FigpackExtension, view_type: str):
+    def __init__(self, *, extension: "FigpackExtension", view_type: str) -> None:
         """
         Initialize an extension-based view
 
@@ -23,10 +27,10 @@ class ExtensionView(FigpackView):
         self.extension = extension
         self.view_type = view_type
 
-    def _write_to_zarr_group(self, group: Group) -> None:
+    def write_to_zarr_group(self, group: "Group") -> None:
         """
         Write the extension view metadata to a Zarr group.
-        Subclasses should call super()._write_to_zarr_group(group) first,
+        Subclasses should call super().write_to_zarr_group(group) first,
         then add their own data.
 
         Args:

figpack/core/figpack_extension.py

@@ -17,7 +17,7 @@ class FigpackExtension:
         javascript_code: str,
         additional_files: Optional[Dict[str, str]] = None,
         version: str = "1.0.0",
-    ):
+    ) -> None:
         """
         Initialize a figpack extension
 

figpack/core/figpack_view.py

@@ -5,7 +5,7 @@ Base view class for figpack visualization components
 import os
 import random
 import string
-from typing import Union
+from typing import Optional
 
 from .zarr import Group
 
@@ -19,17 +19,17 @@ class FigpackView:
         self,
         *,
         title: str,
-        description: Union[str, None] = None,
-        port: Union[int, None] = None,
-        open_in_browser: Union[bool, None] = None,
-        upload: Union[bool, None] = None,
-        inline: Union[bool, None] = None,
+        description: Optional[str] = None,
+        port: Optional[int] = None,
+        open_in_browser: Optional[bool] = None,
+        upload: Optional[bool] = None,
+        inline: Optional[bool] = None,
         inline_height: int = 600,
-        ephemeral: Union[bool, None] = None,
-        allow_origin: Union[str, None] = None,
-        wait_for_input: Union[bool, None] = None,
-        _dev: Union[bool, None] = None,
-    ):
+        ephemeral: Optional[bool] = None,
+        allow_origin: Optional[str] = None,
+        wait_for_input: Optional[bool] = None,
+        _dev: Optional[bool] = None,
+    ) -> None:
         """
         Display a figpack view component with intelligent environment detection and flexible display options.
         See https://flatironinstitute.github.io/figpack/show_function.html for complete documentation.
@@ -60,13 +60,23 @@ class FigpackView:
 
         # determine upload
         if upload is None:
-            upload = os.environ.get("FIGPACK_UPLOAD") == "1"
-        else:
-            if upload is True and ephemeral is True:
+            if os.environ.get("FIGPACK_UPLOAD") == "1":
+                upload = True
+            elif os.environ.get("FIGPACK_UPLOAD") == "0":
+                upload = False
+
+        if upload is True:
+            if ephemeral is True:
                 # ephemeral is reserved for the case where we don't specify upload
                 # and we are in a notebook in a remote environment such as
                 # colab or jupyterhub
-                raise ValueError("ephemeral cannot be set if upload is set")
+                raise ValueError(
+                    "ephemeral cannot be set to True if upload is set to True"
+                )
+            else:
+                ephemeral = (
+                    False  # if we excplicitly set upload=True, force ephemeral=False
+                )
 
         # determine inline
         if inline is None:
@@ -76,15 +86,22 @@ class FigpackView:
                 inline = False
             elif _is_in_notebook() and not upload:
                 inline = True
+            else:
+                inline = False
 
         # determine open_in_browser
         if open_in_browser is None:
             open_in_browser = os.environ.get("FIGPACK_OPEN_IN_BROWSER") == "1"
 
         # determine ephemeral
-        if ephemeral is None:
+        if ephemeral is None and not upload:
             ephemeral = False  # default to False
-            if _is_in_notebook():
+            if os.environ.get("FIGPACK_REMOTE_ENV") == "1":
+                ephemeral = True
+                upload = True
+            elif os.environ.get("FIGPACK_REMOTE_ENV") == "0":
+                ephemeral = False
+            elif _is_in_notebook():
                 if _is_in_colab():
                     # if we are in a notebook and in colab, we should show as uploaded ephemeral
                     print("Detected Google Colab notebook environment.")
@@ -96,10 +113,22 @@ class FigpackView:
                     upload = True
                     ephemeral = True
 
+        if ephemeral is None:
+            ephemeral = False
+
+        if upload is None:
+            upload = False
+
         # determine _dev
         if _dev is None:
             _dev = os.environ.get("FIGPACK_DEV") == "1"
 
+        if port is None and os.environ.get("FIGPACK_PORT"):
+            try:
+                port = int(os.environ.get("FIGPACK_PORT", ""))
+            except Exception:
+                pass
+
         # determine wait_for_input
         if wait_for_input is None:
             wait_for_input = not _is_in_notebook()
@@ -108,6 +137,8 @@ class FigpackView:
         if ephemeral and not upload:
             raise ValueError("ephemeral=True requires upload=True to be set")
 
+        _local_figure_name: Optional[str] = None
+
         if _dev:
             if open_in_browser:
                 print("** Note: In dev mode, open_in_browser is forced to False **")
@@ -145,7 +176,7 @@ class FigpackView:
             _local_figure_name=_local_figure_name if _dev else None,
         )
 
-    def save(self, output_path: str, *, title: str) -> None:
+    def save(self, output_path: str, *, title: str, description: str = "") -> None:
         """
         Save as figure either to a folder or to a .tar.gz file
         Args:
@@ -153,13 +184,13 @@ class FigpackView:
         """
         from ._save_figure import _save_figure
 
-        _save_figure(self, output_path, title=title)
+        _save_figure(self, output_path, title=title, description=description)
 
-    def _write_to_zarr_group(self, group: Group) -> None:
+    def write_to_zarr_group(self, group: 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")
+        raise NotImplementedError("Subclasses must implement write_to_zarr_group")

figpack/core/zarr.py

@@ -33,13 +33,13 @@ class Group:
         if _check_zarr_version() == 2:
             self._zarr_group.create_dataset(name, **kwargs)
         elif _check_zarr_version() == 3:
-            self._zarr_group.create_array(name, **kwargs)
+            self._zarr_group.create_array(name, **kwargs)  # type: ignore
         else:
             raise RuntimeError("Unsupported Zarr version")
 
     @property
     def attrs(self) -> Dict[str, Any]:
-        return self._zarr_group.attrs
+        return self._zarr_group.attrs  # type: ignore
 
     def __getitem__(self, key: str) -> Any:
         return self._zarr_group[key]