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

scitex/fts/_bundle/_children.py

@@ -0,0 +1,216 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-12-21 06:10:24 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/fts/_bundle/_children.py
+
+# Timestamp: 2025-12-20
+
+"""Child embedding for FTS composite bundles.
+
+This module handles embedding child bundles into composite FTS containers.
+Children are stored in the children/ directory with UUID-based names to avoid
+collisions, while labels and positions are stored in layout.panels.
+
+Design principles:
+- Use child's own node.id (from canonical/spec.json) for naming
+- Handle collisions with _2, _3, etc. suffixes
+- Return (child_name, child_id) tuple for identity tracking
+- Always validate child is valid FTS bundle
+"""
+
+import tempfile
+import zipfile
+from pathlib import Path
+from typing import TYPE_CHECKING
+from typing import Dict, Tuple, Union
+
+from ._storage import Storage
+from ._storage import get_storage
+
+if TYPE_CHECKING:
+    from ._FTS import FTS
+
+
+class ValidationError(Exception):
+    """Error raised when bundle validation fails."""
+
+    pass
+
+
+def embed_child(
+    container_storage: Storage,
+    child_path: Union[str, Path],
+    validate: bool = False,  # Default False for WIP workflows
+) -> Tuple[str, str]:
+    """Embed a child bundle into container's children/ directory.
+
+    Uses the child's own node.id (from canonical/spec.json) for naming to
+    preserve identity. Handles collisions with _2, _3, etc. suffixes.
+
+    Args:
+        container_storage: Storage for the container bundle
+        child_path: Path to child bundle (.zip or directory)
+        validate: Validate child is valid FTS bundle (default False for WIP)
+
+    Returns:
+        (child_name, child_id):
+            child_name: Filename in children/ (e.g., "690b1931.zip" or "690b1931_2.zip")
+            child_id: Full UUID from child's spec.json (for identity tracking)
+
+    Raises:
+        ValidationError: If validate=True and child is invalid FTS bundle
+        FileNotFoundError: If child path doesn't exist
+    """
+    child_path = Path(child_path)
+    if not child_path.exists():
+        raise FileNotFoundError(f"Child bundle not found: {child_path}")
+
+    # Load child bundle to get its node.id and optionally validate
+    from ._FTS import FTS
+
+    child_fts = FTS(child_path)
+
+    if validate:
+        errors = child_fts.validate()
+        if errors:
+            raise ValidationError(f"Invalid child bundle: {errors}")
+
+    # Get child's identity
+    full_child_id = child_fts.node.id
+    short_id = full_child_id[:8]
+
+    # Determine child filename with collision handling
+    child_name = f"{short_id}.zip"
+    suffix = 2
+    while container_storage.exists(f"children/{child_name}"):
+        child_name = f"{short_id}_{suffix}.zip"
+        suffix += 1
+
+    # Copy child bundle into children/ directory
+    _copy_child_to_storage(container_storage, child_path, child_name)
+
+    return child_name, full_child_id
+
+
+def _copy_child_to_storage(
+    container_storage: Storage,
+    child_path: Path,
+    child_name: str,
+) -> None:
+    """Copy child bundle into container's children/ directory.
+
+    Handles both ZIP and directory child bundles, always storing as ZIP.
+    The child ZIP uses a prefix matching its name (for proper unzip behavior).
+    """
+    import io
+
+    dest_path = f"children/{child_name}"
+    # Use child_name (e.g., "6352df06.zip") stem as prefix
+    child_prefix = child_name.replace(".zip", "") + "/"
+
+    if child_path.suffix == ".zip":
+        # Read ZIP contents and copy to container
+        with zipfile.ZipFile(child_path, "r") as zf:
+            buf = io.BytesIO()
+            with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as out_zf:
+                # Get original prefix (e.g., "my_plot/" from "my_plot.zip")
+                orig_prefix = child_path.stem + "/"
+                for item in zf.namelist():
+                    if item.endswith("/"):  # Skip directory entries
+                        continue
+                    data = zf.read(item)
+                    # Strip original prefix and add new prefix
+                    if item.startswith(orig_prefix):
+                        rel_path = item[len(orig_prefix) :]
+                    else:
+                        rel_path = item
+                    out_zf.writestr(child_prefix + rel_path, data)
+
+            container_storage.write(dest_path, buf.getvalue())
+    else:
+        # Directory bundle: create ZIP from directory
+        buf = io.BytesIO()
+        with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as out_zf:
+            for item in child_path.rglob("*"):
+                if item.is_file():
+                    rel_path = item.relative_to(child_path)
+                    out_zf.writestr(
+                        child_prefix + str(rel_path), item.read_bytes()
+                    )
+
+        container_storage.write(dest_path, buf.getvalue())
+
+
+def load_embedded_children(
+    container_path: Union[str, Path],
+) -> Dict[str, "FTS"]:
+    """Load all embedded children from children/ directory.
+
+    Args:
+        container_path: Path to container bundle
+
+    Returns:
+        Dict mapping child_name -> FTS object
+    """
+    from ._FTS import FTS
+
+    container_path = Path(container_path)
+    storage = get_storage(container_path)
+
+    children = {}
+    for item in storage.list():
+        if item.startswith("children/") and item.endswith(".zip"):
+            child_name = item.split("/", 1)[1]
+            # Extract child to temp and load
+            child_fts = _load_child_from_storage(storage, child_name)
+            if child_fts:
+                children[child_name] = child_fts
+
+    return children
+
+
+def _load_child_from_storage(
+    storage: Storage,
+    child_name: str,
+) -> "FTS":
+    """Load a single child bundle from storage.
+
+    Extracts child ZIP to temp directory and loads as FTS.
+    The temp file name matches the prefix inside the ZIP.
+
+    NOTE: Temp files are kept alive because FTS.validate() needs to
+    access storage for file existence checks. The OS will clean up
+    temp files eventually, or they can be cleaned up explicitly.
+    """
+    from ._FTS import FTS
+
+    child_path = f"children/{child_name}"
+
+    # Check if child exists
+    if not storage.exists(child_path):
+        return None
+
+    # Read child ZIP data
+    child_data = storage.read(child_path)
+
+    # Create temp directory and use matching filename
+    # The child ZIP has files prefixed with child_name stem (e.g., "6352df06/canonical/...")
+    # ZipStorage uses the file stem as prefix, so temp file must match
+    tmp_dir = Path(tempfile.mkdtemp())
+    tmp_path = tmp_dir / child_name  # Use same name to match internal prefix
+
+    tmp_path.write_bytes(child_data)
+    fts = FTS(tmp_path)
+    # Store temp path reference on FTS object for potential cleanup
+    fts._temp_path = tmp_path
+    fts._temp_dir = tmp_dir
+    return fts
+
+
+__all__ = [
+    "embed_child",
+    "load_embedded_children",
+    "ValidationError",
+]
+
+# EOF

scitex/fts/_bundle/_conversion/__init__.py

@@ -0,0 +1,15 @@
+#!/usr/bin/env python3
+# Timestamp: 2025-12-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/fsb/_conversion/__init__.py
+
+"""FTS Conversion Utilities."""
+
+from .bundle2dict import bundle_to_dict
+from .dict2bundle import dict_to_bundle
+
+__all__ = [
+    "bundle_to_dict",
+    "dict_to_bundle",
+]
+
+# EOF

scitex/fts/_bundle/_conversion/_bundle2dict.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+# Timestamp: 2025-12-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/fsb/_conversion/bundle2dict.py
+
+"""Convert FTS bundle to dictionary."""
+
+from typing import TYPE_CHECKING, Any, Dict
+
+if TYPE_CHECKING:
+    from .._FSB import FTS
+
+
+def bundle_to_dict(bundle: "FTS") -> Dict[str, Any]:
+    """Convert Figure-Statistics Bundle to a flat dictionary.
+
+    Args:
+        bundle: Figure-Statistics Bundle instance.
+
+    Returns:
+        Dictionary with all bundle data.
+    """
+    result = {
+        "path": str(bundle.path),
+        "is_zip": bundle.path.suffix == ".zip",
+        "type": bundle.bundle_type,
+    }
+
+    if bundle.node:
+        result["node"] = bundle.node.to_dict()
+    if bundle._encoding:
+        result["encoding"] = bundle._encoding.to_dict()
+    if bundle._theme:
+        result["theme"] = bundle._theme.to_dict()
+    if bundle._stats:
+        result["stats"] = bundle._stats.to_dict()
+    if bundle._data_info:
+        result["data_info"] = bundle._data_info.to_dict()
+
+    return result
+
+
+__all__ = ["bundle_to_dict"]
+
+# EOF

scitex/fts/_bundle/_conversion/_dict2bundle.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+# Timestamp: 2025-12-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/fsb/_conversion/dict2bundle.py
+
+"""Convert dictionary to FTS bundle."""
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Dict, Union
+
+if TYPE_CHECKING:
+    from .._FSB import FTS
+
+
+def dict_to_bundle(
+    data: Dict[str, Any],
+    path: Union[str, Path],
+) -> "FTS":
+    """Create Figure-Statistics Bundle from dictionary data.
+
+    Args:
+        data: Dictionary with 'node', 'encoding', 'theme', etc.
+        path: Path for the new bundle.
+
+    Returns:
+        Figure-Statistics Bundle instance.
+    """
+    from .._FSB import FTS
+
+    node_data = data.get("node", {})
+    node_type = node_data.get("type", "plot")
+    name = node_data.get("name")
+    size_mm = node_data.get("size_mm")
+
+    bundle = FTS(path, create=True, node_type=node_type, name=name, size_mm=size_mm)
+
+    if "encoding" in data:
+        bundle.encoding = data["encoding"]
+    if "theme" in data:
+        bundle.theme = data["theme"]
+    if "stats" in data:
+        bundle.stats = data["stats"]
+    if "data_info" in data:
+        bundle.data_info = data["data_info"]
+
+    return bundle
+
+
+__all__ = ["dict_to_bundle"]
+
+# EOF

scitex/fts/_bundle/_dataclasses/_Axes.py

@@ -0,0 +1,57 @@
+#!/usr/bin/env python3
+# Timestamp: 2025-12-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/fsb/_dataclasses/Axes.py
+
+"""Axes - Axis configuration for plot nodes."""
+
+from dataclasses import dataclass
+from typing import Any, Dict, Optional, Tuple
+
+
+@dataclass
+class Axes:
+    """Axis configuration for plot nodes.
+
+    Defines axis limits, scales, and labels.
+    """
+
+    xlim: Optional[Tuple[float, float]] = None
+    ylim: Optional[Tuple[float, float]] = None
+    xscale: str = "linear"  # linear, log, symlog
+    yscale: str = "linear"
+    xlabel: Optional[str] = None
+    ylabel: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        result = {}
+        if self.xlim is not None:
+            result["xlim"] = list(self.xlim)
+        if self.ylim is not None:
+            result["ylim"] = list(self.ylim)
+        if self.xscale != "linear":
+            result["xscale"] = self.xscale
+        if self.yscale != "linear":
+            result["yscale"] = self.yscale
+        if self.xlabel:
+            result["xlabel"] = self.xlabel
+        if self.ylabel:
+            result["ylabel"] = self.ylabel
+        return result
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Axes":
+        xlim = data.get("xlim")
+        ylim = data.get("ylim")
+        return cls(
+            xlim=tuple(xlim) if xlim else None,
+            ylim=tuple(ylim) if ylim else None,
+            xscale=data.get("xscale", "linear"),
+            yscale=data.get("yscale", "linear"),
+            xlabel=data.get("xlabel"),
+            ylabel=data.get("ylabel"),
+        )
+
+
+__all__ = ["Axes"]
+
+# EOF

scitex/fts/_bundle/_dataclasses/_BBox.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+# Timestamp: 2025-12-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/fsb/_dataclasses/BBox.py
+
+"""BBox - Bounding box in normalized coordinates (0-1)."""
+
+from dataclasses import dataclass
+from typing import Any, Dict
+
+
+@dataclass
+class BBox:
+    """Bounding box in normalized coordinates (0-1).
+
+    Used for positioning elements within parent containers.
+    Origin is top-left, y increases downward.
+    """
+
+    x0: float = 0.0
+    y0: float = 0.0
+    x1: float = 1.0
+    y1: float = 1.0
+
+    def __post_init__(self):
+        # Clamp to valid range
+        self.x0 = max(0.0, min(1.0, self.x0))
+        self.y0 = max(0.0, min(1.0, self.y0))
+        self.x1 = max(0.0, min(1.0, self.x1))
+        self.y1 = max(0.0, min(1.0, self.y1))
+
+    @property
+    def width(self) -> float:
+        return self.x1 - self.x0
+
+    @property
+    def height(self) -> float:
+        return self.y1 - self.y0
+
+    def to_dict(self) -> Dict[str, float]:
+        return {"x0": self.x0, "y0": self.y0, "x1": self.x1, "y1": self.y1}
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "BBox":
+        return cls(
+            x0=data.get("x0", 0.0),
+            y0=data.get("y0", 0.0),
+            x1=data.get("x1", 1.0),
+            y1=data.get("y1", 1.0),
+        )
+
+
+__all__ = ["BBox"]
+
+# EOF

scitex/fts/_bundle/_dataclasses/_ColumnDef.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+# Timestamp: 2025-12-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/fsb/_dataclasses/ColumnDef.py
+
+"""ColumnDef - Column definition with metadata."""
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class ColumnDef:
+    """Column definition with metadata."""
+
+    name: str
+    dtype: str  # float64, int64, string, bool, datetime, category
+    description: Optional[str] = None
+    unit: Optional[str] = None  # Physical unit: mV, ms, Hz, etc.
+    role: Optional[str] = None  # x, y, group, subject, condition, time, error, weight
+    missing_count: Optional[int] = None
+    unique_count: Optional[int] = None
+    min: Optional[float] = None
+    max: Optional[float] = None
+    mean: Optional[float] = None
+    std: Optional[float] = None
+    categories: Optional[List[str]] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        result = {"name": self.name, "dtype": self.dtype}
+        for attr in [
+            "description",
+            "unit",
+            "role",
+            "missing_count",
+            "unique_count",
+            "min",
+            "max",
+            "mean",
+            "std",
+            "categories",
+        ]:
+            val = getattr(self, attr)
+            if val is not None:
+                result[attr] = val
+        return result
+
+    @classmethod
+    def from_dict(cls, data: Any) -> "ColumnDef":
+        # Handle case where column is just a string (column name)
+        if isinstance(data, str):
+            return cls(name=data, dtype="unknown")
+        if not isinstance(data, dict):
+            return cls(name="", dtype="unknown")  # Default
+        return cls(
+            name=data.get("name", ""),
+            dtype=data.get("dtype", "float64"),
+            description=data.get("description"),
+            unit=data.get("unit"),
+            role=data.get("role"),
+            missing_count=data.get("missing_count"),
+            unique_count=data.get("unique_count"),
+            min=data.get("min"),
+            max=data.get("max"),
+            mean=data.get("mean"),
+            std=data.get("std"),
+            categories=data.get("categories"),
+        )
+
+
+__all__ = ["ColumnDef"]
+
+# EOF

scitex/fts/_bundle/_dataclasses/_DataFormat.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+# Timestamp: 2025-12-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/fsb/_dataclasses/DataFormat.py
+
+"""DataFormat - Data file format specification."""
+
+from dataclasses import dataclass
+from typing import Any, Dict
+
+
+@dataclass
+class DataFormat:
+    """Data file format specification."""
+
+    type: str = "csv"  # csv, tsv, parquet, json
+    encoding: str = "utf-8"
+    delimiter: str = ","
+    header_row: int = 0
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "type": self.type,
+            "encoding": self.encoding,
+            "delimiter": self.delimiter,
+            "header_row": self.header_row,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "DataFormat":
+        return cls(
+            type=data.get("type", "csv"),
+            encoding=data.get("encoding", "utf-8"),
+            delimiter=data.get("delimiter", ","),
+            header_row=data.get("header_row", 0),
+        )
+
+
+__all__ = ["DataFormat"]
+
+# EOF

scitex/fts/_bundle/_dataclasses/_DataInfo.py

@@ -0,0 +1,135 @@
+#!/usr/bin/env python3
+# Timestamp: 2025-12-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/fsb/_dataclasses/DataInfo.py
+
+"""DataInfo - Complete data info specification for a bundle."""
+
+import json
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
+from ._ColumnDef import ColumnDef
+from ._DataFormat import DataFormat
+from ._DataSource import DataSource
+
+if TYPE_CHECKING:
+    import pandas
+
+DATA_INFO_VERSION = "1.0.0"
+
+
+@dataclass
+class DataInfo:
+    """Complete data info specification for a bundle.
+
+    Stored in data/data_info.json.
+    """
+
+    columns: List[ColumnDef] = field(default_factory=list)
+    source: Optional[DataSource] = None
+    format: DataFormat = field(default_factory=DataFormat)
+    shape: Optional[Dict[str, int]] = None  # rows, columns
+
+    # Schema metadata
+    schema_name: str = "fsb.data_info"
+    schema_version: str = DATA_INFO_VERSION
+
+    def to_dict(self) -> Dict[str, Any]:
+        result = {
+            "columns": [c.to_dict() for c in self.columns],
+            "format": self.format.to_dict(),
+        }
+        if self.source:
+            result["source"] = self.source.to_dict()
+        if self.shape:
+            result["shape"] = self.shape
+        return result
+
+    def to_json(self, indent: int = 2) -> str:
+        return json.dumps(self.to_dict(), indent=indent)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "DataInfo":
+        source = None
+        if "source" in data:
+            source = DataSource.from_dict(data["source"])
+        return cls(
+            columns=[ColumnDef.from_dict(c) for c in data.get("columns", [])],
+            source=source,
+            format=DataFormat.from_dict(data.get("format", {})),
+            shape=data.get("shape"),
+        )
+
+    @classmethod
+    def from_json(cls, json_str: str) -> "DataInfo":
+        return cls.from_dict(json.loads(json_str))
+
+    def get_column(self, name: str) -> Optional[ColumnDef]:
+        """Get column definition by name."""
+        for col in self.columns:
+            if col.name == name:
+                return col
+        return None
+
+    @classmethod
+    def from_dataframe(
+        cls, df: "pandas.DataFrame", source_path: Optional[str] = None
+    ) -> "DataInfo":
+        """Create DataInfo from a pandas DataFrame."""
+        import pandas as pd
+
+        columns = []
+        for col_name in df.columns:
+            col = df[col_name]
+            dtype = str(col.dtype)
+
+            # Map pandas dtypes to our types
+            if "float" in dtype:
+                dtype_str = "float64"
+            elif "int" in dtype:
+                dtype_str = "int64"
+            elif "bool" in dtype:
+                dtype_str = "bool"
+            elif "datetime" in dtype:
+                dtype_str = "datetime"
+            elif col.dtype.name == "category":
+                dtype_str = "category"
+            else:
+                dtype_str = "string"
+
+            col_def = ColumnDef(
+                name=str(col_name),
+                dtype=dtype_str,
+                missing_count=int(col.isna().sum()),
+                unique_count=int(col.nunique()),
+            )
+
+            # Add numeric stats
+            if dtype_str in ("float64", "int64"):
+                col_def.min = float(col.min()) if not pd.isna(col.min()) else None
+                col_def.max = float(col.max()) if not pd.isna(col.max()) else None
+                col_def.mean = float(col.mean()) if not pd.isna(col.mean()) else None
+                col_def.std = float(col.std()) if not pd.isna(col.std()) else None
+
+            # Add categories
+            if dtype_str == "category" or (
+                dtype_str == "string" and col.nunique() < 20
+            ):
+                col_def.categories = col.dropna().unique().tolist()
+
+            columns.append(col_def)
+
+        source = None
+        if source_path:
+            source = DataSource(path=source_path)
+
+        return cls(
+            columns=columns,
+            source=source,
+            shape={"rows": len(df), "columns": len(df.columns)},
+        )
+
+
+__all__ = ["DATA_INFO_VERSION", "DataInfo"]
+
+# EOF