figpack 0.3.2__tar.gz → 0.3.5__tar.gz

{figpack-0.3.2/figpack.egg-info → figpack-0.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: figpack
-Version: 0.3.2
+Version: 0.3.5
 Summary: A Python package for creating shareable, interactive visualizations in the browser
 Author-email: Jeremy Magland <jmagland@flatironinstitute.org>
 License: Apache-2.0
@@ -133,7 +133,7 @@ If you use figpack in your research, please cite it:
 
 Or in APA format:
 
-> Magland, J. (2025). figpack (Version 0.3.2) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.17419621
+> Magland, J. (2025). figpack (Version 0.3.5) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.17419621
 
 ## Contributing
 

{figpack-0.3.2 → figpack-0.3.5}/README.md

@@ -57,7 +57,7 @@ If you use figpack in your research, please cite it:
 
 Or in APA format:
 
-> Magland, J. (2025). figpack (Version 0.3.2) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.17419621
+> Magland, J. (2025). figpack (Version 0.3.5) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.17419621
 
 ## Contributing
 

{figpack-0.3.2 → figpack-0.3.5}/figpack/__init__.py

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

{figpack-0.3.2 → figpack-0.3.5}/figpack/core/_bundle_utils.py

@@ -15,7 +15,12 @@ thisdir = pathlib.Path(__file__).parent.resolve()
 
 
 def prepare_figure_bundle(
-    view: FigpackView, tmpdir: str, *, title: str, description: Optional[str] = None
+    view: FigpackView,
+    tmpdir: str,
+    *,
+    title: str,
+    description: Optional[str] = None,
+    script: Optional[str] = None,
 ) -> None:
     """
     Prepare a figure bundle in the specified temporary directory.
@@ -31,6 +36,7 @@ def prepare_figure_bundle(
         tmpdir: The temporary directory to prepare the bundle in
         title: Title for the figure (required)
         description: Optional description for the figure (markdown supported)
+        script: Optional script text used to generate the figure
     """
     html_dir = thisdir / ".." / "figpack-figure-dist"
     if not os.path.exists(html_dir):
@@ -61,10 +67,12 @@ def prepare_figure_bundle(
         zarr_group = Group(zarr_group)
         view.write_to_zarr_group(zarr_group)
 
-        # Add title and description as attributes on the top-level zarr group
+        # Add title and description and script as attributes on the top-level zarr group
         zarr_group.attrs["title"] = title
-        if description is not None:
+        if description:
             zarr_group.attrs["description"] = description
+        if script:
+            zarr_group.attrs["script"] = script
 
         # Discover and write extension JavaScript files
         required_extensions = _discover_required_extensions(view)

{figpack-0.3.2 → figpack-0.3.5}/figpack/core/_save_figure.py

@@ -6,7 +6,12 @@ from .figpack_view import FigpackView
 
 
 def _save_figure(
-    view: FigpackView, output_path: str, *, title: str, description: str = ""
+    view: FigpackView,
+    output_path: str,
+    *,
+    title: str,
+    description: str = "",
+    script: str = "",
 ) -> None:
     """
     Save the figure to a folder or a .tar.gz file
@@ -14,6 +19,9 @@ def _save_figure(
     Args:
         view: FigpackView instance to save
         output_path: Output path (destination folder or .tar.gz file path)
+        title: Title for the figure
+        description: Description text with markdown support
+        script: Optional script text used to generate the figure
     """
     output_path_2 = pathlib.Path(output_path)
     if (output_path_2.suffix == ".gz" and output_path_2.suffixes[-2] == ".tar") or (
@@ -21,7 +29,9 @@ def _save_figure(
     ):
         # It's a .tar.gz file
         with tempfile.TemporaryDirectory(prefix="figpack_save_") as tmpdir:
-            prepare_figure_bundle(view, tmpdir, title=title, description=description)
+            prepare_figure_bundle(
+                view, tmpdir, title=title, description=description, script=script
+            )
             # Create tar.gz file
             import tarfile
 
@@ -31,5 +41,9 @@ def _save_figure(
         # It's a folder
         output_path_2.mkdir(parents=True, exist_ok=True)
         prepare_figure_bundle(
-            view, str(output_path_2), title=title, description=description
+            view,
+            str(output_path_2),
+            title=title,
+            description=description,
+            script=script,
         )

{figpack-0.3.2 → figpack-0.3.5}/figpack/core/_show_view.py

@@ -91,6 +91,7 @@ def _show_view(
     ephemeral: bool,
     title: str,
     description: Union[str, None],
+    script: Union[str, None],
     inline: bool,
     inline_height: int,
     wait_for_input: bool,
@@ -99,7 +100,9 @@ def _show_view(
     if upload:
         # Upload behavior: create temporary directory for this upload only
         with tempfile.TemporaryDirectory(prefix="figpack_upload_") as tmpdir:
-            prepare_figure_bundle(view, tmpdir, title=title, description=description)
+            prepare_figure_bundle(
+                view, tmpdir, title=title, description=description, script=script
+            )
 
             # Check for API key - required for regular uploads, optional for ephemeral
             api_key = os.environ.get("FIGPACK_API_KEY")
@@ -143,7 +146,7 @@ def _show_view(
 
         # Prepare the figure bundle in the subdirectory
         prepare_figure_bundle(
-            view, str(figure_dir), title=title, description=description
+            view, str(figure_dir), title=title, description=description, script=script
         )
 
         # Start or get existing server

{figpack-0.3.2 → figpack-0.3.5}/figpack/core/_view_figure.py

@@ -131,9 +131,7 @@ def view_figure(figure_path: str, port: Union[int, None] = None) -> None:
         )
         return
 
-    if not figure_pathlib.suffix.lower() in [".gz", ".tgz"] or not str(
-        figure_pathlib
-    ).endswith(".tar.gz"):
+    if not figure_path.endswith(".tar.gz") and not figure_path.endswith(".tgz"):
         print(f"Error: Archive file must be a .tar.gz file: {figure_path}")
         sys.exit(1)
 

{figpack-0.3.2 → figpack-0.3.5}/figpack/core/figpack_view.py

@@ -20,6 +20,7 @@ class FigpackView:
         *,
         title: str,
         description: Optional[str] = None,
+        script: Optional[str] = None,
         port: Optional[int] = None,
         open_in_browser: Optional[bool] = None,
         upload: Optional[bool] = None,
@@ -29,7 +30,7 @@ class FigpackView:
         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.
@@ -41,6 +42,7 @@ class FigpackView:
         Args:
             title: Title for browser tab and figure (required)
             description: Description text with markdown support (optional)
+            script: Optional script text used to generate the figure
             port: Local server port, random if None
             open_in_browser: Auto-open in browser, auto-detects by environment
             upload: Upload figure to figpack servers, auto-detects by environment
@@ -161,7 +163,7 @@ class FigpackView:
             )
             print("")
 
-        _show_view(
+        return _show_view(
             self,
             port=port,
             open_in_browser=open_in_browser,
@@ -170,21 +172,29 @@ class FigpackView:
             ephemeral=ephemeral,
             title=title,
             description=description,
+            script=script,
             inline=inline,
             inline_height=inline_height,
             wait_for_input=wait_for_input,
             _local_figure_name=_local_figure_name if _dev else None,
         )
 
-    def save(self, output_path: str, *, title: str, description: str = "") -> None:
+    def save(
+        self, output_path: str, *, title: str, description: str = "", script: str = ""
+    ) -> None:
         """
         Save as figure either to a folder or to a .tar.gz file
         Args:
             output_path: Output path (destination folder or .tar.gz file path)
+            title: Title for the figure
+            description: Description text with markdown support
+            script: Optional script text used to generate the figure
         """
         from ._save_figure import _save_figure
 
-        _save_figure(self, output_path, title=title, description=description)
+        _save_figure(
+            self, output_path, title=title, description=description, script=script
+        )
 
     def write_to_zarr_group(self, group: Group) -> None:
         """

figpack-0.3.5/figpack/core/zarr.py

@@ -0,0 +1,129 @@
+from typing import Any, Dict
+import numpy as np
+
+
+_UNSPECIFIED = object()
+
+
+class Group:
+    def __init__(self, zarr_group):
+        self._zarr_group = zarr_group
+
+    def create_group(self, name: str) -> "Group":
+        return Group(self._zarr_group.create_group(name))
+
+    def create_dataset(
+        self,
+        name: str,
+        *,
+        data=_UNSPECIFIED,
+        dtype=_UNSPECIFIED,
+        chunks=_UNSPECIFIED,
+        compressor=_UNSPECIFIED,
+    ) -> None:
+        kwargs = {}
+        if data is not _UNSPECIFIED:
+            kwargs["data"] = data
+        if dtype is not _UNSPECIFIED:
+            kwargs["dtype"] = dtype
+        if chunks is not _UNSPECIFIED:
+            kwargs["chunks"] = chunks
+        else:
+            if data is not _UNSPECIFIED:
+                chunks2 = _get_optimal_chunk_size(data.shape, data.dtype)
+                if chunks2 is not _UNSPECIFIED:
+                    kwargs["chunks"] = chunks2
+        if compressor is not _UNSPECIFIED:
+            kwargs["compressor"] = compressor
+        if _check_zarr_version() == 2:
+            self._zarr_group.create_dataset(name, **kwargs)
+        elif _check_zarr_version() == 3:
+            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  # type: ignore
+
+    def __getitem__(self, key: str) -> Any:
+        return self._zarr_group[key]
+
+    # implement in operator
+    def __contains__(self, key: str) -> bool:
+        return key in self._zarr_group
+
+    def __iter__(self):
+        return iter(self._zarr_group)
+
+    def __reversed__(self):
+        return reversed(self._zarr_group)
+
+
+def _check_zarr_version():
+    import zarr
+
+    version = zarr.__version__
+    major_version = int(version.split(".")[0])
+    return major_version
+
+
+def _get_optimal_chunk_size(shape: tuple, dtype) -> tuple:
+    """Compute an optimal chunk shape targeting ~5 MB per chunk,
+    chunking along only one dimension and avoiding mostly empty chunks.
+    """
+    target_bytes = 5 * 1024 * 1024  # 5 MB
+
+    if np.prod(shape) <= 1:
+        # all dimensions are zero or one
+        # return shape of unspecified to let zarr choose on this edge case
+        return _UNSPECIFIED
+
+    # Ensure dtype is a numpy dtype to get itemsize
+    if isinstance(dtype, str):
+        dtype = np.dtype(dtype)
+
+    itemsize = np.dtype(dtype).itemsize
+
+    # Total array size in bytes
+    total_bytes = np.prod(shape) * itemsize
+    if total_bytes <= target_bytes:
+        # Entire array fits comfortably in one chunk
+        return shape
+
+    # Choose the first non-singleton dimension to chunk along
+    for axis, dim in enumerate(shape):
+        if dim > 1:
+            break
+    else:
+        return shape  # all singleton
+
+    # Compute how many elements fit in target_bytes
+    target_elements = target_bytes // itemsize
+
+    # Compute product of all other dimensions (fixed)
+    other_size = np.prod(shape) // shape[axis]
+
+    # Determine chunk length along chosen axis
+    chunk_len = max(1, min(shape[axis], target_elements // other_size))
+
+    # Construct chunk shape
+    chunk_shape = list(shape)
+    chunk_shape[axis] = chunk_len
+
+    return tuple([int(c) for c in chunk_shape])
+
+
+if __name__ == "__main__":
+    # Test the _get_optimal_chunk_size function for a variety of shapes and dtypes
+    test_cases = [
+        ((1000, 1000), np.float32),
+        ((5000, 2000), np.uint8),
+        ((100, 100, 100), np.float64),
+        ((10, 30, 30, 1500), np.int16),
+        ((1, 1, 1), np.float32),
+    ]
+
+    for shape, dtype in test_cases:
+        chunk_size = _get_optimal_chunk_size(shape, dtype)
+        print(f"Optimal chunk size for shape {shape} and dtype {dtype}: {chunk_size}")