scitex 2.8.1__py3-none-any.whl → 2.10.0__py3-none-any.whl

scitex/fts/_bundle/_saver.py

@@ -0,0 +1,269 @@
+#!/usr/bin/env python3
+# Timestamp: 2025-12-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/fts/_bundle/_saver.py
+
+"""FTS Bundle saving utilities.
+
+Bundle structure (IDENTICAL for all kinds):
+    bundle.zip/
+    ├── canonical/              # Source of truth (editable, human-readable)
+    │   ├── spec.json           # {kind, children, layout, payload_schema, ...}
+    │   ├── encoding.json       # Data-to-visual mappings
+    │   ├── theme.json          # Visual aesthetics
+    │   ├── data_info.json      # Column metadata
+    │   └── runtime.json        # Runtime configuration
+    ├── payload/                # ALWAYS exists (empty for kind=figure)
+    │   ├── data.csv            # Source data (for kind=plot)
+    │   └── stats.json          # Statistics (for kind=stats)
+    ├── artifacts/              # Derived (can be deleted and regenerated)
+    │   ├── cache/
+    │   │   ├── geometry_px.json
+    │   │   ├── hitmap.png
+    │   │   ├── hitmap.svg
+    │   │   └── render_manifest.json
+    │   └── exports/
+    │       ├── figure.png
+    │       ├── figure.svg
+    │       └── figure.pdf
+    └── children/               # ALWAYS exists (empty for kind=plot)
+        └── {child_id}.zip
+"""
+
+import hashlib
+import io
+import json
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Dict, Optional
+
+from ._storage import Storage, get_storage
+
+if TYPE_CHECKING:
+    from ._dataclasses import DataInfo, Node
+    from .._fig import Encoding, Theme
+    from .._stats import Stats
+
+
+def save_bundle_components(
+    path: Path,
+    node: Optional["Node"] = None,
+    encoding: Optional["Encoding"] = None,
+    theme: Optional["Theme"] = None,
+    stats: Optional["Stats"] = None,
+    data_info: Optional["DataInfo"] = None,
+    render: bool = True,
+) -> None:
+    """Save all bundle components to storage.
+
+    Uses the new canonical/artifacts/payload/children structure.
+
+    Args:
+        path: Bundle path (directory or ZIP)
+        node: Node metadata (saved to canonical/spec.json)
+        encoding: Encoding specification (saved to canonical/encoding.json)
+        theme: Theme specification (saved to canonical/theme.json)
+        stats: Statistics (saved to payload/stats.json for kind=stats)
+        data_info: Data info metadata (saved to canonical/data_info.json)
+        render: Whether to generate exports/cache (default True)
+    """
+    storage = get_storage(path)
+
+    # Collect all files to write
+    files = {}
+
+    # === ALWAYS create all directories and placeholder files ===
+    # Use .keep files as directory markers for ZIP compatibility
+    files["canonical/.keep"] = ""
+    files["payload/.keep"] = ""
+    files["payload/data.csv"] = ""  # Empty CSV for consistency
+    files["artifacts/.keep"] = ""
+    files["artifacts/exports/.keep"] = ""
+    files["artifacts/cache/.keep"] = ""
+    files["children/.keep"] = ""
+
+    # canonical/ - Source of truth
+    if node:
+        files["canonical/spec.json"] = json.dumps(node.to_dict(), indent=2)
+
+    if encoding:
+        files["canonical/encoding.json"] = encoding.to_json()
+
+    if theme:
+        files["canonical/theme.json"] = theme.to_json()
+
+    if data_info:
+        files["canonical/data_info.json"] = data_info.to_json()
+
+    # payload/ - Data files (for leaf kinds)
+    if stats and stats.analyses:
+        files["payload/stats.json"] = stats.to_json()
+
+    # Write files, preserving any existing children/ files
+    # For ZIP, we need to merge with existing content
+    if hasattr(storage, 'write_all_preserve'):
+        storage.write_all_preserve(files)
+    else:
+        # Fallback: write each file individually (preserves existing)
+        for name, data in files.items():
+            if isinstance(data, str):
+                data = data.encode("utf-8")
+            storage.write(name, data)
+
+
+def save_render_outputs(
+    storage: Storage,
+    figure: Any,  # matplotlib.figure.Figure
+    geometry: Dict,
+    source_hash: str,
+    theme_hash: str,
+    renderer_version: str = "1.0.0",
+    dpi: int = 300,
+) -> None:
+    """Save artifacts/exports/ and artifacts/cache/.
+
+    Same structure for both kind=plot and kind=figure.
+
+    Args:
+        storage: Bundle storage
+        figure: Matplotlib figure to save
+        geometry: Geometry data (hit areas, element positions)
+        source_hash: Hash of canonical/ for cache invalidation
+        theme_hash: Hash of effective theme (after parent overrides)
+        renderer_version: Renderer version for cache invalidation
+        dpi: Output DPI for raster formats
+    """
+    # Save artifacts/exports/
+    for fmt in ["png", "svg", "pdf"]:
+        buf = io.BytesIO()
+        figure.savefig(buf, format=fmt, dpi=dpi, bbox_inches="tight")
+        storage.write(f"artifacts/exports/figure.{fmt}", buf.getvalue())
+
+    # Save artifacts/cache/geometry_px.json
+    # Add coordinate space declaration
+    geometry_with_space = {
+        "space": "figure_px",  # Coordinate space declaration
+        **geometry,
+    }
+    storage.write(
+        "artifacts/cache/geometry_px.json",
+        json.dumps(geometry_with_space, indent=2).encode(),
+    )
+
+    # Generate and save hitmaps
+    hitmap_png, hitmap_svg = generate_hitmap(figure, geometry, dpi)
+    if hitmap_png:
+        storage.write("artifacts/cache/hitmap.png", hitmap_png)
+    if hitmap_svg:
+        storage.write("artifacts/cache/hitmap.svg", hitmap_svg)
+
+    # Save render manifest (includes cache invalidation keys)
+    manifest = {
+        "dpi": dpi,
+        "formats": ["png", "svg", "pdf"],
+        # Cache invalidation keys
+        "canonical_hash": source_hash,
+        "effective_theme_hash": theme_hash,
+        "renderer_version": renderer_version,
+    }
+    storage.write(
+        "artifacts/cache/render_manifest.json",
+        json.dumps(manifest, indent=2).encode(),
+    )
+
+
+def generate_hitmap(
+    figure: Any,  # matplotlib.figure.Figure
+    geometry: Dict,
+    dpi: int = 300,
+) -> tuple:
+    """Generate hitmap.png and hitmap.svg for click detection.
+
+    Returns:
+        (hitmap_png_bytes, hitmap_svg_bytes) - bytes or None if failed
+    """
+    # Basic implementation - generate colored regions for hit testing
+    # This is a simplified version; full implementation would color-code elements
+    try:
+        import io
+
+        import matplotlib.pyplot as plt
+        import numpy as np
+
+        # Create hitmap figure with same dimensions
+        fig_size = figure.get_size_inches()
+        hitmap_fig, ax = plt.subplots(figsize=fig_size, dpi=dpi)
+        ax.set_xlim(0, 1)
+        ax.set_ylim(0, 1)
+        ax.axis("off")
+
+        # Draw colored regions for each element in geometry
+        elements = geometry.get("elements", [])
+        for i, elem in enumerate(elements):
+            if "bbox" in elem:
+                bbox = elem["bbox"]
+                color = plt.cm.tab20(i % 20)
+                ax.add_patch(
+                    plt.Rectangle(
+                        (bbox.get("x", 0), bbox.get("y", 0)),
+                        bbox.get("width", 0.1),
+                        bbox.get("height", 0.1),
+                        facecolor=color,
+                        edgecolor="none",
+                    )
+                )
+
+        # Save as PNG
+        png_buf = io.BytesIO()
+        hitmap_fig.savefig(png_buf, format="png", dpi=dpi, bbox_inches="tight")
+        png_bytes = png_buf.getvalue()
+
+        # Save as SVG
+        svg_buf = io.BytesIO()
+        hitmap_fig.savefig(svg_buf, format="svg", bbox_inches="tight")
+        svg_bytes = svg_buf.getvalue()
+
+        plt.close(hitmap_fig)
+        return png_bytes, svg_bytes
+
+    except Exception as e:
+        # If hitmap generation fails, return None (non-critical)
+        return None, None
+
+
+def compute_canonical_hash(storage: Storage) -> str:
+    """Compute hash of canonical/ directory for cache invalidation."""
+    hasher = hashlib.sha256()
+
+    canonical_files = [
+        "canonical/spec.json",
+        "canonical/encoding.json",
+        "canonical/theme.json",
+        "canonical/data_info.json",
+    ]
+
+    for filepath in canonical_files:
+        if storage.exists(filepath):
+            data = storage.read(filepath)
+            hasher.update(data)
+
+    return hasher.hexdigest()[:16]
+
+
+def compute_theme_hash(theme: Optional["Theme"]) -> str:
+    """Compute hash of theme for cache invalidation."""
+    if theme is None:
+        return "default"
+
+    hasher = hashlib.sha256()
+    hasher.update(theme.to_json().encode())
+    return hasher.hexdigest()[:16]
+
+
+__all__ = [
+    "save_bundle_components",
+    "save_render_outputs",
+    "generate_hitmap",
+    "compute_canonical_hash",
+    "compute_theme_hash",
+]
+
+# EOF

scitex/fts/_bundle/_storage.py

@@ -0,0 +1,200 @@
+#!/usr/bin/env python3
+# Timestamp: 2025-12-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/fsb/_bundle/_storage.py
+
+"""
+Storage Abstraction for FTS Bundles.
+
+Provides a unified interface for reading/writing bundle contents
+regardless of whether the bundle is a ZIP file or directory.
+
+Usage:
+    storage = get_storage(Path("bundle.zip"))  # or Path("bundle/")
+    data = storage.read("node.json")
+    storage.write("encoding.json", json_bytes)
+"""
+
+import json
+import zipfile
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import List, Optional, Union
+
+
+class Storage(ABC):
+    """Abstract storage interface for FTS bundles."""
+
+    def __init__(self, path: Path):
+        self._path = path
+
+    @property
+    def path(self) -> Path:
+        """Storage path."""
+        return self._path
+
+    @abstractmethod
+    def exists(self, name: str) -> bool:
+        """Check if file exists in storage."""
+        pass
+
+    @abstractmethod
+    def read(self, name: str) -> bytes:
+        """Read file contents as bytes."""
+        pass
+
+    @abstractmethod
+    def write(self, name: str, data: bytes) -> None:
+        """Write data to file."""
+        pass
+
+    @abstractmethod
+    def list(self) -> List[str]:
+        """List all files in storage."""
+        pass
+
+    def read_json(self, name: str) -> Optional[dict]:
+        """Read and parse JSON file."""
+        if not self.exists(name):
+            return None
+        data = self.read(name)
+        return json.loads(data.decode("utf-8"))
+
+    def write_json(self, name: str, obj: dict, indent: int = 2) -> None:
+        """Write object as JSON file."""
+        data = json.dumps(obj, indent=indent).encode("utf-8")
+        self.write(name, data)
+
+
+class ZipStorage(Storage):
+    """Storage implementation for ZIP files.
+
+    ZIP files are structured with a top-level directory named after the bundle.
+    For example, my_figure.zip contains:
+        my_figure/
+            node.json
+            encoding.json
+            theme.json
+    This ensures `unzip my_figure.zip` creates a my_figure/ directory.
+    """
+
+    @property
+    def _prefix(self) -> str:
+        """Top-level directory name inside the ZIP (bundle stem)."""
+        return self._path.stem + "/"
+
+    def _prefixed(self, name: str) -> str:
+        """Add prefix to file path."""
+        return self._prefix + name
+
+    def _unprefixed(self, name: str) -> str:
+        """Remove prefix from file path."""
+        if name.startswith(self._prefix):
+            return name[len(self._prefix) :]
+        return name
+
+    def exists(self, name: str) -> bool:
+        if not self._path.exists():
+            return False
+        with zipfile.ZipFile(self._path, "r") as zf:
+            # Check both prefixed and unprefixed for backwards compatibility
+            return self._prefixed(name) in zf.namelist() or name in zf.namelist()
+
+    def read(self, name: str) -> bytes:
+        with zipfile.ZipFile(self._path, "r") as zf:
+            # Try prefixed first, fall back to unprefixed for backwards compatibility
+            prefixed = self._prefixed(name)
+            if prefixed in zf.namelist():
+                return zf.read(prefixed)
+            return zf.read(name)
+
+    def write(self, name: str, data: bytes) -> None:
+        # ZIP files need special handling - read existing, add/update, rewrite
+        existing = {}
+        prefixed_name = self._prefixed(name)
+        if self._path.exists():
+            with zipfile.ZipFile(self._path, "r") as zf:
+                for item in zf.namelist():
+                    if item != prefixed_name:
+                        existing[item] = zf.read(item)
+
+        with zipfile.ZipFile(self._path, "w", zipfile.ZIP_DEFLATED) as zf:
+            for item_name, item_data in existing.items():
+                zf.writestr(item_name, item_data)
+            zf.writestr(prefixed_name, data)
+
+    def list(self) -> List[str]:
+        if not self._path.exists():
+            return []
+        with zipfile.ZipFile(self._path, "r") as zf:
+            # Return unprefixed names for API consistency
+            return [self._unprefixed(n) for n in zf.namelist() if not n.endswith("/")]
+
+    def write_all(self, files: dict) -> None:
+        """Write multiple files at once (more efficient for ZIP).
+
+        Files are stored under a top-level directory matching the bundle name.
+        """
+        with zipfile.ZipFile(self._path, "w", zipfile.ZIP_DEFLATED) as zf:
+            for name, data in files.items():
+                if isinstance(data, str):
+                    data = data.encode("utf-8")
+                zf.writestr(self._prefixed(name), data)
+
+
+class DirStorage(Storage):
+    """Storage implementation for directories."""
+
+    def exists(self, name: str) -> bool:
+        return (self._path / name).exists()
+
+    def read(self, name: str) -> bytes:
+        with open(self._path / name, "rb") as f:
+            return f.read()
+
+    def write(self, name: str, data: bytes) -> None:
+        file_path = self._path / name
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(file_path, "wb") as f:
+            f.write(data)
+
+    def list(self) -> List[str]:
+        if not self._path.exists():
+            return []
+        result = []
+        for item in self._path.rglob("*"):
+            if item.is_file():
+                result.append(str(item.relative_to(self._path)))
+        return result
+
+    def write_all(self, files: dict) -> None:
+        """Write multiple files."""
+        self._path.mkdir(parents=True, exist_ok=True)
+        for name, data in files.items():
+            if isinstance(data, str):
+                data = data.encode("utf-8")
+            self.write(name, data)
+
+
+def get_storage(path: Union[str, Path]) -> Storage:
+    """Get appropriate storage for path.
+
+    Args:
+        path: Bundle path (directory or .zip file)
+
+    Returns:
+        Storage instance (ZipStorage or DirStorage)
+    """
+    path = Path(path)
+    if path.suffix == ".zip":
+        return ZipStorage(path)
+    return DirStorage(path)
+
+
+__all__ = [
+    "Storage",
+    "ZipStorage",
+    "DirStorage",
+    "get_storage",
+]
+
+# EOF

scitex/fts/_bundle/_utils/__init__.py

@@ -0,0 +1,55 @@
+#!/usr/bin/env python3
+# Timestamp: 2025-12-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/fsb/_bundle/_utils/__init__.py
+
+"""FTS Bundle utilities - types, constants, errors, and helpers."""
+
+# Constants
+from ._const import EXTENSIONS, SCHEMA_NAME, SCHEMA_VERSION, ZIP_EXTENSION
+
+# Types
+from ._types import (
+    TYPE_DEFAULTS,
+    BundleType,
+    NodeType,
+    get_default_constraints,
+)
+
+# Errors
+from ._errors import (
+    BundleError,
+    BundleNotFoundError,
+    BundleValidationError,
+    CircularReferenceError,
+    ConstraintError,
+    DepthLimitError,
+    NestedBundleNotFoundError,
+)
+
+# Generation
+from ._generate import generate_bundle_id
+
+__all__ = [
+    # Constants
+    "ZIP_EXTENSION",
+    "EXTENSIONS",
+    "SCHEMA_NAME",
+    "SCHEMA_VERSION",
+    # Types
+    "NodeType",
+    "BundleType",
+    "TYPE_DEFAULTS",
+    "get_default_constraints",
+    # Errors
+    "BundleError",
+    "BundleValidationError",
+    "BundleNotFoundError",
+    "NestedBundleNotFoundError",
+    "CircularReferenceError",
+    "DepthLimitError",
+    "ConstraintError",
+    # Generation
+    "generate_bundle_id",
+]
+
+# EOF

scitex/fts/_bundle/_utils/_const.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+# Timestamp: 2025-12-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/fsb/_bundle/_utils/_const.py
+
+"""FTS Bundle constants."""
+
+from typing import Tuple
+
+# Bundle extension (ZIP for portability, or directory)
+ZIP_EXTENSION: str = ".zip"
+
+# Supported formats: .zip files or directories (no extension)
+EXTENSIONS: Tuple[str, ...] = (".zip",)
+
+# Schema constants
+SCHEMA_NAME = "scitex.fts"
+SCHEMA_VERSION = "1.0.0"
+
+__all__ = [
+    "ZIP_EXTENSION",
+    "EXTENSIONS",
+    "SCHEMA_NAME",
+    "SCHEMA_VERSION",
+]
+
+# EOF

scitex/fts/_bundle/_utils/_errors.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+# Timestamp: 2025-12-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/fsb/_bundle/_utils/_errors.py
+
+"""FTS Bundle error classes."""
+
+
+class BundleError(Exception):
+    """Base exception for bundle operations."""
+
+    pass
+
+
+class BundleValidationError(BundleError, ValueError):
+    """Error raised when bundle validation fails."""
+
+    pass
+
+
+class BundleNotFoundError(BundleError, FileNotFoundError):
+    """Error raised when a bundle is not found."""
+
+    pass
+
+
+class NestedBundleNotFoundError(BundleNotFoundError):
+    """Error raised when a nested bundle or file within it is not found."""
+
+    pass
+
+
+class CircularReferenceError(BundleValidationError):
+    """Error raised when circular reference is detected in bundle hierarchy.
+
+    This occurs when a bundle references itself directly or indirectly
+    through its children, detected via bundle_id tracking.
+    """
+
+    pass
+
+
+class DepthLimitError(BundleValidationError):
+    """Error raised when bundle nesting exceeds max_depth constraint.
+
+    The max_depth is defined per bundle type in TYPE_DEFAULTS.
+    Default is 3 for figures, 1 for leaf types.
+    """
+
+    pass
+
+
+class ConstraintError(BundleValidationError):
+    """Error raised when bundle violates its type constraints.
+
+    Examples:
+    - Leaf type (plot, stats) has children
+    - Unknown type specified
+    """
+
+    pass
+
+
+__all__ = [
+    "BundleError",
+    "BundleValidationError",
+    "BundleNotFoundError",
+    "NestedBundleNotFoundError",
+    "CircularReferenceError",
+    "DepthLimitError",
+    "ConstraintError",
+]
+
+# EOF

scitex/fts/_bundle/_utils/_generate.py

@@ -0,0 +1,21 @@
+#!/usr/bin/env python3
+# Timestamp: 2025-12-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/fsb/_bundle/_utils/_generate.py
+
+"""FTS Bundle ID generation utilities."""
+
+import uuid
+
+
+def generate_bundle_id() -> str:
+    """Generate a unique bundle ID (UUID4).
+
+    Returns:
+        A new UUID4 string.
+    """
+    return str(uuid.uuid4())
+
+
+__all__ = ["generate_bundle_id"]
+
+# EOF