figpack 0.2.7__tar.gz → 0.2.9__tar.gz

{figpack-0.2.7/figpack.egg-info → figpack-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: figpack
-Version: 0.2.7
+Version: 0.2.9
 Summary: A Python package for creating shareable, interactive visualizations in the browser
 Author-email: Jeremy Magland <jmagland@flatironinstitute.org>
 License: Apache-2.0

figpack-0.2.9/figpack/__init__.py

@@ -0,0 +1,16 @@
+"""
+figpack - A Python package for creating shareable, interactive visualizations in the browser
+"""
+
+__version__ = "0.2.9"
+
+from .cli import view_figure
+from .core import FigpackView, FigpackExtension, ExtensionRegistry, ExtensionView
+
+__all__ = [
+    "view_figure",
+    "FigpackView",
+    "FigpackExtension",
+    "ExtensionRegistry",
+    "ExtensionView",
+]

figpack-0.2.9/figpack/core/__init__.py

@@ -0,0 +1,5 @@
+from .figpack_view import FigpackView
+from .figpack_extension import FigpackExtension, ExtensionRegistry
+from .extension_view import ExtensionView
+
+__all__ = ["FigpackView", "FigpackExtension", "ExtensionRegistry", "ExtensionView"]

figpack-0.2.9/figpack/core/_bundle_utils.py

@@ -0,0 +1,180 @@
+import os
+import pathlib
+from typing import Set
+
+import zarr
+
+from .figpack_view import FigpackView
+from .figpack_extension import ExtensionRegistry
+from .extension_view import ExtensionView
+
+thisdir = pathlib.Path(__file__).parent.resolve()
+
+
+def prepare_figure_bundle(
+    view: FigpackView, tmpdir: str, *, title: str, description: str = None
+) -> None:
+    """
+    Prepare a figure bundle in the specified temporary directory.
+
+    This function:
+    1. Copies all files from the figpack-figure-dist directory to tmpdir
+    2. Writes the view data to a zarr group
+    3. Discovers and writes extension JavaScript files
+    4. Consolidates zarr metadata
+
+    Args:
+        view: The figpack view to prepare
+        tmpdir: The temporary directory to prepare the bundle in
+        title: Title for the figure (required)
+        description: Optional description for the figure (markdown supported)
+    """
+    html_dir = thisdir / ".." / "figpack-figure-dist"
+    if not os.path.exists(html_dir):
+        raise SystemExit(f"Error: directory not found: {html_dir}")
+
+    # Copy all files in html_dir recursively to tmpdir
+    for item in html_dir.iterdir():
+        if item.is_file():
+            target = pathlib.Path(tmpdir) / item.name
+            target.write_bytes(item.read_bytes())
+        elif item.is_dir():
+            target = pathlib.Path(tmpdir) / item.name
+            target.mkdir(exist_ok=True)
+            for subitem in item.iterdir():
+                target_sub = target / subitem.name
+                target_sub.write_bytes(subitem.read_bytes())
+
+    # Write the view data to the Zarr group
+    zarr_group = zarr.open_group(
+        pathlib.Path(tmpdir) / "data.zarr",
+        mode="w",
+        synchronizer=zarr.ThreadSynchronizer(),
+    )
+    view._write_to_zarr_group(zarr_group)
+
+    # Add title and description as attributes on the top-level zarr group
+    zarr_group.attrs["title"] = title
+    if description is not None:
+        zarr_group.attrs["description"] = description
+
+    # Discover and write extension JavaScript files
+    required_extensions = _discover_required_extensions(view)
+    _write_extension_files(required_extensions, tmpdir)
+
+    zarr.consolidate_metadata(zarr_group.store)
+
+
+def _discover_required_extensions(view: FigpackView) -> Set[str]:
+    """
+    Recursively discover all extensions required by a view and its children
+
+    Args:
+        view: The root view to analyze
+
+    Returns:
+        Set of extension names required by this view hierarchy
+    """
+    extensions = set()
+    visited = set()  # Prevent infinite recursion
+
+    def _collect_extensions(v: FigpackView):
+        # Prevent infinite recursion
+        if id(v) in visited:
+            return
+        visited.add(id(v))
+
+        # Check if this view is an extension view
+        if isinstance(v, ExtensionView):
+            extensions.add(v.extension_name)
+
+        # Recursively check all attributes that might contain child views
+        for attr_name in dir(v):
+            if attr_name.startswith("_"):
+                continue
+
+            try:
+                attr_value = getattr(v, attr_name)
+
+                # Handle single child view
+                if isinstance(attr_value, FigpackView):
+                    _collect_extensions(attr_value)
+
+                # Handle lists/tuples of items that might contain views
+                elif isinstance(attr_value, (list, tuple)):
+                    for item in attr_value:
+                        # Check if item has a 'view' attribute (like LayoutItem)
+                        if hasattr(item, "view") and isinstance(item.view, FigpackView):
+                            _collect_extensions(item.view)
+                        # Or if the item itself is a view
+                        elif isinstance(item, FigpackView):
+                            _collect_extensions(item)
+
+                # Handle objects that might have a 'view' attribute
+                elif hasattr(attr_value, "view") and isinstance(
+                    attr_value.view, FigpackView
+                ):
+                    _collect_extensions(attr_value.view)
+
+            except (AttributeError, TypeError):
+                # Skip attributes that can't be accessed or aren't relevant
+                continue
+
+    _collect_extensions(view)
+    return extensions
+
+
+def _write_extension_files(extension_names: Set[str], tmpdir: str) -> None:
+    """
+    Write JavaScript files for the required extensions
+
+    Args:
+        extension_names: Set of extension names to write
+        tmpdir: Directory to write extension files to
+    """
+    if not extension_names:
+        return
+
+    registry = ExtensionRegistry.get_instance()
+    tmpdir_path = pathlib.Path(tmpdir)
+
+    for extension_name in extension_names:
+        extension = registry.get_extension(extension_name)
+        if extension is None:
+            raise RuntimeError(
+                f"Extension '{extension_name}' is required but not registered"
+            )
+
+        # Write the main JavaScript file
+        js_filename = extension.get_javascript_filename()
+        js_path = tmpdir_path / js_filename
+
+        # Add some metadata as comments at the top
+        js_content = f"""/*
+ * Figpack Extension: {extension.name}
+ * Version: {extension.version}
+ * Generated automatically - do not edit
+ */
+
+{extension.javascript_code}
+"""
+
+        js_path.write_text(js_content, encoding="utf-8")
+
+        # Write additional JavaScript files
+        additional_filenames = extension.get_additional_filenames()
+        for original_name, safe_filename in additional_filenames.items():
+            additional_content = extension.additional_files[original_name]
+            additional_path = tmpdir_path / safe_filename
+
+            # Add metadata header to additional files too
+            additional_js_content = f"""/*
+ * Figpack Extension Additional File: {extension.name}/{original_name}
+ * Version: {extension.version}
+ * Generated automatically - do not edit
+ */
+
+{additional_content}
+"""
+
+            additional_path.write_text(additional_js_content, encoding="utf-8")

figpack-0.2.9/figpack/core/extension_view.py

@@ -0,0 +1,53 @@
+"""
+Base class for views that use figpack extensions
+"""
+
+import zarr
+from .figpack_view import FigpackView
+from .figpack_extension import ExtensionRegistry
+
+
+class ExtensionView(FigpackView):
+    """
+    Base class for views that are rendered by figpack extensions
+    """
+
+    def __init__(self, *, extension_name: str):
+        """
+        Initialize an extension-based view
+
+        Args:
+            extension_name: Name of the extension that will render this view
+        """
+        super().__init__()
+        self.extension_name = extension_name
+
+        # Validate that the extension is registered
+        registry = ExtensionRegistry.get_instance()
+        extension = registry.get_extension(extension_name)
+        if extension is None:
+            raise ValueError(
+                f"Extension '{extension_name}' is not registered. "
+                f"Make sure to register the extension before creating views that use it."
+            )
+
+    def _write_to_zarr_group(self, group: zarr.Group) -> None:
+        """
+        Write the extension view metadata to a Zarr group.
+        Subclasses should call super()._write_to_zarr_group(group) first,
+        then add their own data.
+
+        Args:
+            group: Zarr group to write data into
+        """
+        # Set the view type to indicate this is an extension view
+        group.attrs["view_type"] = "ExtensionView"
+
+        # Store the extension name so the frontend knows which extension to use
+        group.attrs["extension_name"] = self.extension_name
+
+        # Store extension metadata for debugging/compatibility
+        registry = ExtensionRegistry.get_instance()
+        extension = registry.get_extension(self.extension_name)
+        if extension:
+            group.attrs["extension_version"] = extension.version

figpack-0.2.9/figpack/core/figpack_extension.py

@@ -0,0 +1,137 @@
+"""
+Extension system for figpack - allows runtime loading of custom view components
+"""
+
+from typing import Dict, Optional
+
+
+class FigpackExtension:
+    """
+    Base class for figpack extensions that provide custom view components
+    """
+
+    def __init__(
+        self,
+        *,
+        name: str,
+        javascript_code: str,
+        additional_files: Optional[Dict[str, str]] = None,
+        version: str = "1.0.0",
+    ):
+        """
+        Initialize a figpack extension
+
+        Args:
+            name: Unique name for the extension (used as identifier)
+            javascript_code: JavaScript code that implements the extension
+            additional_files: Optional dictionary of additional JavaScript files
+                            {filename: content} that the extension can load
+            version: Version string for compatibility tracking
+        """
+        self.name = name
+        self.javascript_code = javascript_code
+        self.additional_files = additional_files or {}
+        self.version = version
+
+        # Validate extension name
+        if not name or not isinstance(name, str):
+            raise ValueError("Extension name must be a non-empty string")
+
+        # Basic validation of JavaScript code
+        if not javascript_code or not isinstance(javascript_code, str):
+            raise ValueError("Extension javascript_code must be a non-empty string")
+
+    def get_javascript_filename(self) -> str:
+        """
+        Get the filename that should be used for this extension's JavaScript file
+
+        Returns:
+            Filename for the extension JavaScript file
+        """
+        # Sanitize the name for use as a filename
+        safe_name = "".join(c for c in self.name if c.isalnum() or c in "-_")
+        return f"extension-{safe_name}.js"
+
+    def get_additional_filenames(self) -> Dict[str, str]:
+        """
+        Get the filenames for additional JavaScript files
+
+        Returns:
+            Dictionary mapping original filenames to safe filenames
+        """
+        safe_name = "".join(c for c in self.name if c.isalnum() or c in "-_")
+        return {
+            original_name: f"extension-{safe_name}-{original_name}"
+            for original_name in self.additional_files.keys()
+        }
+
+
+class ExtensionRegistry:
+    """
+    Singleton registry for managing figpack extensions
+    """
+
+    _instance: Optional["ExtensionRegistry"] = None
+
+    def __init__(self):
+        self._extensions: Dict[str, FigpackExtension] = {}
+
+    @classmethod
+    def get_instance(cls) -> "ExtensionRegistry":
+        """Get the singleton instance of the extension registry"""
+        if cls._instance is None:
+            cls._instance = cls()
+        return cls._instance
+
+    @classmethod
+    def register(cls, extension: FigpackExtension) -> None:
+        """
+        Register an extension with the global registry
+
+        Args:
+            extension: The extension to register
+        """
+        registry = cls.get_instance()
+        registry._register_extension(extension)
+
+    def _register_extension(self, extension: FigpackExtension) -> None:
+        """
+        Internal method to register an extension
+
+        Args:
+            extension: The extension to register
+        """
+        if extension.name in self._extensions:
+            existing = self._extensions[extension.name]
+            if existing.version != extension.version:
+                print(
+                    f"Warning: Replacing extension '{extension.name}' "
+                    f"version {existing.version} with version {extension.version}"
+                )
+
+        self._extensions[extension.name] = extension
+
+    def get_extension(self, name: str) -> Optional[FigpackExtension]:
+        """
+        Get an extension by name
+
+        Args:
+            name: Name of the extension to retrieve
+
+        Returns:
+            The extension if found, None otherwise
+        """
+        return self._extensions.get(name)
+
+    def get_all_extensions(self) -> Dict[str, FigpackExtension]:
+        """
+        Get all registered extensions
+
+        Returns:
+            Dictionary mapping extension names to extension objects
+        """
+        return self._extensions.copy()
+
+    def clear(self) -> None:
+        """Clear all registered extensions (mainly for testing)"""
+        self._extensions.clear()

{figpack-0.2.7 → figpack-0.2.9}/figpack/core/figpack_view.py

@@ -121,7 +121,7 @@ class FigpackView:
             )
             print("** Development mode **")
             print(
-                f"For development, run figpack-figure in dev mode and use http://localhost:5173?data=http://localhost:{port}/{_local_figure_name}/data.zarr"
+                f"For development, run figpack-figure in dev mode and use http://localhost:5173?figure=http://localhost:{port}/{_local_figure_name}/"
             )
             print("")