scitex 2.5.0__py3-none-any.whl → 2.7.3__py3-none-any.whl

scitex/git/_validation.py

@@ -30,27 +30,27 @@ def validate_branch_name(name: str) -> Tuple[bool, str]:
 
     name = name.strip()
 
-    if name.startswith('-'):
+    if name.startswith("-"):
         return False, "Branch name cannot start with '-'"
 
-    if name.endswith('.lock'):
+    if name.endswith(".lock"):
         return False, "Branch name cannot end with '.lock'"
 
-    if '..' in name:
+    if ".." in name:
         return False, "Branch name cannot contain '..'"
 
-    invalid_chars = ['~', '^', ':', '?', '*', '[', '\\', ' ', '\t']
+    invalid_chars = ["~", "^", ":", "?", "*", "[", "\\", " ", "\t"]
     for char in invalid_chars:
         if char in name:
             return False, f"Branch name cannot contain '{char}'"
 
-    if name.endswith('/'):
+    if name.endswith("/"):
         return False, "Branch name cannot end with '/'"
 
-    if name.startswith('/'):
+    if name.startswith("/"):
         return False, "Branch name cannot start with '/'"
 
-    if '//' in name:
+    if "//" in name:
         return False, "Branch name cannot contain consecutive slashes"
 
     return True, ""
@@ -99,7 +99,7 @@ def validate_path(path: Path, must_exist: bool = False) -> Tuple[bool, str]:
             return False, f"Path does not exist: {path}"
 
         path_str = str(resolved)
-        if '..' in path.parts:
+        if ".." in path.parts:
             return False, "Path contains parent directory references"
 
         return True, ""

scitex/git/_workflow.py

@@ -37,7 +37,9 @@ def setup_branches(repo_path: Path, template_name: str, verbose: bool = True) ->
     if not git_add_all(repo_path, verbose=verbose):
         return False
 
-    if not git_commit(repo_path, f"Initial commit from {template_name}", verbose=verbose):
+    if not git_commit(
+        repo_path, f"Initial commit from {template_name}", verbose=verbose
+    ):
         return False
 
     if not git_branch_rename(repo_path, "main", verbose=verbose):
@@ -70,9 +72,7 @@ def _rollback_commit(repo_path: Path, verbose: bool = True) -> None:
 
     with _in_directory(repo_path):
         result = sh(
-            ["git", "reset", "--soft", "HEAD~1"],
-            verbose=verbose,
-            return_as="dict"
+            ["git", "reset", "--soft", "HEAD~1"], verbose=verbose, return_as="dict"
         )
         if result["success"]:
             logger.info("Rolled back commit due to workflow failure")

scitex/io/__init__.py

@@ -4,6 +4,7 @@
 # File: /ssh:sp:/home/ywatanabe/proj/scitex_repo/src/scitex/io/__init__.py
 # ----------------------------------------
 import os
+
 __FILE__ = __file__
 __DIR__ = os.path.dirname(__FILE__)
 # ----------------------------------------
@@ -12,6 +13,13 @@ __DIR__ = os.path.dirname(__FILE__)
 # Import commonly used functions directly
 from ._save import save
 from ._load import load
+
+# Bundle I/O for .figz, .pltz, .statsz
+# Users should use module-specific save/load functions:
+#   - scitex.plt.save_pltz() / load_pltz()
+#   - scitex.fig.save_figz() / load_figz()
+#   - scitex.stats.save_statsz() / load_statsz()
+# Internal bundle functions available via scitex.io._bundle for module implementations
 from ._load_configs import load_configs
 from ._glob import glob, parse_glob
 from ._reload import reload
@@ -24,7 +32,7 @@ from ._load_modules._ZarrExplorer import ZarrExplorer, explore_zarr, has_zarr_ke
 from ._load_cache import (
     get_cache_info,
     configure_cache,
-    clear_cache as clear_load_cache
+    clear_cache as clear_load_cache,
 )
 
 # Import save module functions
@@ -78,39 +86,16 @@ except ImportError:
     has_metadata = None
 
 __all__ = [
+    # Primary I/O
     "save",
     "load",
+    # Config loading
     "load_configs",
+    # File utilities
     "glob",
-    "parse_glob",
     "reload",
     "flush",
     "cache",
-    "H5Explorer",
-    "explore_h5",
-    "has_h5_key",
-    "path",
-    "mv_to_tmp",
-    "json2md",
-    "save_image",
-    "save_text",
-    "save_mp4",
-    "save_listed_dfs_as_csv",
-    "save_listed_scalars_as_csv",
-    "save_optuna_study_as_csv_and_pngs",
-    "ZarrExplorer",
-    "explore_zarr",
-    "has_zarr_key",
-    "migrate_h5_to_zarr",
-    "migrate_h5_to_zarr_batch",
-    # Load cache control functions
-    "get_cache_info",
-    "configure_cache",
-    "clear_load_cache",
-    # Metadata functions
-    "read_metadata",
-    "embed_metadata",
-    "has_metadata",
 ]
 
 # EOF

scitex/io/_bundle.py

@@ -0,0 +1,434 @@
+#!/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]) -> Dict[str, Any]:
+    """Load bundle from directory or ZIP transparently.
+
+    Args:
+        path: Path to bundle (directory or ZIP).
+
+    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:
+        # ZIP archive - extract to temp and load
+        result["is_zip"] = True
+        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
+    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,
+) -> 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.
+
+    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
+
+    # Create directory
+    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
+    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/_glob.py

@@ -23,7 +23,7 @@ def glob(expression: Union[str, Path], parse=False, ensure_one=False):
     Parameters:
     -----------
     expression : Union[str, Path]
-        The glob pattern to match against file paths. Can be a string or pathlib.Path object. 
+        The glob pattern to match against file paths. Can be a string or pathlib.Path object.
         Supports standard glob syntax and curly brace expansion (e.g., 'dir/{a,b}/*.txt').
     parse : bool, optional
         Whether to parse the matched paths. Default is False.
@@ -56,7 +56,7 @@ def glob(expression: Union[str, Path], parse=False, ensure_one=False):
     # Convert Path objects to strings for consistency
     if isinstance(expression, Path):
         expression = str(expression)
-        
+
     glob_pattern = _re.sub(r"{[^}]*}", "*", expression)
     # Enable recursive globbing for ** patterns
     recursive = "**" in glob_pattern

scitex/io/_json2md.py

@@ -5,9 +5,8 @@
 # ----------------------------------------
 from __future__ import annotations
 import os
-__FILE__ = (
-    "./src/scitex/io/_json2md.py"
-)
+
+__FILE__ = "./src/scitex/io/_json2md.py"
 __DIR__ = os.path.dirname(__FILE__)
 # ----------------------------------------
 
@@ -15,6 +14,7 @@ import json
 import sys
 import argparse
 
+
 def json2md(obj, level=1):
     output = []
     if isinstance(obj, dict):