figrecipe 0.5.0__py3-none-any.whl → 0.7.4__py3-none-any.whl

figrecipe/_recorder.py

@@ -1,12 +1,15 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
+# Timestamp: "2025-12-23 09:57:28 (ywatanabe)"
+# File: /home/ywatanabe/proj/figrecipe/src/figrecipe/_recorder.py
+
+
 """Core recording functionality for figrecipe."""
 
-from collections import OrderedDict
+import uuid
 from dataclasses import dataclass, field
 from datetime import datetime
 from typing import Any, Dict, List, Optional, Tuple
-import uuid
 
 import matplotlib
 import numpy as np
@@ -34,7 +37,9 @@ class CallRecord:
         }
 
     @classmethod
-    def from_dict(cls, data: Dict[str, Any], ax_position: Tuple[int, int] = (0, 0)) -> "CallRecord":
+    def from_dict(
+        cls, data: Dict[str, Any], ax_position: Tuple[int, int] = (0, 0)
+    ) -> "CallRecord":
         """Create from dictionary."""
         return cls(
             id=data["id"],
@@ -53,6 +58,8 @@ class AxesRecord:
     position: Tuple[int, int]
     calls: List[CallRecord] = field(default_factory=list)
     decorations: List[CallRecord] = field(default_factory=list)
+    # Panel-level caption (e.g., "(A) Description of this panel")
+    caption: Optional[str] = None
 
     def add_call(self, record: CallRecord) -> None:
         """Add a plotting call record."""
@@ -64,10 +71,13 @@ class AxesRecord:
 
     def to_dict(self) -> Dict[str, Any]:
         """Convert to dictionary for serialization."""
-        return {
+        result = {
             "calls": [c.to_dict() for c in self.calls],
             "decorations": [d.to_dict() for d in self.decorations],
         }
+        if self.caption is not None:
+            result["caption"] = self.caption
+        return result
 
 
 @dataclass
@@ -86,6 +96,15 @@ class FigureRecord:
     style: Optional[Dict[str, Any]] = None
     # Constrained layout flag
     constrained_layout: bool = False
+    # Figure-level decorations (suptitle, supxlabel, supylabel)
+    suptitle: Optional[Dict[str, Any]] = None
+    supxlabel: Optional[Dict[str, Any]] = None
+    supylabel: Optional[Dict[str, Any]] = None
+    # Panel labels (A, B, C, D for multi-panel figures)
+    panel_labels: Optional[Dict[str, Any]] = None
+    # Metadata for scientific figures (not rendered, stored in recipe)
+    title_metadata: Optional[str] = None  # Figure title for publication/reference
+    caption: Optional[str] = None  # Figure caption (e.g., "Fig. 1. Description...")
 
     def get_axes_key(self, row: int, col: int) -> str:
         """Get dictionary key for axes at position."""
@@ -120,12 +139,33 @@ class FigureRecord:
         # Add constrained_layout if True
         if self.constrained_layout:
             result["figure"]["constrained_layout"] = True
+        # Add suptitle if set
+        if self.suptitle is not None:
+            result["figure"]["suptitle"] = self.suptitle
+        # Add supxlabel if set
+        if self.supxlabel is not None:
+            result["figure"]["supxlabel"] = self.supxlabel
+        # Add supylabel if set
+        if self.supylabel is not None:
+            result["figure"]["supylabel"] = self.supylabel
+        # Add panel_labels if set
+        if self.panel_labels is not None:
+            result["figure"]["panel_labels"] = self.panel_labels
+        # Add metadata section for scientific figures
+        metadata = {}
+        if self.title_metadata is not None:
+            metadata["title"] = self.title_metadata
+        if self.caption is not None:
+            metadata["caption"] = self.caption
+        if metadata:
+            result["metadata"] = metadata
         return result
 
     @classmethod
     def from_dict(cls, data: Dict[str, Any]) -> "FigureRecord":
         """Create from dictionary."""
         fig_data = data.get("figure", {})
+        metadata = data.get("metadata", {})
         record = cls(
             id=data.get("id", f"fig_{uuid.uuid4().hex[:8]}"),
             created=data.get("created", ""),
@@ -135,6 +175,12 @@ class FigureRecord:
             layout=fig_data.get("layout"),
             style=fig_data.get("style"),
             constrained_layout=fig_data.get("constrained_layout", False),
+            suptitle=fig_data.get("suptitle"),
+            supxlabel=fig_data.get("supxlabel"),
+            supylabel=fig_data.get("supylabel"),
+            panel_labels=fig_data.get("panel_labels"),
+            title_metadata=metadata.get("title"),
+            caption=metadata.get("caption"),
         )
 
         # Reconstruct axes
@@ -146,7 +192,10 @@ class FigureRecord:
             else:
                 row, col = 0, 0
 
-            ax_record = AxesRecord(position=(row, col))
+            ax_record = AxesRecord(
+                position=(row, col),
+                caption=ax_data.get("caption"),
+            )
             for call_data in ax_data.get("calls", []):
                 ax_record.calls.append(CallRecord.from_dict(call_data, (row, col)))
             for dec_data in ax_data.get("decorations", []):
@@ -160,26 +209,7 @@ class FigureRecord:
 class Recorder:
     """Central recorder for tracking matplotlib calls."""
 
-    # Plotting methods that create artists
-    PLOTTING_METHODS = {
-        "plot", "scatter", "bar", "barh", "hist", "hist2d",
-        "boxplot", "violinplot", "pie", "errorbar", "fill",
-        "fill_between", "fill_betweenx", "stackplot", "stem",
-        "step", "imshow", "pcolor", "pcolormesh", "contour",
-        "contourf", "quiver", "barbs", "streamplot", "hexbin",
-        "tripcolor", "triplot", "tricontour", "tricontourf",
-        "eventplot", "stairs", "ecdf", "matshow", "spy",
-        "loglog", "semilogx", "semilogy", "acorr", "xcorr",
-        "specgram", "psd", "csd", "cohere", "angle_spectrum",
-        "magnitude_spectrum", "phase_spectrum",
-    }
-
-    # Decoration methods
-    DECORATION_METHODS = {
-        "set_xlabel", "set_ylabel", "set_title", "set_xlim",
-        "set_ylim", "legend", "grid", "axhline", "axvline",
-        "axhspan", "axvspan", "text", "annotate",
-    }
+    from ._params import DECORATION_METHODS, PLOTTING_METHODS
 
     def __init__(self):
         self._figure_record: Optional[FigureRecord] = None
@@ -270,74 +300,15 @@ class Recorder:
         args: tuple,
         method_name: str,
     ) -> List[Dict[str, Any]]:
-        """Process positional arguments for storage.
+        """Process positional arguments for storage."""
+        from ._recorder_utils import process_args
 
-        Parameters
-        ----------
-        args : tuple
-            Raw positional arguments.
-        method_name : str
-            Name of the method.
-
-        Returns
-        -------
-        list
-            Processed args with name and data.
-        """
-        from ._utils._numpy_io import should_store_inline, to_serializable
-
-        processed = []
-        # Simple arg names based on common patterns
-        arg_names = self._get_arg_names(method_name, len(args))
-
-        for i, (name, value) in enumerate(zip(arg_names, args)):
-            if isinstance(value, np.ndarray):
-                if should_store_inline(value):
-                    processed.append({
-                        "name": name,
-                        "data": to_serializable(value),
-                        "dtype": str(value.dtype),
-                    })
-                else:
-                    # Mark for file storage (will be handled by serializer)
-                    processed.append({
-                        "name": name,
-                        "data": "__FILE__",
-                        "dtype": str(value.dtype),
-                        "_array": value,  # Temporary, removed during serialization
-                    })
-            elif hasattr(value, "values"):  # pandas
-                arr = np.asarray(value)
-                if should_store_inline(arr):
-                    processed.append({
-                        "name": name,
-                        "data": to_serializable(arr),
-                        "dtype": str(arr.dtype),
-                    })
-                else:
-                    processed.append({
-                        "name": name,
-                        "data": "__FILE__",
-                        "dtype": str(arr.dtype),
-                        "_array": arr,
-                    })
-            else:
-                # Scalar or other serializable value
-                try:
-                    processed.append({
-                        "name": name,
-                        "data": value if self._is_serializable(value) else str(value),
-                    })
-                except (TypeError, ValueError):
-                    processed.append({
-                        "name": name,
-                        "data": str(value),
-                    })
-
-        return processed
+        return process_args(
+            args, method_name, self._get_arg_names, self._is_serializable
+        )
 
     def _get_arg_names(self, method_name: str, n_args: int) -> List[str]:
-        """Get argument names for a method.
+        """Get argument names for a method from signatures.
 
         Parameters
         ----------
@@ -351,31 +322,18 @@ class Recorder:
         list
             List of argument names.
         """
-        # Common patterns
-        patterns = {
-            "plot": ["x", "y", "fmt"],
-            "scatter": ["x", "y", "s", "c"],
-            "bar": ["x", "height", "width", "bottom"],
-            "barh": ["y", "width", "height", "left"],
-            "hist": ["x", "bins"],
-            "imshow": ["X"],
-            "contour": ["X", "Y", "Z", "levels"],
-            "contourf": ["X", "Y", "Z", "levels"],
-            "fill_between": ["x", "y1", "y2"],
-            "errorbar": ["x", "y", "yerr", "xerr"],
-            "text": ["x", "y", "s"],
-            "annotate": ["text", "xy", "xytext"],
-        }
+        try:
+            from ._signatures import get_signature
 
-        if method_name in patterns:
-            names = patterns[method_name][:n_args]
+            sig = get_signature(method_name)
+            names = [arg["name"] for arg in sig["args"][:n_args]]
             # Pad with generic names if needed
             while len(names) < n_args:
                 names.append(f"arg{len(names)}")
             return names
-
-        # Default generic names
-        return [f"arg{i}" for i in range(n_args)]
+        except Exception:
+            # Fallback to generic names
+            return [f"arg{i}" for i in range(n_args)]
 
     def _process_kwargs(
         self,
@@ -384,6 +342,8 @@ class Recorder:
     ) -> Dict[str, Any]:
         """Process keyword arguments for storage.
 
+        Only stores non-default kwargs to keep recipes minimal.
+
         Parameters
         ----------
         kwargs : dict
@@ -396,6 +356,15 @@ class Recorder:
         dict
             Processed kwargs (non-default only).
         """
+        # Get defaults from signature
+        defaults = {}
+        try:
+            from ._signatures import get_defaults
+
+            defaults = get_defaults(method_name)
+        except Exception:
+            pass
+
         # Remove internal keys
         skip_keys = {"id", "track", "_array"}
         processed = {}
@@ -404,6 +373,16 @@ class Recorder:
             if key in skip_keys:
                 continue
 
+            # Skip if value matches default
+            if key in defaults:
+                default_val = defaults[key]
+                # Compare values (handle None specially)
+                if default_val is not None and value == default_val:
+                    continue
+                # Also skip if both are None
+                if default_val is None and value is None:
+                    continue
+
             if self._is_serializable(value):
                 processed[key] = value
             elif isinstance(value, np.ndarray):
@@ -433,3 +412,6 @@ class Recorder:
                 for k, v in value.items()
             )
         return False
+
+
+# EOF

figrecipe/_recorder_utils.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Utilities for recorder argument processing."""
+
+from typing import Any, Dict, List
+
+import numpy as np
+
+
+def process_args(
+    args: tuple,
+    method_name: str,
+    get_arg_names_func,
+    is_serializable_func,
+) -> List[Dict[str, Any]]:
+    """Process positional arguments for storage.
+
+    Parameters
+    ----------
+    args : tuple
+        Raw positional arguments.
+    method_name : str
+        Name of the method.
+    get_arg_names_func : callable
+        Function to get argument names.
+    is_serializable_func : callable
+        Function to check serializability.
+
+    Returns
+    -------
+    list
+        Processed args with name and data.
+    """
+    from ._utils._numpy_io import should_store_inline, to_serializable
+
+    processed = []
+    arg_names = get_arg_names_func(method_name, len(args))
+
+    for name, value in zip(arg_names, args):
+        processed_arg = _process_single_arg(
+            name, value, should_store_inline, to_serializable, is_serializable_func
+        )
+        processed.append(processed_arg)
+
+    return processed
+
+
+def _process_single_arg(
+    name: str,
+    value: Any,
+    should_store_inline,
+    to_serializable,
+    is_serializable_func,
+) -> Dict[str, Any]:
+    """Process a single argument value."""
+    # Handle result references (e.g., ContourSet for clabel)
+    if isinstance(value, dict) and "__ref__" in value:
+        return {"name": name, "data": {"__ref__": value["__ref__"]}}
+
+    if isinstance(value, np.ndarray):
+        return _process_ndarray(name, value, should_store_inline, to_serializable)
+
+    if hasattr(value, "values"):  # pandas
+        arr = np.asarray(value)
+        return _process_ndarray(name, arr, should_store_inline, to_serializable)
+
+    if (
+        isinstance(value, (list, tuple))
+        and len(value) > 0
+        and isinstance(value[0], np.ndarray)
+    ):
+        # List of arrays (e.g., boxplot, violinplot data)
+        return _process_array_list(name, value, to_serializable)
+
+    # Scalar or other serializable value
+    return _process_scalar(name, value, is_serializable_func)
+
+
+def _process_ndarray(
+    name: str, value: np.ndarray, should_store_inline, to_serializable
+) -> Dict[str, Any]:
+    """Process numpy array argument."""
+    if should_store_inline(value):
+        return {
+            "name": name,
+            "data": to_serializable(value),
+            "dtype": str(value.dtype),
+        }
+    else:
+        # Mark for file storage (will be handled by serializer)
+        return {
+            "name": name,
+            "data": "__FILE__",
+            "dtype": str(value.dtype),
+            "_array": value,  # Temporary, removed during serialization
+        }
+
+
+def _process_array_list(name: str, value: list, to_serializable) -> Dict[str, Any]:
+    """Process list of arrays argument."""
+    arrays_data = [to_serializable(arr) for arr in value]
+    dtypes = [str(arr.dtype) for arr in value]
+    return {
+        "name": name,
+        "data": arrays_data,
+        "dtype": (dtypes[0] if len(set(dtypes)) == 1 else dtypes),
+        "_is_array_list": True,
+    }
+
+
+def _process_scalar(name: str, value: Any, is_serializable_func) -> Dict[str, Any]:
+    """Process scalar or other value."""
+    try:
+        return {
+            "name": name,
+            "data": value if is_serializable_func(value) else str(value),
+        }
+    except (TypeError, ValueError):
+        return {"name": name, "data": str(value)}
+
+
+__all__ = ["process_args"]
+
+# EOF

figrecipe/_reproducer/__init__.py

@@ -0,0 +1,18 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Figure reproduction module.
+
+This module provides functionality to reproduce figures from recipe files.
+The public API exposes three main functions:
+- reproduce: Reproduce a figure from a recipe file
+- reproduce_from_record: Reproduce a figure from a FigureRecord object
+- get_recipe_info: Get information about a recipe without reproducing it
+"""
+
+from ._core import get_recipe_info, reproduce, reproduce_from_record
+
+__all__ = [
+    "reproduce",
+    "reproduce_from_record",
+    "get_recipe_info",
+]