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

figrecipe/_wrappers/_figure.py

@@ -3,16 +3,17 @@
 """Wrapped Figure that manages recording."""
 
 from pathlib import Path
-from typing import Any, Dict, List, Literal, Optional, Tuple, Union, TYPE_CHECKING
+from typing import TYPE_CHECKING, Any, List, Literal, Optional, Tuple, Union
 
 import matplotlib.pyplot as plt
+import numpy as np
 from matplotlib.figure import Figure
+from numpy.typing import NDArray
 
 from ._axes import RecordingAxes
 
 if TYPE_CHECKING:
-    from .._recorder import Recorder, FigureRecord
-    from .._utils._numpy_io import DataFormat
+    from .._recorder import FigureRecord, Recorder
 
 
 class RecordingFigure:
@@ -79,6 +80,88 @@ class RecordingFigure:
         """Get the figure record."""
         return self._recorder.figure_record
 
+    def _get_style_fontsize(self, key: str, default: float) -> float:
+        """Get fontsize from loaded style."""
+        try:
+            from ..styles._style_loader import _STYLE_CACHE
+
+            if _STYLE_CACHE is not None:
+                fonts = getattr(_STYLE_CACHE, "fonts", None)
+                if fonts is not None:
+                    return getattr(fonts, key, default)
+        except Exception:
+            pass
+        return default
+
+    def suptitle(self, t: str, **kwargs) -> Any:
+        """Set super title for the figure and record it.
+
+        Parameters
+        ----------
+        t : str
+            The super title text.
+        **kwargs
+            Additional arguments passed to matplotlib's suptitle().
+
+        Returns
+        -------
+        Text
+            The matplotlib Text object.
+        """
+        # Auto-apply fontsize from style if not specified
+        if "fontsize" not in kwargs:
+            kwargs["fontsize"] = self._get_style_fontsize("suptitle_pt", 10)
+        # Record the suptitle call
+        self._recorder.figure_record.suptitle = {"text": t, "kwargs": kwargs}
+        # Call the underlying figure's suptitle
+        return self._fig.suptitle(t, **kwargs)
+
+    def supxlabel(self, t: str, **kwargs) -> Any:
+        """Set super x-label for the figure and record it.
+
+        Parameters
+        ----------
+        t : str
+            The super x-label text.
+        **kwargs
+            Additional arguments passed to matplotlib's supxlabel().
+
+        Returns
+        -------
+        Text
+            The matplotlib Text object.
+        """
+        # Auto-apply fontsize from style if not specified
+        if "fontsize" not in kwargs:
+            kwargs["fontsize"] = self._get_style_fontsize("supxlabel_pt", 8)
+        # Record the supxlabel call
+        self._recorder.figure_record.supxlabel = {"text": t, "kwargs": kwargs}
+        # Call the underlying figure's supxlabel
+        return self._fig.supxlabel(t, **kwargs)
+
+    def supylabel(self, t: str, **kwargs) -> Any:
+        """Set super y-label for the figure and record it.
+
+        Parameters
+        ----------
+        t : str
+            The super y-label text.
+        **kwargs
+            Additional arguments passed to matplotlib's supylabel().
+
+        Returns
+        -------
+        Text
+            The matplotlib Text object.
+        """
+        # Auto-apply fontsize from style if not specified
+        if "fontsize" not in kwargs:
+            kwargs["fontsize"] = self._get_style_fontsize("supylabel_pt", 8)
+        # Record the supylabel call
+        self._recorder.figure_record.supylabel = {"text": t, "kwargs": kwargs}
+        # Call the underlying figure's supylabel
+        return self._fig.supylabel(t, **kwargs)
+
     def __getattr__(self, name: str) -> Any:
         """Delegate attribute access to underlying figure."""
         return getattr(self._fig, name)
@@ -88,6 +171,7 @@ class RecordingFigure:
         fname,
         save_recipe: bool = True,
         recipe_format: Literal["csv", "npz", "inline"] = "csv",
+        verbose: bool = True,
         **kwargs,
     ):
         """Save the figure image and optionally the recipe.
@@ -101,6 +185,8 @@ class RecordingFigure:
             Recipe will be saved with same name but .yaml extension.
         recipe_format : str
             Format for data in recipe: 'csv' (default), 'npz', or 'inline'.
+        verbose : bool
+            If True (default), print save status.
         **kwargs
             Passed to matplotlib's savefig().
 
@@ -118,7 +204,7 @@ class RecordingFigure:
         >>> fig.savefig('figure.png', save_recipe=False)  # Image only
         """
         # Handle file-like objects (BytesIO, etc.) - just pass through
-        if hasattr(fname, 'write'):
+        if hasattr(fname, "write"):
             self._fig.savefig(fname, **kwargs)
             return fname
 
@@ -128,8 +214,12 @@ class RecordingFigure:
         if save_recipe:
             recipe_path = fname.with_suffix(".yaml")
             self.save_recipe(recipe_path, include_data=True, data_format=recipe_format)
+            if verbose:
+                print(f"Saved: {fname} + {recipe_path}")
             return fname, recipe_path
 
+        if verbose:
+            print(f"Saved: {fname}")
         return fname
 
     def save_recipe(
@@ -155,7 +245,10 @@ class RecordingFigure:
             Path to saved recipe file.
         """
         from .._serializer import save_recipe
-        return save_recipe(self._recorder.figure_record, path, include_data, data_format)
+
+        return save_recipe(
+            self._recorder.figure_record, path, include_data, data_format
+        )
 
 
 def create_recording_subplots(
@@ -163,7 +256,7 @@ def create_recording_subplots(
     ncols: int = 1,
     recorder: Optional["Recorder"] = None,
     **kwargs,
-) -> Tuple[RecordingFigure, Union[RecordingAxes, List[RecordingAxes]]]:
+) -> Tuple[RecordingFigure, Union[RecordingAxes, NDArray]]:
     """Create a figure with recording-enabled axes.
 
     Parameters
@@ -181,8 +274,8 @@ def create_recording_subplots(
     -------
     fig : RecordingFigure
         Wrapped figure.
-    axes : RecordingAxes or list
-        Wrapped axes (single if 1x1, otherwise 2D array).
+    axes : RecordingAxes or ndarray
+        Wrapped axes (single if 1x1, otherwise numpy array matching matplotlib).
     """
     from .._recorder import Recorder
 
@@ -205,23 +298,27 @@ def create_recording_subplots(
         wrapped_fig = RecordingFigure(fig, recorder, wrapped_ax)
         return wrapped_fig, wrapped_ax
 
-    # Handle 1D or 2D arrays
-    import numpy as np
-    mpl_axes = np.atleast_2d(mpl_axes)
+    # Handle 1D or 2D arrays - reshape to (nrows, ncols) for uniform processing
+    mpl_axes_arr = np.asarray(mpl_axes)
+    if mpl_axes_arr.ndim == 1:
+        mpl_axes_arr = mpl_axes_arr.reshape(nrows, ncols)
 
     wrapped_axes = []
-    for i in range(mpl_axes.shape[0]):
+    for i in range(nrows):
         row = []
-        for j in range(mpl_axes.shape[1]):
-            row.append(RecordingAxes(mpl_axes[i, j], recorder, position=(i, j)))
+        for j in range(ncols):
+            row.append(RecordingAxes(mpl_axes_arr[i, j], recorder, position=(i, j)))
         wrapped_axes.append(row)
 
     wrapped_fig = RecordingFigure(fig, recorder, wrapped_axes)
 
-    # Return in same shape as matplotlib
+    # Return in same shape as matplotlib (numpy arrays for consistency)
     if nrows == 1:
-        return wrapped_fig, wrapped_axes[0]
+        # 1xN -> 1D array of shape (N,)
+        return wrapped_fig, np.array(wrapped_axes[0], dtype=object)
     elif ncols == 1:
-        return wrapped_fig, [row[0] for row in wrapped_axes]
+        # Nx1 -> 1D array of shape (N,)
+        return wrapped_fig, np.array([row[0] for row in wrapped_axes], dtype=object)
     else:
-        return wrapped_fig, wrapped_axes
+        # NxM -> 2D array
+        return wrapped_fig, np.array(wrapped_axes, dtype=object)

figrecipe/plt.py

@@ -9,4 +9,3 @@ Usage:
 """
 
 from .pyplot import *  # noqa: F401, F403
-from .pyplot import __all__

figrecipe/pyplot.py

@@ -34,9 +34,10 @@ Examples
 import matplotlib.pyplot as _plt
 from matplotlib.pyplot import *  # noqa: F401, F403
 
+from . import save as _ps_save
+
 # Import figrecipe functionality
 from . import subplots as _ps_subplots
-from . import save as _ps_save
 from ._wrappers import RecordingFigure
 
 # Override subplots with recording-enabled version

figrecipe/styles/__init__.py

@@ -18,22 +18,21 @@ Usage:
     fig, ax = ps.subplots(**style.to_subplots_kwargs())
 """
 
-from ._style_loader import (
-    load_style,
-    unload_style,
-    get_style,
-    reload_style,
-    list_presets,
-    STYLE,
-    to_subplots_kwargs,
-)
-
 from ._style_applier import (
     apply_style_mm,
     apply_theme_colors,
     check_font,
     list_available_fonts,
 )
+from ._style_loader import (
+    STYLE,
+    get_style,
+    list_presets,
+    load_style,
+    reload_style,
+    to_subplots_kwargs,
+    unload_style,
+)
 
 __all__ = [
     "load_style",