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

scitex/io/_bundle.py

@@ -0,0 +1,493 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-12-13 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/io/_bundle.py
+
+"""
+SciTeX Bundle I/O - Shared utilities for .figz, .pltz, and .statsz formats.
+
+This module provides common bundle operations. Domain-specific logic is in:
+    - scitex.plt.io._bundle  (pltz: hitmap, CSV, overview)
+    - scitex.fig.io._bundle  (figz: panel composition, nested pltz)
+    - scitex.stats.io._bundle (statsz: comparison metadata)
+
+Bundle formats:
+    .figz  - Publication Figure Bundle (panels + layout)
+    .pltz  - Reproducible Plot Bundle (data + spec + exports)
+    .statsz - Statistical Results Bundle (stats + metadata)
+
+Each bundle can be:
+    - Directory form: Figure1.figz.d/
+    - ZIP archive form: Figure1.figz
+"""
+
+import json
+import shutil
+import zipfile
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union
+
+__all__ = [
+    "is_bundle",
+    "load_bundle",
+    "save_bundle",
+    "pack_bundle",
+    "unpack_bundle",
+    "validate_bundle",
+    "validate_spec",
+    "BundleType",
+    "BundleValidationError",
+    "BUNDLE_EXTENSIONS",
+    "get_bundle_type",
+    "dir_to_zip_path",
+    "zip_to_dir_path",
+]
+
+# Bundle extensions
+BUNDLE_EXTENSIONS = (".figz", ".pltz", ".statsz")
+
+
+class BundleValidationError(ValueError):
+    """Error raised when bundle validation fails."""
+    pass
+
+
+class BundleType:
+    """Bundle type constants."""
+    FIGZ = "figz"
+    PLTZ = "pltz"
+    STATSZ = "statsz"
+
+
+def get_bundle_type(path: Union[str, Path]) -> Optional[str]:
+    """Get bundle type from path.
+
+    Args:
+        path: Path to bundle (directory or ZIP).
+
+    Returns:
+        Bundle type string or None if not a bundle.
+    """
+    p = Path(path)
+
+    # Directory bundle: ends with .figz.d, .pltz.d, .statsz.d
+    if p.is_dir() and p.suffix == ".d":
+        stem = p.stem  # e.g., "Figure1.figz"
+        for ext in BUNDLE_EXTENSIONS:
+            if stem.endswith(ext):
+                return ext[1:]  # Remove leading dot
+        return None
+
+    # ZIP bundle: ends with .figz, .pltz, .statsz
+    if p.suffix in BUNDLE_EXTENSIONS:
+        return p.suffix[1:]  # Remove leading dot
+
+    return None
+
+
+def is_bundle(path: Union[str, Path]) -> bool:
+    """Check if path is a SciTeX bundle (directory or ZIP).
+
+    Args:
+        path: Path to check.
+
+    Returns:
+        True if path is a bundle.
+    """
+    return get_bundle_type(path) is not None
+
+
+def dir_to_zip_path(dir_path: Path) -> Path:
+    """Convert directory path to ZIP path.
+
+    Example: Figure1.figz.d/ -> Figure1.figz
+    """
+    if dir_path.suffix == ".d":
+        return dir_path.with_suffix("")
+    return dir_path
+
+
+def zip_to_dir_path(zip_path: Path) -> Path:
+    """Convert ZIP path to directory path.
+
+    Example: Figure1.figz -> Figure1.figz.d/
+    """
+    return Path(str(zip_path) + ".d")
+
+
+def pack_bundle(
+    dir_path: Union[str, Path], output_path: Optional[Union[str, Path]] = None
+) -> Path:
+    """Pack a bundle directory into a ZIP archive.
+
+    The ZIP archive includes the .d directory as a top-level folder so that
+    standard unzip extracts to: fname.pltz.d/fname.csv, fname.pltz.d/fname.json, etc.
+
+    Args:
+        dir_path: Path to bundle directory (e.g., Figure1.figz.d/).
+        output_path: Output ZIP path. Auto-generated if None.
+
+    Returns:
+        Path to created ZIP archive.
+    """
+    dir_path = Path(dir_path)
+
+    if not dir_path.is_dir():
+        raise ValueError(f"Not a directory: {dir_path}")
+
+    if output_path is None:
+        output_path = dir_to_zip_path(dir_path)
+    else:
+        output_path = Path(output_path)
+
+    # Get the directory name to use as top-level folder in ZIP
+    # e.g., "stx_line.pltz.d" for path "/path/to/stx_line.pltz.d"
+    dir_name = dir_path.name
+
+    # Create ZIP archive with directory structure preserved
+    with zipfile.ZipFile(output_path, "w", zipfile.ZIP_DEFLATED) as zf:
+        for file_path in dir_path.rglob("*"):
+            if file_path.is_file():
+                # Include directory name in archive path
+                # e.g., "stx_line.pltz.d/stx_line.csv"
+                rel_path = file_path.relative_to(dir_path)
+                arcname = Path(dir_name) / rel_path
+                zf.write(file_path, arcname)
+
+    return output_path
+
+
+def unpack_bundle(
+    zip_path: Union[str, Path], output_path: Optional[Union[str, Path]] = None
+) -> Path:
+    """Unpack a bundle ZIP archive into a directory.
+
+    The ZIP archive contains a top-level .d directory, so extraction goes to
+    the parent directory. E.g., stx_line.pltz extracts to create stx_line.pltz.d/
+
+    Args:
+        zip_path: Path to bundle ZIP (e.g., Figure1.figz).
+        output_path: Output directory path. Auto-generated if None.
+
+    Returns:
+        Path to created directory.
+    """
+    zip_path = Path(zip_path)
+
+    if not zip_path.is_file():
+        raise ValueError(f"Not a file: {zip_path}")
+
+    # Determine extraction target
+    if output_path is None:
+        # Extract to same directory as ZIP file (ZIP contains .d folder structure)
+        extract_to = zip_path.parent
+        expected_dir = zip_to_dir_path(zip_path)
+    else:
+        output_path = Path(output_path)
+        extract_to = output_path.parent
+        expected_dir = output_path
+
+    # Extract ZIP archive (contains .d directory structure)
+    with zipfile.ZipFile(zip_path, "r") as zf:
+        zf.extractall(extract_to)
+
+    return expected_dir
+
+
+def validate_spec(
+    spec: Dict[str, Any], bundle_type: str, strict: bool = False
+) -> List[str]:
+    """Validate a bundle specification against its schema.
+
+    Args:
+        spec: The specification dictionary to validate.
+        bundle_type: Bundle type ('figz', 'pltz', 'statsz').
+        strict: If True, raise BundleValidationError on failure.
+
+    Returns:
+        List of validation warning/error messages (empty if valid).
+
+    Raises:
+        BundleValidationError: If strict=True and validation fails.
+    """
+    errors = []
+
+    # Basic schema validation
+    if "schema" not in spec:
+        errors.append("Missing required field: schema")
+    elif not isinstance(spec["schema"], dict):
+        errors.append("'schema' field must be a dictionary")
+    else:
+        schema = spec["schema"]
+        if "name" not in schema:
+            errors.append("schema.name is required")
+        if "version" not in schema:
+            errors.append("schema.version is required")
+
+    # Delegate to domain-specific validators
+    if bundle_type == BundleType.FIGZ:
+        from scitex.fig.io._bundle import validate_figz_spec
+        errors.extend(validate_figz_spec(spec))
+    elif bundle_type == BundleType.PLTZ:
+        from scitex.plt.io._bundle import validate_pltz_spec
+        errors.extend(validate_pltz_spec(spec))
+    elif bundle_type == BundleType.STATSZ:
+        from scitex.stats.io._bundle import validate_statsz_spec
+        errors.extend(validate_statsz_spec(spec))
+    else:
+        errors.append(f"Unknown bundle type: {bundle_type}")
+
+    if strict and errors:
+        raise BundleValidationError("; ".join(errors))
+
+    return errors
+
+
+def validate_bundle(
+    path: Union[str, Path], strict: bool = False
+) -> Dict[str, Any]:
+    """Validate a bundle and return validation results.
+
+    Args:
+        path: Path to bundle (directory or ZIP).
+        strict: If True, raise BundleValidationError on failure.
+
+    Returns:
+        Dictionary with:
+        - 'valid': bool
+        - 'errors': list of error messages
+        - 'bundle_type': detected bundle type
+        - 'spec': parsed spec (if available)
+
+    Raises:
+        BundleValidationError: If strict=True and validation fails.
+    """
+    result = {
+        "valid": True,
+        "errors": [],
+        "bundle_type": None,
+        "spec": None,
+    }
+
+    p = Path(path)
+
+    # Check bundle type
+    bundle_type = get_bundle_type(p)
+    if bundle_type is None:
+        result["valid"] = False
+        result["errors"].append(f"Not a valid bundle path: {path}")
+        if strict:
+            raise BundleValidationError(result["errors"][0])
+        return result
+
+    result["bundle_type"] = bundle_type
+
+    # Try to load and validate
+    try:
+        bundle = load_bundle(path)
+        spec = bundle.get("spec")
+        result["spec"] = spec
+
+        if spec is not None:
+            errors = validate_spec(spec, bundle_type, strict=False)
+            if errors:
+                result["valid"] = False
+                result["errors"].extend(errors)
+        else:
+            result["valid"] = False
+            result["errors"].append("Bundle has no spec")
+
+    except Exception as e:
+        result["valid"] = False
+        result["errors"].append(f"Failed to load bundle: {e}")
+
+    if strict and not result["valid"]:
+        raise BundleValidationError("; ".join(result["errors"]))
+
+    return result
+
+
+def load_bundle(path: Union[str, Path], in_memory: bool = True) -> Dict[str, Any]:
+    """Load bundle from directory or ZIP transparently.
+
+    Args:
+        path: Path to bundle (directory or ZIP).
+        in_memory: If True, load ZIP contents in-memory without extracting.
+                   If False, extract to temp directory (legacy behavior).
+
+    Returns:
+        Bundle data as dictionary with:
+        - 'type': Bundle type ('figz', 'pltz', 'statsz')
+        - 'spec': Parsed JSON specification
+        - 'path': Original path
+        - 'is_zip': Whether loaded from ZIP
+        - Additional fields based on bundle type
+    """
+    p = Path(path)
+    bundle_type = get_bundle_type(p)
+
+    if bundle_type is None:
+        raise ValueError(f"Not a valid bundle: {path}")
+
+    result = {
+        "type": bundle_type,
+        "path": p,
+        "is_zip": False,
+    }
+
+    # Handle ZIP vs directory
+    if p.is_file() and p.suffix in BUNDLE_EXTENSIONS:
+        result["is_zip"] = True
+
+        if in_memory:
+            # In-memory loading using ZipBundle
+            from ._zip_bundle import ZipBundle
+            with ZipBundle(p, mode="r") as zb:
+                result["_zip_bundle"] = zb
+                # Load common files in-memory
+                try:
+                    result["spec"] = zb.read_json("spec.json")
+                except FileNotFoundError:
+                    result["spec"] = None
+                try:
+                    result["style"] = zb.read_json("style.json")
+                except FileNotFoundError:
+                    result["style"] = None
+                try:
+                    result["data"] = zb.read_csv("data.csv")
+                except FileNotFoundError:
+                    result["data"] = None
+
+                # Get file list
+                result["files"] = zb.namelist()
+
+            return result
+        else:
+            # Legacy: extract to temp and load
+            import tempfile
+            temp_dir = Path(tempfile.mkdtemp())
+            with zipfile.ZipFile(p, "r") as zf:
+                zf.extractall(temp_dir)
+            bundle_dir = temp_dir
+    else:
+        bundle_dir = p
+
+    # Delegate to domain-specific loaders (for directory bundles or legacy mode)
+    if bundle_type == BundleType.FIGZ:
+        from scitex.fig.io._bundle import load_figz_bundle
+        result.update(load_figz_bundle(bundle_dir))
+    elif bundle_type == BundleType.PLTZ:
+        from scitex.plt.io import load_layered_pltz_bundle
+        result.update(load_layered_pltz_bundle(bundle_dir))
+    elif bundle_type == BundleType.STATSZ:
+        from scitex.stats.io._bundle import load_statsz_bundle
+        result.update(load_statsz_bundle(bundle_dir))
+
+    return result
+
+
+def save_bundle(
+    data: Dict[str, Any],
+    path: Union[str, Path],
+    bundle_type: Optional[str] = None,
+    as_zip: bool = False,
+    atomic: bool = True,
+) -> Path:
+    """Save data as a bundle.
+
+    Args:
+        data: Bundle data dictionary.
+        path: Output path (with or without .d suffix).
+        bundle_type: Bundle type ('figz', 'pltz', 'statsz'). Auto-detected if None.
+        as_zip: If True, save as ZIP archive.
+        atomic: If True, use atomic write (temp file + rename) for ZIP.
+
+    Returns:
+        Path to saved bundle.
+    """
+    p = Path(path)
+
+    # Determine bundle type
+    if bundle_type is None:
+        bundle_type = get_bundle_type(p)
+        if bundle_type is None:
+            raise ValueError(f"Cannot determine bundle type from path: {path}")
+
+    # Determine if saving as directory or ZIP
+    if as_zip or (p.suffix in BUNDLE_EXTENSIONS and not str(p).endswith(".d")):
+        save_as_zip = True
+        if p.suffix == ".d":
+            zip_path = dir_to_zip_path(p)
+        else:
+            zip_path = p
+        dir_path = zip_to_dir_path(zip_path)
+    else:
+        save_as_zip = False
+        if not str(p).endswith(".d"):
+            dir_path = Path(str(p) + ".d")
+        else:
+            dir_path = p
+
+    # For direct ZIP saving with atomic writes, use ZipBundle
+    # Note: figz bundles need special handling for nested pltz panels,
+    # so they go through the directory-based save_figz_bundle path
+    if save_as_zip and atomic and bundle_type != BundleType.FIGZ:
+        from ._zip_bundle import ZipBundle
+
+        with ZipBundle(zip_path, mode="w") as zb:
+            # Write spec
+            if "spec" in data:
+                zb.write_json("spec.json", data["spec"])
+
+            # Write style
+            if "style" in data:
+                zb.write_json("style.json", data["style"])
+
+            # Write CSV data
+            if "data" in data and data["data"] is not None:
+                import pandas as pd
+                if isinstance(data["data"], pd.DataFrame):
+                    zb.write_csv("data.csv", data["data"])
+
+            # Write exports (PNG, SVG, etc.)
+            for key in ["png", "svg", "pdf"]:
+                if key in data and data[key] is not None:
+                    export_data = data[key]
+                    if isinstance(export_data, bytes):
+                        zb.write_bytes(f"exports/figure.{key}", export_data)
+
+        return zip_path
+
+    # Create directory for non-ZIP or non-atomic saves
+    dir_path.mkdir(parents=True, exist_ok=True)
+
+    # Delegate to domain-specific savers
+    if bundle_type == BundleType.FIGZ:
+        from scitex.fig.io._bundle import save_figz_bundle
+        save_figz_bundle(data, dir_path)
+    elif bundle_type == BundleType.PLTZ:
+        # Note: This path is only reached when calling save_bundle() directly
+        # The main stx.io.save() flow uses _save_pltz_bundle() which handles layered format
+        from scitex.plt.io._bundle import save_pltz_bundle
+        save_pltz_bundle(data, dir_path)
+    elif bundle_type == BundleType.STATSZ:
+        from scitex.stats.io._bundle import save_statsz_bundle
+        save_statsz_bundle(data, dir_path)
+    else:
+        raise ValueError(f"Unknown bundle type: {bundle_type}")
+
+    # Pack to ZIP if requested (non-atomic path)
+    if save_as_zip:
+        pack_bundle(dir_path, zip_path)
+        shutil.rmtree(dir_path)  # Remove temp directory
+        return zip_path
+
+    return dir_path
+
+
+# Backward compatibility aliases
+_get_bundle_type = get_bundle_type
+_dir_to_zip_path = dir_to_zip_path
+_zip_to_dir_path = zip_to_dir_path
+
+# EOF

scitex/io/_flush.py

@@ -5,7 +5,10 @@
 
 import os
 import sys
-import warnings
+
+from scitex import logging
+
+logger = logging.getLogger(__name__)
 
 
 def flush(sys=sys):
@@ -14,7 +17,7 @@ def flush(sys=sys):
     This ensures all pending write operations are completed.
     """
     if sys is None:
-        warnings.warn("flush needs sys. Skipping.")
+        logger.warning("flush needs sys. Skipping.")
     else:
         sys.stdout.flush()
         sys.stderr.flush()

scitex/io/_load.py

@@ -48,6 +48,98 @@ from ._load_modules._zarr import _load_zarr
 from ._load_modules._canvas import _load_canvas
 
 
+def _load_bundle(lpath, verbose=False, **kwargs):
+    """Load a .pltz, .figz, or .statsz bundle.
+
+    Parameters
+    ----------
+    lpath : str or Path
+        Path to the bundle (directory or ZIP).
+    verbose : bool
+        If True, print verbose output.
+    **kwargs
+        Additional arguments.
+
+    Returns
+    -------
+    For .pltz bundles:
+        tuple: (fig, ax, data) where fig is reconstructed figure,
+               ax is the axes, data is DataFrame or None.
+    For .figz bundles:
+        dict: Figure data with 'spec' and 'panels'.
+    For .statsz bundles:
+        dict: Stats data with 'spec' and 'comparisons'.
+    """
+    from ._bundle import load_bundle, BundleType
+
+    bundle = load_bundle(lpath)
+    bundle_type = bundle.get('type')
+
+    if bundle_type == BundleType.PLTZ:
+        # Return (fig, ax, data) tuple for .pltz bundles
+        # Note: We return the spec and data, not a reconstructed figure
+        # as matplotlib figures cannot be perfectly serialized/deserialized
+        import matplotlib.pyplot as plt
+        from pathlib import Path
+
+        p = Path(lpath)
+        bundle_dir = p
+
+        # Handle ZIP extraction
+        if not p.is_dir():
+            import tempfile
+            import zipfile
+            temp_dir = Path(tempfile.mkdtemp())
+            with zipfile.ZipFile(p, 'r') as zf:
+                zf.extractall(temp_dir)
+            bundle_dir = temp_dir
+
+        # Find PNG file - layered format stores in exports/
+        basename = bundle.get('basename', 'plot')
+        png_path = bundle_dir / "exports" / f"{basename}.png"
+        if not png_path.exists():
+            # Fallback to root level (legacy format)
+            png_path = bundle_dir / f"{basename}.png"
+
+        # Load the PNG as a figure
+        if png_path.exists():
+            img = plt.imread(str(png_path))
+            fig, ax = plt.subplots()
+            ax.imshow(img)
+            ax.axis('off')
+
+            # Attach metadata from spec
+            spec = bundle.get('spec', {})
+            if spec:
+                # Handle both layered and legacy spec formats
+                axes_list = spec.get('axes', [])
+                if axes_list and isinstance(axes_list, list):
+                    for key, val in axes_list[0].items():
+                        setattr(ax, f'_scitex_{key}', val)
+                # Theme from style (layered) or spec (legacy)
+                style = bundle.get('style', {})
+                theme = style.get('theme', {}) if style else spec.get('theme', {})
+                if theme:
+                    fig._scitex_theme = theme.get('mode')
+
+            # Data from bundle (merged in load_layered_pltz_bundle)
+            data = bundle.get('data')
+            return fig, ax, data
+        else:
+            # No PNG, return spec and data
+            return bundle.get('spec'), None, bundle.get('data')
+
+    elif bundle_type == BundleType.FIGZ:
+        # Return figure dict for .figz bundles
+        return bundle
+
+    elif bundle_type == BundleType.STATSZ:
+        # Return stats dict for .statsz bundles
+        return bundle
+
+    return bundle
+
+
 def load(
     lpath: Union[str, Path],
     ext: str = None,
@@ -157,6 +249,12 @@ def load(
     if lpath.endswith(".canvas"):
         return _load_canvas(lpath, verbose=verbose, **kwargs)
 
+    # Handle bundle formats (.pltz, .figz, .statsz and their .d variants)
+    bundle_extensions = (".figz", ".pltz", ".statsz")
+    for bext in bundle_extensions:
+        if lpath.endswith(bext) or lpath.endswith(f"{bext}.d"):
+            return _load_bundle(lpath, verbose=verbose, **kwargs)
+
     # Check if it's a glob pattern
     if "*" in lpath or "?" in lpath or "[" in lpath:
         # Handle glob pattern

scitex/io/_load_modules/_H5Explorer.py

@@ -11,7 +11,6 @@ __DIR__ = os.path.dirname(__FILE__)
 
 import random
 import time
-import warnings
 
 # Time-stamp: "2025-06-13 21:00:00 (ywatanabe)"
 
@@ -22,6 +21,10 @@ from typing import Any, Dict, List, Optional
 import h5py
 import numpy as np
 
+from scitex import logging
+
+logger = logging.getLogger(__name__)
+
 
 class H5Explorer:
     """Interactive HDF5 file explorer.
@@ -262,7 +265,7 @@ def explore_h5(filepath: str) -> None:
         explorer.explore()
         explorer.close()
     else:
-        warnings.warn(f"Warning: File does not exist: {filepath}")
+        logger.warning(f"File does not exist: {filepath}")
 
 
 def has_h5_key(h5_path, key, max_retries=3, action_on_corrupted="delete"):

scitex/io/_load_modules/_canvas.py

@@ -3,7 +3,7 @@
 # Timestamp: 2025-12-08
 # File: /home/ywatanabe/proj/scitex-code/src/scitex/io/_load_modules/_canvas.py
 """
-Load canvas directory (.canvas) for scitex.vis.
+Load canvas directory (.canvas) for scitex.fig.
 
 Canvas directories are portable figure bundles containing:
     - canvas.json: Layout, panels, composition settings
@@ -100,7 +100,7 @@ def _load_canvas(
     # Return Canvas object by default
     if not as_dict:
         try:
-            from scitex.vis.canvas import Canvas
+            from scitex.fig.canvas import Canvas
 
             canvas_obj = Canvas.from_dict(canvas_dict)
             # Store reference to original directory for copying

scitex/io/_load_modules/_image.py

@@ -3,11 +3,12 @@
 # Time-stamp: "2024-11-14 07:55:38 (ywatanabe)"
 # File: ./scitex_repo/src/scitex/io/_load_modules/_image.py
 
-import logging
 from typing import Any, Dict, Optional, Tuple, Union
 
 from PIL import Image
 
+from scitex import logging
+
 logger = logging.getLogger(__name__)
 
 
@@ -58,9 +59,7 @@ def _load_image(
 
     except Exception as e:
         # If metadata reading fails, return None
-        import warnings
-
-        warnings.warn(f"Failed to read metadata: {e}")
+        logger.warning(f"Failed to read metadata: {e}")
         return img, None