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

scitex/io/_save_modules/_symlink.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-12-21 13:11:56 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/io/_save_modules/_symlink.py
+
+
+# Timestamp: 2025-12-19
+
+"""Symlink creation utilities for save operations."""
+
+import os
+from pathlib import Path
+
+from scitex import logging
+from scitex.path._clean import clean
+from scitex.sh import sh
+from scitex.str._color_text import color_text
+
+logger = logging.getLogger()
+
+
+def symlink(spath, spath_cwd, symlink_from_cwd, verbose):
+    """Create a symbolic link from the current working directory."""
+    if symlink_from_cwd and (spath != spath_cwd):
+        os.makedirs(os.path.dirname(spath_cwd), exist_ok=True)
+        sh(["rm", "-f", f"{spath_cwd}"], verbose=False)
+        sh(["ln", "-sfr", f"{spath}", f"{spath_cwd}"], verbose=False)
+        if verbose:
+            # Get file extension to provide more informative message
+            ext = os.path.splitext(spath_cwd)[1].lower()
+            logger.success(color_text(f"(Symlinked to: {spath_cwd})"))
+
+
+# def symlink_to(spath_final, symlink_to_path, verbose):
+#     """Create a symbolic link at the specified path pointing to the saved file."""
+#     if symlink_to_path:
+#         # Convert Path objects to strings for consistency
+#         if isinstance(symlink_to_path, Path):
+#             symlink_to_path = str(symlink_to_path)
+
+#         # Clean the symlink path
+#         symlink_to_path = clean(symlink_to_path)
+
+#         # Ensure the symlink directory exists (only if there is a directory component)
+#         symlink_dir = os.path.dirname(symlink_to_path)
+#         if symlink_dir:  # Only create directory if there's a directory component
+#             os.makedirs(symlink_dir, exist_ok=True)
+
+#         # Remove existing symlink or file
+#         sh(["rm", "-f", f"{symlink_to_path}"], verbose=False)
+
+#         # Create the symlink using relative path for robustness
+#         sh(["ln", "-sfr", f"{spath_final}", f"{symlink_to_path}"], verbose=False)
+
+
+#         if verbose:
+#             symlink_to_full = (
+#                 os.path.realpath(symlink_to_path) + "/" + os.path.basename(spath_final)
+#             )
+#             logger.success(f"Symlinked: {spath_final} ->\n           {symlink_to_full}")
+def symlink_to(spath_final, symlink_to_path, verbose):
+    """Create a symbolic link at the specified path pointing to the saved file."""
+    if symlink_to_path:
+        if isinstance(symlink_to_path, Path):
+            symlink_to_path = str(symlink_to_path)
+
+        symlink_to_path = clean(symlink_to_path)
+
+        if not os.path.isabs(symlink_to_path):
+            symlink_to_path = os.path.abspath(symlink_to_path)
+
+        if os.path.isdir(symlink_to_path) or (
+            not os.path.exists(symlink_to_path)
+            and not os.path.splitext(symlink_to_path)[1]
+        ):
+            symlink_to_path = os.path.join(
+                symlink_to_path, os.path.basename(spath_final)
+            )
+
+        symlink_dir = os.path.dirname(symlink_to_path)
+        if symlink_dir:
+            os.makedirs(symlink_dir, exist_ok=True)
+
+        sh(["rm", "-f", f"{symlink_to_path}"], verbose=False)
+        sh(
+            ["ln", "-sfr", f"{spath_final}", f"{symlink_to_path}"],
+            verbose=False,
+        )
+
+        if verbose:
+            logger.success(
+                f"Symlinked: {spath_final} ->\n"
+                f"           {symlink_to_path}"
+            )
+
+# EOF

scitex/io/_save_modules/_yaml.py

@@ -62,7 +62,7 @@ def _save_yaml(obj, spath):
 
     yaml = YAML()
     yaml.preserve_quotes = True
-    yaml.indent(mapping=4, sequence=4, offset=4)
+    yaml.indent(mapping=4, sequence=4, offset=2)
 
     with open(spath, "w") as f:
         yaml.dump(obj_with_strings, f)

scitex/io/_save_modules/_zarr.py

@@ -1,5 +1,4 @@
 #!/usr/bin/env python3
-# -*- coding: utf-8 -*-
 # Timestamp: "2025-07-11 15:44:00 (ywatanabe)"
 # File: /ssh:sp:/home/ywatanabe/proj/scitex_repo/src/scitex/io/_save_modules/_zarr.py
 # ----------------------------------------
@@ -13,7 +12,55 @@ from typing import Any, Optional
 
 import numpy as np
 import zarr
-from numcodecs import Zstd, LZ4, GZip
+
+# Detect Zarr version for API compatibility
+ZARR_V3 = int(zarr.__version__.split(".")[0]) >= 3
+
+
+def _get_compressor(compressor_name):
+    """Get compressor based on Zarr version."""
+    if ZARR_V3:
+        from zarr.codecs import GzipCodec, ZstdCodec
+
+        compressor_map = {
+            "zstd": ZstdCodec(level=3),
+            "gzip": GzipCodec(level=5),
+        }
+        return compressor_map.get(compressor_name.lower(), ZstdCodec(level=3))
+    else:
+        from numcodecs import LZ4, GZip, Zstd
+
+        compressor_map = {
+            "zstd": Zstd(level=3),
+            "lz4": LZ4(acceleration=1),
+            "gzip": GZip(level=5),
+        }
+        return compressor_map.get(compressor_name.lower(), Zstd(level=3))
+
+
+def _create_array(group, name, data, chunks=True, compressor=None, **kwargs):
+    """Create array with version-appropriate API."""
+    if ZARR_V3:
+        # Zarr v3 API: use create_array with compressors list
+        comp_kwargs = {}
+        if compressor is not None:
+            comp_kwargs["compressors"] = [compressor]
+
+        # Handle chunks parameter: v3 doesn't accept True/None
+        if chunks is True:
+            chunks = "auto"
+        elif chunks is None or chunks is False:
+            # Don't pass chunks, let zarr use defaults
+            return group.create_array(name, data=data, **comp_kwargs, **kwargs)
+
+        return group.create_array(
+            name, data=data, chunks=chunks, **comp_kwargs, **kwargs
+        )
+    else:
+        # Zarr v2 API: use create_dataset with compressor
+        return group.create_dataset(
+            name, data=data, chunks=chunks, compressor=compressor, **kwargs
+        )
 
 
 def _save_zarr(
@@ -38,7 +85,7 @@ def _save_zarr(
     key : str, optional
         Key/group path within Zarr store
     compressor : str
-        Compression algorithm ('zstd', 'lz4', 'gzip')
+        Compression algorithm ('zstd', 'gzip')
     chunks : bool or tuple
         Chunking strategy
     store_type : str
@@ -60,7 +107,7 @@ def _save_zarr(
     # Create appropriate store
     if store_type == "zip":
         # Single file ZIP store
-        store = zarr.ZipStore(spath, mode="w")
+        store = zarr.storage.ZipStore(spath, mode="w")
         root = zarr.open(store, mode="w")
     else:
         # Directory store
@@ -71,17 +118,12 @@ def _save_zarr(
         # Open or create Zarr store
         try:
             root = zarr.open(spath, mode="a")
-        except:
+        except Exception:
             root = zarr.open(spath, mode="w")
 
     # Handle compressor configuration
     if isinstance(compressor, str):
-        compressor_map = {
-            "zstd": Zstd(level=3),
-            "lz4": LZ4(acceleration=1),
-            "gzip": GZip(level=5),
-        }
-        compressor = compressor_map.get(compressor.lower(), Zstd(level=3))
+        compressor = _get_compressor(compressor)
 
     # Navigate to target group
     if key:
@@ -109,12 +151,14 @@ def _save_zarr(
     for dataset_name, data in obj.items():
         if isinstance(data, str):
             # String data
-            target_group.create_dataset(
-                dataset_name, data=np.array(data), compressor=None
+            _create_array(
+                target_group, dataset_name, data=np.array(data), compressor=None
             )
         elif isinstance(data, (int, float, bool)):
-            # Scalar data - no compression needed
-            target_group.create_dataset(dataset_name, data=data)
+            # Scalar data - convert to 0-d array
+            _create_array(
+                target_group, dataset_name, data=np.array(data), compressor=None
+            )
         else:
             # Array data
             data_array = np.asarray(data)
@@ -124,7 +168,8 @@ def _save_zarr(
                 import pickle
 
                 pickled_data = pickle.dumps(data)
-                dataset = target_group.create_dataset(
+                dataset = _create_array(
+                    target_group,
                     dataset_name,
                     data=np.frombuffer(pickled_data, dtype=np.uint8),
                     compressor=compressor,
@@ -132,7 +177,8 @@ def _save_zarr(
                 dataset.attrs["_type"] = "pickled"
             else:
                 # Regular array data
-                target_group.create_dataset(
+                _create_array(
+                    target_group,
                     dataset_name,
                     data=data_array,
                     chunks=chunks,
@@ -151,7 +197,7 @@ def _save_zarr(
             print(
                 f"✅ Saved to Zarr (consolidated): {spath}" + (f"/{key}" if key else "")
             )
-        except:
+        except Exception:
             print(f"✅ Saved to Zarr: {spath}" + (f"/{key}" if key else ""))
     else:
         print(f"✅ Saved to Zarr ({store_type}): {spath}" + (f"/{key}" if key else ""))

scitex/io/bundle/README.md

@@ -0,0 +1,212 @@
+<!-- ---
+!-- Timestamp: 2025-12-16 20:36:14
+!-- Author: ywatanabe
+!-- File: /home/ywatanabe/proj/scitex-code/src/scitex/io/bundle/README.md
+!-- --- -->
+
+# SciTeX Bundle I/O
+
+## Overview
+
+SciTeX uses bundle formats for reproducible scientific figures:
+
+| Format    | Purpose             | Contents                                    |
+|-----------|---------------------|---------------------------------------------|
+| `.pltz`   | Single plot bundle  | spec.json, style.json, data.csv, exports/   |
+| `.figz`   | Multi-panel figure  | spec.json, style.json, nested .pltz bundles |
+| `.statsz` | Statistical results | spec.json, stats data, comparison metadata  |
+
+## Format Variants
+
+Each bundle can exist in two forms:
+
+| Suffix                              | Type        | Use Case                    |
+|-------------------------------------|-------------|-----------------------------|
+| `.pltz` / `.figz` / `.statsz`       | ZIP archive | Storage, transfer, download |
+| `.pltz.d` / `.figz.d` / `.statsz.d` | Directory   | Editing, development        |
+
+## Quick Start
+
+```python
+import scitex.io.bundle as bundle
+
+# Load a bundle (works with both ZIP and directory)
+data = bundle.load("Figure1.figz")
+print(data['spec'])
+print(data['type'])  # 'figz'
+
+# Save a bundle
+bundle.save(data, "output.pltz", as_zip=True)
+
+# Copy a bundle
+bundle.copy("template.pltz", "my_plot.pltz.d")
+
+# Pack/unpack between formats
+bundle.pack("plot.pltz.d")      # -> plot.pltz
+bundle.unpack("plot.pltz")       # -> plot.pltz.d/
+```
+
+## ZipBundle Class
+
+In-memory access to ZIP bundles without extraction:
+
+```python
+from scitex.io.bundle import ZipBundle
+
+# Reading
+with ZipBundle("figure.figz") as zb:
+    spec = zb.read_json("spec.json")
+    data = zb.read_csv("data.csv")
+    png = zb.read_bytes("exports/figure.png")
+
+# Writing (atomic)
+with ZipBundle("output.pltz", mode="w") as zb:
+    zb.write_json("spec.json", spec_dict)
+    zb.write_csv("data.csv", dataframe)
+    zb.write_bytes("exports/plot.png", png_bytes)
+
+# Modifying (read + write atomically)
+with ZipBundle("figure.figz", mode="a") as zb:
+    spec = zb.read_json("spec.json")
+    spec["title"] = "Updated"
+    zb.write_json("spec.json", spec)
+```
+
+## Nested Bundle Access
+
+Access pltz bundles nested inside figz:
+
+```python
+from scitex.io.bundle import nested
+
+# Get preview image
+preview = nested.get_preview("Figure1.figz/A.pltz.d")
+
+# Get JSON
+spec = nested.get_json("Figure1.figz/A.pltz.d/spec.json")
+
+# Get any file
+png = nested.get_file("Figure1.figz/A.pltz.d/exports/plot.png")
+
+# Write to nested bundle
+nested.put_json("Figure1.figz/A.pltz.d/spec.json", updated_spec)
+
+# List files
+files = nested.list_files("Figure1.figz/A.pltz.d")
+
+# Resolve full bundle data
+data = nested.resolve("Figure1.figz/A.pltz.d")
+```
+
+## Bundle Structure
+
+### .pltz Bundle
+
+```
+plot.pltz.d/
+├── spec.json          # Plot specification (traces, axes, data refs)
+├── style.json         # Visual styling (colors, fonts, sizes)
+├── data.csv           # Source data
+├── exports/
+│   ├── plot.png       # Rendered preview
+│   ├── plot_hitmap.png
+│   └── plot.svg
+└── cache/
+    └── geometry_px.json
+```
+
+### .figz Bundle
+
+```
+Figure1.figz.d/
+├── spec.json          # Figure layout, panel positions
+├── style.json         # Figure-level styling
+├── A.pltz.d/          # Panel A (nested pltz)
+├── B.pltz.d/          # Panel B (nested pltz)
+└── exports/
+    └── Figure1.png    # Composed figure
+```
+
+## API Reference
+
+### Core Operations
+
+| Function | Description |
+|----------|-------------|
+| `load(path)` | Load bundle from ZIP or directory |
+| `save(data, path)` | Save bundle to ZIP or directory |
+| `copy(src, dst)` | Copy bundle between locations |
+| `pack(dir_path)` | Convert directory to ZIP |
+| `unpack(zip_path)` | Convert ZIP to directory |
+| `validate(path)` | Validate bundle structure |
+| `is_bundle(path)` | Check if path is a bundle |
+| `get_type(path)` | Get bundle type ('figz', 'pltz', 'statsz') |
+
+### ZipBundle Methods
+
+| Method | Description |
+|--------|-------------|
+| `read_bytes(name)` | Read file as bytes |
+| `read_text(name)` | Read file as string |
+| `read_json(name)` | Read and parse JSON |
+| `read_csv(name)` | Read CSV as DataFrame |
+| `write_bytes(name, data)` | Write bytes |
+| `write_text(name, text)` | Write string |
+| `write_json(name, data)` | Write JSON |
+| `write_csv(name, df)` | Write DataFrame as CSV |
+| `namelist()` | List files in bundle |
+
+### Nested Access (bundle.nested)
+
+| Function | Description |
+|----------|-------------|
+| `nested.get_file(path)` | Get file from nested bundle |
+| `nested.get_json(path)` | Get JSON from nested bundle |
+| `nested.get_preview(path)` | Get preview PNG |
+| `nested.put_file(path, data)` | Write file to nested bundle |
+| `nested.put_json(path, data)` | Write JSON to nested bundle |
+| `nested.list_files(path)` | List files in nested bundle |
+| `nested.resolve(path)` | Load full nested bundle data |
+| `nested.parse_path(path)` | Parse nested path components |
+
+## Migration from Old API
+
+| Old Import | New Import |
+|------------|------------|
+| `from scitex.io._bundle import load_bundle` | `from scitex.io.bundle import load` |
+| `from scitex.io._bundle import save_bundle` | `from scitex.io.bundle import save` |
+| `from scitex.io._bundle import copy_bundle` | `from scitex.io.bundle import copy` |
+| `from scitex.io._bundle import pack_bundle` | `from scitex.io.bundle import pack` |
+| `from scitex.io._bundle import unpack_bundle` | `from scitex.io.bundle import unpack` |
+| `from scitex.io._bundle import validate_bundle` | `from scitex.io.bundle import validate` |
+| `from scitex.io._bundle import BundleType` | `from scitex.io.bundle import BundleType` |
+| `from scitex.io._bundle import BundleValidationError` | `from scitex.io.bundle import BundleValidationError` |
+| `from scitex.io._bundle import BUNDLE_EXTENSIONS` | `from scitex.io.bundle import EXTENSIONS` |
+| `from scitex.io._bundle import get_bundle_type` | `from scitex.io.bundle import get_type` |
+| `from scitex.io._zip_bundle import ZipBundle` | `from scitex.io.bundle import ZipBundle` |
+| `from scitex.io._zip_bundle import open_bundle` | `from scitex.io.bundle import open_zip` |
+| `from scitex.io._zip_bundle import create_bundle` | `from scitex.io.bundle import create_zip` |
+| `from scitex.io._zip_bundle import zip_directory_bundle` | `from scitex.io.bundle import zip_directory` |
+| `from scitex.io._nested_bundle import resolve_nested_bundle` | `from scitex.io.bundle import nested; nested.resolve` |
+| `from scitex.io._nested_bundle import get_nested_file` | `from scitex.io.bundle import nested; nested.get_file` |
+| `from scitex.io._nested_bundle import get_nested_json` | `from scitex.io.bundle import nested; nested.get_json` |
+| `from scitex.io._nested_bundle import get_nested_preview` | `from scitex.io.bundle import nested; nested.get_preview` |
+| `from scitex.io._nested_bundle import put_nested_file` | `from scitex.io.bundle import nested; nested.put_file` |
+| `from scitex.io._nested_bundle import put_nested_json` | `from scitex.io.bundle import nested; nested.put_json` |
+| `from scitex.io._nested_bundle import list_nested_files` | `from scitex.io.bundle import nested; nested.list_files` |
+| `from scitex.io._nested_bundle import parse_nested_path` | `from scitex.io.bundle import nested; nested.parse_path` |
+| `from scitex.io._nested_bundle import NestedBundleNotFoundError` | `from scitex.io.bundle import NestedBundleNotFoundError` |
+
+## Module Structure
+
+```
+scitex/io/bundle/
+├── __init__.py      # Public API exports
+├── _types.py        # BundleType, errors, constants
+├── _core.py         # load, save, copy, pack, unpack, validate
+├── _zip.py          # ZipBundle class and functions
+├── _nested.py       # Nested bundle access
+└── README.md        # This documentation
+```
+
+<!-- EOF -->

scitex/io/bundle/__init__.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-12-16 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/io/bundle/__init__.py
+
+"""
+SciTeX Bundle I/O - Unified bundle handling for .figz, .pltz, .statsz formats.
+
+This module provides a clean API for working with SciTeX bundles:
+    - .figz - Publication Figure Bundle (panels + layout)
+    - .pltz - Reproducible Plot Bundle (data + spec + exports)
+    - .statsz - Statistical Results Bundle (stats + metadata)
+
+Each bundle can exist in two forms:
+    - ZIP archive: Figure1.figz, plot.pltz
+    - Directory: Figure1.figz.d/, plot.pltz.d/
+
+Usage:
+    import scitex.io.bundle as bundle
+
+    # Load a bundle
+    data = bundle.load("Figure1.figz")
+
+    # Save a bundle
+    bundle.save(data, "output.pltz", as_zip=True)
+
+    # Copy a bundle
+    bundle.copy("template.pltz", "my_plot.pltz.d")
+
+    # Access ZIP bundles in-memory
+    with bundle.ZipBundle("figure.figz") as zb:
+        spec = zb.read_json("spec.json")
+        data = zb.read_csv("data.csv")
+
+    # Access nested bundles (pltz inside figz)
+    preview = bundle.nested.get_preview("Figure1.figz/A.pltz.d")
+    spec = bundle.nested.get_json("Figure1.figz/A.pltz.d/spec.json")
+"""
+
+# Types and constants
+from ._types import (
+    EXTENSIONS,
+    FIGZ,
+    PLTZ,
+    STATSZ,
+    BundleError,
+    BundleNotFoundError,
+    BundleType,
+    BundleValidationError,
+    NestedBundleNotFoundError,
+)
+
+# Core operations
+from ._core import (
+    copy,
+    dir_to_zip_path,
+    get_type,
+    is_bundle,
+    load,
+    pack,
+    save,
+    unpack,
+    validate,
+    validate_spec,
+    zip_to_dir_path,
+)
+
+# ZipBundle class and functions
+from ._zip import ZipBundle
+from ._zip import create as create_zip
+from ._zip import open as open_zip
+from ._zip import zip_directory
+
+# Nested bundle access as namespace
+from . import _nested as nested
+
+__all__ = [
+    # Types
+    "BundleType",
+    "BundleError",
+    "BundleValidationError",
+    "BundleNotFoundError",
+    "NestedBundleNotFoundError",
+    # Constants
+    "EXTENSIONS",
+    "FIGZ",
+    "PLTZ",
+    "STATSZ",
+    # Core operations
+    "load",
+    "save",
+    "copy",
+    "pack",
+    "unpack",
+    "validate",
+    "validate_spec",
+    "is_bundle",
+    "get_type",
+    "dir_to_zip_path",
+    "zip_to_dir_path",
+    # ZipBundle
+    "ZipBundle",
+    "open_zip",
+    "create_zip",
+    "zip_directory",
+    # Nested access namespace
+    "nested",
+]
+
+# EOF