scitex 2.10.3__py3-none-any.whl → 2.13.0__py3-none-any.whl

scitex/{fts/_bundle → io/bundle}/_dataclasses/__init__.py

@@ -11,17 +11,17 @@ from ._ColumnDef import ColumnDef
 from ._DataFormat import DataFormat
 from ._DataInfo import DATA_INFO_VERSION, DataInfo
 from ._DataSource import DataSource
-from ._Node import Node, ShapeParams, TextContent
-from ._NodeRefs import NodeRefs
 from ._SizeMM import SizeMM
+from ._Spec import ShapeParams, Spec, TextContent
+from ._SpecRefs import SpecRefs
 
 __all__ = [
     # Core models
     "BBox",
     "SizeMM",
     "Axes",
-    "NodeRefs",
-    "Node",
+    "Spec",
+    "SpecRefs",
     "TextContent",
     "ShapeParams",
     # Data Info

scitex/{fts/_bundle → io/bundle}/_loader.py

@@ -2,10 +2,10 @@
 # Timestamp: 2025-12-20
 # File: /home/ywatanabe/proj/scitex-code/src/scitex/fts/_bundle/_loader.py
 
-"""FTS Bundle loading utilities.
+"""SciTeX Bundle loading utilities.
 
 Loads bundles using the new canonical/artifacts/payload/children structure.
-Supports backwards compatibility with old flat structure (node.json at root).
+Supports backwards compatibility with old flat structure (spec.json at root).
 
 New structure:
     canonical/spec.json     (was node.json)
@@ -21,15 +21,15 @@ from typing import TYPE_CHECKING, Optional, Tuple
 from ._storage import get_storage
 
 if TYPE_CHECKING:
-    from ._dataclasses import DataInfo, Node
-    from .._fig import Encoding, Theme
-    from .._stats import Stats
+    from ._dataclasses import DataInfo, Spec
+    from .kinds._plot._dataclasses import Encoding, Theme
+    from .kinds._stats._dataclasses import Stats
 
 
 def load_bundle_components(
     path: Path,
 ) -> Tuple[
-    Optional["Node"],
+    Optional["Spec"],
     Optional["Encoding"],
     Optional["Theme"],
     Optional["Stats"],
@@ -43,15 +43,15 @@ def load_bundle_components(
         path: Bundle path (directory or ZIP)
 
     Returns:
-        Tuple of (node, encoding, theme, stats, data_info)
+        Tuple of (spec, encoding, theme, stats, data_info)
     """
-    from ._dataclasses import DataInfo, Node
-    from .._fig import Encoding, Theme
-    from .._stats import Stats
+    from ._dataclasses import DataInfo, Spec
+    from .kinds._plot._dataclasses import Encoding, Theme
+    from .kinds._stats._dataclasses import Stats
 
     storage = get_storage(path)
 
-    node = None
+    spec = None
     encoding = None
     theme = None
     stats = None
@@ -59,7 +59,7 @@ def load_bundle_components(
 
     # Detect structure: new (canonical/) or legacy (flat)
     # - New: canonical/spec.json
-    # - Legacy FTS: node.json at root
+    # - Legacy v1: node.json at root
     # - Legacy sio.save(): spec.json at root
     if storage.exists("canonical/spec.json"):
         structure = "v2"  # New canonical/ structure
@@ -69,15 +69,15 @@ def load_bundle_components(
         structure = "v1"  # Legacy node.json structure
     is_new_structure = structure == "v2"
 
-    # Node / spec.json
+    # Spec / spec.json
     if structure == "v2":
-        node_data = storage.read_json("canonical/spec.json")
+        spec_data = storage.read_json("canonical/spec.json")
     elif structure == "sio":
-        node_data = storage.read_json("spec.json")
+        spec_data = storage.read_json("spec.json")
     else:
-        node_data = storage.read_json("node.json")
-    if node_data:
-        node = Node.from_dict(node_data)
+        spec_data = storage.read_json("node.json")
+    if spec_data:
+        spec = Spec.from_dict(spec_data)
 
     # Encoding
     if is_new_structure:
@@ -111,7 +111,7 @@ def load_bundle_components(
     if data_info_data:
         data_info = DataInfo.from_dict(data_info_data)
 
-    return node, encoding, theme, stats, data_info
+    return spec, encoding, theme, stats, data_info
 
 
 def get_bundle_structure_version(path: Path) -> str:

scitex/io/bundle/_manifest.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+# Timestamp: 2026-01-07
+# File: src/scitex/io/bundle/_manifest.py
+
+"""Bundle manifest handling.
+
+Manifests are JSON files inside bundles that identify the bundle type
+and version. This provides a more reliable way to identify bundle types
+than relying solely on file extensions.
+
+Example manifest.json:
+    {
+        "scitex": {
+            "type": "plot",
+            "version": "1.0.0"
+        }
+    }
+"""
+
+import json
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+__all__ = [
+    "MANIFEST_FILENAME",
+    "create_manifest",
+    "write_manifest",
+    "read_manifest",
+    "get_type_from_manifest",
+]
+
+MANIFEST_FILENAME = "manifest.json"
+
+
+def create_manifest(bundle_type: str, version: str = "1.0.0") -> Dict[str, Any]:
+    """Create a manifest dictionary.
+
+    Args:
+        bundle_type: Type of bundle ('plot', 'figure', 'stats')
+        version: Bundle format version
+
+    Returns:
+        Manifest dictionary
+    """
+    return {"scitex": {"type": bundle_type, "version": version}}
+
+
+def write_manifest(bundle_path: Path, bundle_type: str, version: str = "1.0.0") -> None:
+    """Write manifest.json to bundle directory.
+
+    Args:
+        bundle_path: Path to bundle directory
+        bundle_type: Type of bundle
+        version: Bundle format version
+    """
+    manifest = create_manifest(bundle_type, version)
+    manifest_path = Path(bundle_path) / MANIFEST_FILENAME
+    with open(manifest_path, "w") as f:
+        json.dump(manifest, f, indent=2)
+
+
+def read_manifest(bundle_path: Path) -> Optional[Dict[str, Any]]:
+    """Read manifest.json from bundle.
+
+    Args:
+        bundle_path: Path to bundle (directory or ZIP)
+
+    Returns:
+        Manifest dictionary or None if not found
+    """
+    bundle_path = Path(bundle_path)
+    manifest_path = bundle_path / MANIFEST_FILENAME
+
+    if not manifest_path.exists():
+        return None
+
+    try:
+        with open(manifest_path) as f:
+            return json.load(f)
+    except (OSError, json.JSONDecodeError):
+        return None
+
+
+def get_type_from_manifest(bundle_path: Path) -> Optional[str]:
+    """Get bundle type from manifest.
+
+    Args:
+        bundle_path: Path to bundle
+
+    Returns:
+        Bundle type string or None if manifest not found/invalid
+    """
+    manifest = read_manifest(bundle_path)
+    if manifest and "scitex" in manifest:
+        return manifest["scitex"].get("type")
+    return None
+
+
+# EOF

scitex/{fts/_bundle → io/bundle}/_mpl_helpers.py

@@ -1,8 +1,8 @@
 #!/usr/bin/env python3
-# Timestamp: 2025-12-20
-# File: /home/ywatanabe/proj/scitex-code/src/scitex/fts/_bundle/_mpl_helpers.py
+# Timestamp: 2026-01-07
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/io/bundle/_mpl_helpers.py
 
-"""Matplotlib helper functions for FTS bundle creation."""
+"""Matplotlib helper functions for bundle creation."""
 
 import warnings
 from typing import TYPE_CHECKING, Any, Optional
@@ -10,7 +10,7 @@ from typing import TYPE_CHECKING, Any, Optional
 if TYPE_CHECKING:
     from matplotlib.figure import Figure as MplFigure
 
-    from .._fig import Encoding, Theme
+    from .kinds._plot._dataclasses import Encoding, Theme
 
 
 def _get_scitex_axes(fig: "MplFigure") -> Optional[Any]:
@@ -33,16 +33,27 @@ def _get_scitex_axes(fig: "MplFigure") -> Optional[Any]:
     return None
 
 
+def _simplify_csv_columns(csv_df: "Any") -> "Any":
+    """CSV columns already use figrecipe-compatible format: r{row}c{col}_{caller}-{id}_{var}.
+
+    This function is now a pass-through since the new format is already simple and consistent.
+    Kept for backward compatibility with any code that calls it.
+    """
+    # New format r{row}c{col}_{caller}-{id}_{var} is already simple
+    # No simplification needed
+    return csv_df
+
+
 def _build_encoding_from_csv_columns(csv_df: "Any") -> "Encoding":
-    """Build encoding from actual CSV column names.
+    """Build encoding from CSV column names (simple or verbose format).
 
-    Handles two formats:
-    1. Verbose: ax-row-{row}-col-{col}_trace-id-{id}_variable-{var}
-    2. Simple: column names like 'x', 'y' (user-provided DataFrames)
+    Handles:
+    1. Simple: x, y, trace_x, trace_y, ax0_0_trace_x
+    2. Verbose: ax-row-{row}-col-{col}_trace-id-{id}_variable-{var}
 
     This ensures encoding references match actual data columns.
     """
-    from .._fig._dataclasses import ChannelEncoding, Encoding, TraceEncoding
+    from .kinds._plot._dataclasses import ChannelEncoding, Encoding, TraceEncoding
 
     if csv_df is None or csv_df.empty:
         return Encoding(traces=[])
@@ -89,7 +100,9 @@ def _build_encoding_from_csv_columns(csv_df: "Any") -> "Encoding":
                 if x_col is None:
                     x_col = numeric_cols[0]
                 if y_col is None:
-                    y_col = numeric_cols[1] if numeric_cols[1] != x_col else numeric_cols[0]
+                    y_col = (
+                        numeric_cols[1] if numeric_cols[1] != x_col else numeric_cols[0]
+                    )
             elif len(numeric_cols) == 1:
                 if x_col is None:
                     x_col = numeric_cols[0]
@@ -127,14 +140,10 @@ def validate_encoding_csv_link(encoding: "Encoding", csv_df: "Any") -> list:
     for trace in encoding.traces:
         if trace.x and trace.x.column:
             if trace.x.column not in csv_columns:
-                errors.append(
-                    f"Encoding references missing column: {trace.x.column}"
-                )
+                errors.append(f"Encoding references missing column: {trace.x.column}")
         if trace.y and trace.y.column:
             if trace.y.column not in csv_columns:
-                errors.append(
-                    f"Encoding references missing column: {trace.y.column}"
-                )
+                errors.append(f"Encoding references missing column: {trace.y.column}")
 
     return errors
 
@@ -183,18 +192,84 @@ def extract_data_from_mpl_figure(fig: "MplFigure") -> Optional[Any]:
     return pd.DataFrame(padded)
 
 
+def _build_encoding_from_history(
+    history: dict, ax_row: int = 0, ax_col: int = 0
+) -> "Encoding":
+    """Build encoding from scitex.plt axes history.
+
+    Converts tracking history to Encoding with column names matching
+    the figrecipe-compatible CSV format: r{row}c{col}_{caller}-{id}_{var}
+
+    Parameters
+    ----------
+    history : dict
+        History dict: {trace_id: (trace_id, method, tracked_dict, kwargs)}
+    ax_row : int
+        Row position of axes in grid
+    ax_col : int
+        Column position of axes in grid
+
+    Returns
+    -------
+    Encoding
+        Encoding object with traces referencing CSV column names.
+    """
+    from scitex.plt.utils._csv_column_naming import get_csv_column_name, sanitize_id
+
+    from .kinds._plot._dataclasses import ChannelEncoding, Encoding, TraceEncoding
+
+    traces = []
+
+    # Track per-method counters for auto-generated IDs
+    method_counters = {}
+
+    for record_id, record in history.items():
+        if not isinstance(record, tuple) or len(record) < 4:
+            continue
+
+        id_val, method, tracked_dict, kwargs = record
+
+        # Extract user-provided id from kwargs if present
+        user_id = kwargs.get("id") if kwargs else None
+
+        # Determine trace_id: use user-provided id or auto-generate
+        if user_id:
+            trace_id = sanitize_id(user_id)
+        else:
+            # Auto-generate: per-method counter
+            counter = method_counters.get(method, 0)
+            method_counters[method] = counter + 1
+            trace_id = str(counter)
+
+        # Build column names using the new format
+        x_col = get_csv_column_name("x", ax_row, ax_col, method, trace_id=trace_id)
+        y_col = get_csv_column_name("y", ax_row, ax_col, method, trace_id=trace_id)
+
+        # Create trace encoding
+        trace = TraceEncoding(
+            trace_id=f"{method}-{trace_id}",
+            x=ChannelEncoding(column=x_col),
+            y=ChannelEncoding(column=y_col),
+        )
+        traces.append(trace)
+
+    return Encoding(traces=traces)
+
+
 def build_encoding_from_mpl_figure(fig: "MplFigure") -> "Encoding":
     """Build encoding specification from matplotlib figure.
 
     Uses scitex.plt tracking if available (captures actual plot method),
     otherwise falls back to detecting from rendered figure.
     """
-    from .._fig._dataclasses import Encoding
+    from .kinds._plot._dataclasses import Encoding
 
     # Try scitex.plt tracking first (knows exact plot method)
     scitex_ax = _get_scitex_axes(fig)
     if scitex_ax is not None and hasattr(scitex_ax, "history") and scitex_ax.history:
-        return _build_encoding_from_history(scitex_ax.history)
+        encoding = _build_encoding_from_history(scitex_ax.history)
+        if encoding and encoding.traces:
+            return encoding
 
     # Fallback: detect from rendered figure
     from ._extractors import build_bar_traces, build_line_traces, build_scatter_traces
@@ -212,7 +287,7 @@ def build_encoding_from_mpl_figure(fig: "MplFigure") -> "Encoding":
 
 def build_theme_from_mpl_figure(fig: "MplFigure") -> "Theme":
     """Build theme specification from matplotlib figure."""
-    from .._fig import Theme
+    from .kinds._plot._dataclasses import Theme
 
     return Theme()
 
@@ -220,7 +295,10 @@ def build_theme_from_mpl_figure(fig: "MplFigure") -> "Theme":
 def extract_geometry_from_mpl_figure(fig: "MplFigure") -> dict:
     """Extract geometry data from matplotlib figure for hit testing."""
     try:
-        from scitex.plt.utils._hitmap import extract_path_data, extract_selectable_regions
+        from scitex.plt.utils._hitmap import (
+            extract_path_data,
+            extract_selectable_regions,
+        )
 
         return {
             "path_data": extract_path_data(fig),
@@ -257,7 +335,9 @@ def generate_hitmap_from_mpl_figure(fig: "MplFigure", dpi: int = 300) -> tuple:
         png_buf = io.BytesIO()
         with warnings.catch_warnings():
             warnings.filterwarnings("ignore", message=".*tight_layout.*")
-            fig.savefig(png_buf, format="png", dpi=dpi, facecolor=HITMAP_BACKGROUND_COLOR)
+            fig.savefig(
+                png_buf, format="png", dpi=dpi, facecolor=HITMAP_BACKGROUND_COLOR
+            )
         png_bytes = png_buf.getvalue()
 
         svg_buf = io.BytesIO()
@@ -283,7 +363,7 @@ def from_matplotlib(
     csv_df: Optional[Any] = None,
     dpi: int = 300,
 ):
-    """Create FTS bundle from matplotlib figure.
+    """Create Bundle from matplotlib figure.
 
     Args:
         fig: Matplotlib figure object
@@ -300,7 +380,7 @@ def from_matplotlib(
     import json
     from pathlib import Path
 
-    from ._FTS import FTS
+    from ._Bundle import Bundle
     from ._saver import save_bundle_components
 
     path = Path(path)
@@ -311,13 +391,18 @@ def from_matplotlib(
         "height": round(fig_height_inch * 25.4, 2),
     }
 
-    bundle = FTS(path, create=True, kind="plot", name=name, size_mm=size_mm)
+    bundle = Bundle(path, create=True, kind="plot", name=name, size_mm=size_mm)
 
     if csv_df is None:
         csv_df = extract_data_from_mpl_figure(fig)
 
     if csv_df is not None and not csv_df.empty:
-        bundle._node.payload_schema = "scitex.fts.payload.plot@1"
+        bundle._spec.payload_schema = "scitex.io.bundle.payload.plot@1"
+
+    # Simplify CSV column names for bundle (figrecipe-style)
+    # Converts: ax-row-0-col-0_trace-id-sine_variable-x → sine_x (or just x)
+    if csv_df is not None and not csv_df.empty:
+        csv_df = _simplify_csv_columns(csv_df)
 
     # Build encoding from actual CSV columns (single source of truth)
     # This ensures encoding references match real data columns
@@ -342,7 +427,9 @@ def from_matplotlib(
             "dtypes": {col: str(dtype) for col, dtype in csv_df.dtypes.items()},
             "shape": list(csv_df.shape),
         }
-        storage.write("canonical/data_info.json", json.dumps(data_info, indent=2).encode())
+        storage.write(
+            "canonical/data_info.json", json.dumps(data_info, indent=2).encode()
+        )
 
     for fmt in ["png", "svg", "pdf"]:
         buf = io.BytesIO()
@@ -353,7 +440,9 @@ def from_matplotlib(
 
     geometry = extract_geometry_from_mpl_figure(fig)
     geometry["space"] = "figure_px"
-    storage.write("artifacts/cache/geometry_px.json", json.dumps(geometry, indent=2).encode())
+    storage.write(
+        "artifacts/cache/geometry_px.json", json.dumps(geometry, indent=2).encode()
+    )
 
     hitmap_png, hitmap_svg = generate_hitmap_from_mpl_figure(fig, dpi)
     if hitmap_png:
@@ -362,7 +451,9 @@ def from_matplotlib(
         storage.write("artifacts/cache/hitmap.svg", hitmap_svg)
 
     manifest = {"dpi": dpi, "formats": ["png", "svg", "pdf"], "size_mm": size_mm}
-    storage.write("artifacts/cache/render_manifest.json", json.dumps(manifest, indent=2).encode())
+    storage.write(
+        "artifacts/cache/render_manifest.json", json.dumps(manifest, indent=2).encode()
+    )
 
     save_bundle_components(
         path,