figrecipe 0.5.0__py3-none-any.whl

figrecipe/_wrappers/_figure.py

@@ -0,0 +1,227 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Wrapped Figure that manages recording."""
+
+from pathlib import Path
+from typing import Any, Dict, List, Literal, Optional, Tuple, Union, TYPE_CHECKING
+
+import matplotlib.pyplot as plt
+from matplotlib.figure import Figure
+
+from ._axes import RecordingAxes
+
+if TYPE_CHECKING:
+    from .._recorder import Recorder, FigureRecord
+    from .._utils._numpy_io import DataFormat
+
+
+class RecordingFigure:
+    """Wrapper around matplotlib Figure that manages recording.
+
+    Parameters
+    ----------
+    fig : matplotlib.figure.Figure
+        The underlying matplotlib figure.
+    recorder : Recorder
+        The recorder instance.
+    axes : list of RecordingAxes
+        Wrapped axes objects.
+
+    Examples
+    --------
+    >>> import figrecipe as ps
+    >>> fig, ax = ps.subplots()
+    >>> ax.plot([1, 2, 3], [4, 5, 6])
+    >>> ps.save(fig, "my_figure.yaml")
+    """
+
+    def __init__(
+        self,
+        fig: Figure,
+        recorder: "Recorder",
+        axes: Union[RecordingAxes, List[RecordingAxes]],
+    ):
+        self._fig = fig
+        self._recorder = recorder
+
+        # Normalize axes to list
+        if isinstance(axes, RecordingAxes):
+            self._axes = [[axes]]
+        elif isinstance(axes, list):
+            if axes and isinstance(axes[0], list):
+                self._axes = axes
+            else:
+                self._axes = [axes]
+        else:
+            self._axes = [[axes]]
+
+    @property
+    def fig(self) -> Figure:
+        """Get the underlying matplotlib figure."""
+        return self._fig
+
+    @property
+    def axes(self) -> List[List[RecordingAxes]]:
+        """Get axes as 2D array."""
+        return self._axes
+
+    @property
+    def flat(self) -> List[RecordingAxes]:
+        """Get flattened list of all axes."""
+        result = []
+        for row in self._axes:
+            for ax in row:
+                result.append(ax)
+        return result
+
+    @property
+    def record(self) -> "FigureRecord":
+        """Get the figure record."""
+        return self._recorder.figure_record
+
+    def __getattr__(self, name: str) -> Any:
+        """Delegate attribute access to underlying figure."""
+        return getattr(self._fig, name)
+
+    def savefig(
+        self,
+        fname,
+        save_recipe: bool = True,
+        recipe_format: Literal["csv", "npz", "inline"] = "csv",
+        **kwargs,
+    ):
+        """Save the figure image and optionally the recipe.
+
+        Parameters
+        ----------
+        fname : str or Path
+            Output path for the image file.
+        save_recipe : bool
+            If True (default), also save a YAML recipe alongside the image.
+            Recipe will be saved with same name but .yaml extension.
+        recipe_format : str
+            Format for data in recipe: 'csv' (default), 'npz', or 'inline'.
+        **kwargs
+            Passed to matplotlib's savefig().
+
+        Returns
+        -------
+        Path or tuple
+            If save_recipe=False: image path.
+            If save_recipe=True: (image_path, recipe_path) tuple.
+
+        Examples
+        --------
+        >>> fig, ax = ps.subplots()
+        >>> ax.plot(x, y, id='data')
+        >>> fig.savefig('figure.png')  # Saves both figure.png and figure.yaml
+        >>> fig.savefig('figure.png', save_recipe=False)  # Image only
+        """
+        # Handle file-like objects (BytesIO, etc.) - just pass through
+        if hasattr(fname, 'write'):
+            self._fig.savefig(fname, **kwargs)
+            return fname
+
+        fname = Path(fname)
+        self._fig.savefig(fname, **kwargs)
+
+        if save_recipe:
+            recipe_path = fname.with_suffix(".yaml")
+            self.save_recipe(recipe_path, include_data=True, data_format=recipe_format)
+            return fname, recipe_path
+
+        return fname
+
+    def save_recipe(
+        self,
+        path: Union[str, Path],
+        include_data: bool = True,
+        data_format: Literal["csv", "npz", "inline"] = "csv",
+    ) -> Path:
+        """Save the recording recipe to YAML.
+
+        Parameters
+        ----------
+        path : str or Path
+            Output path for the recipe file.
+        include_data : bool
+            If True, save array data alongside recipe.
+        data_format : str
+            Format for data files: 'csv' (default), 'npz', or 'inline'.
+
+        Returns
+        -------
+        Path
+            Path to saved recipe file.
+        """
+        from .._serializer import save_recipe
+        return save_recipe(self._recorder.figure_record, path, include_data, data_format)
+
+
+def create_recording_subplots(
+    nrows: int = 1,
+    ncols: int = 1,
+    recorder: Optional["Recorder"] = None,
+    **kwargs,
+) -> Tuple[RecordingFigure, Union[RecordingAxes, List[RecordingAxes]]]:
+    """Create a figure with recording-enabled axes.
+
+    Parameters
+    ----------
+    nrows : int
+        Number of rows.
+    ncols : int
+        Number of columns.
+    recorder : Recorder, optional
+        Recorder instance. Created if not provided.
+    **kwargs
+        Passed to plt.subplots().
+
+    Returns
+    -------
+    fig : RecordingFigure
+        Wrapped figure.
+    axes : RecordingAxes or list
+        Wrapped axes (single if 1x1, otherwise 2D array).
+    """
+    from .._recorder import Recorder
+
+    if recorder is None:
+        recorder = Recorder()
+
+    # Create matplotlib figure
+    fig, mpl_axes = plt.subplots(nrows, ncols, **kwargs)
+
+    # Get figsize and dpi
+    figsize = kwargs.get("figsize", fig.get_size_inches())
+    dpi = kwargs.get("dpi", fig.dpi)
+
+    # Start recording
+    recorder.start_figure(figsize=tuple(figsize), dpi=int(dpi))
+
+    # Wrap axes
+    if nrows == 1 and ncols == 1:
+        wrapped_ax = RecordingAxes(mpl_axes, recorder, position=(0, 0))
+        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)
+
+    wrapped_axes = []
+    for i in range(mpl_axes.shape[0]):
+        row = []
+        for j in range(mpl_axes.shape[1]):
+            row.append(RecordingAxes(mpl_axes[i, j], recorder, position=(i, j)))
+        wrapped_axes.append(row)
+
+    wrapped_fig = RecordingFigure(fig, recorder, wrapped_axes)
+
+    # Return in same shape as matplotlib
+    if nrows == 1:
+        return wrapped_fig, wrapped_axes[0]
+    elif ncols == 1:
+        return wrapped_fig, [row[0] for row in wrapped_axes]
+    else:
+        return wrapped_fig, wrapped_axes

figrecipe/plt.py

@@ -0,0 +1,12 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Alias for figrecipe.pyplot - drop-in replacement for matplotlib.pyplot.
+
+Usage:
+    import figrecipe.plt as plt  # Short form
+    # or
+    import figrecipe.pyplot as plt  # Full form
+"""
+
+from .pyplot import *  # noqa: F401, F403
+from .pyplot import __all__

figrecipe/pyplot.py

@@ -0,0 +1,264 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Drop-in replacement for matplotlib.pyplot with recording capabilities.
+
+This module provides a convenient way to use figrecipe as a direct replacement
+for matplotlib.pyplot. Simply change your import statement:
+
+    # Before (standard matplotlib)
+    import matplotlib.pyplot as plt
+
+    # After (figrecipe with recording)
+    import figrecipe.pyplot as plt
+
+All your existing code will work unchanged, but figures created with
+plt.subplots() will automatically have recording capabilities.
+
+Examples
+--------
+>>> import figrecipe.pyplot as plt
+>>> import numpy as np
+>>>
+>>> x = np.linspace(0, 10, 100)
+>>> y = np.sin(x)
+>>>
+>>> fig, ax = plt.subplots()  # Recording-enabled
+>>> ax.plot(x, y, color='red', id='sine_wave')
+>>> fig.save_recipe('my_figure.yaml')  # Save as recipe
+>>>
+>>> # All other pyplot functions work as usual
+>>> plt.show()
+>>> plt.savefig('output.png')
+"""
+
+import matplotlib.pyplot as _plt
+from matplotlib.pyplot import *  # noqa: F401, F403
+
+# 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
+subplots = _ps_subplots
+
+
+def figure(*args, **kwargs):
+    """Create a new figure with optional recording support.
+
+    This is a pass-through to matplotlib.pyplot.figure().
+    For recording support, use subplots() instead.
+
+    Parameters
+    ----------
+    *args, **kwargs
+        Arguments passed to matplotlib.pyplot.figure().
+
+    Returns
+    -------
+    matplotlib.figure.Figure
+        The created figure.
+    """
+    return _plt.figure(*args, **kwargs)
+
+
+def save(fig, path, **kwargs):
+    """Save a figure (recipe for RecordingFigure, or standard save).
+
+    Parameters
+    ----------
+    fig : RecordingFigure or Figure
+        Figure to save. If RecordingFigure, saves as recipe.
+        Otherwise, saves as image using savefig().
+    path : str or Path
+        Output path. Use .yaml for recipe format.
+    **kwargs
+        Additional arguments for save.
+
+    Returns
+    -------
+    Path or tuple
+        Saved path (and ValidationResult if validate=True).
+    """
+    if isinstance(fig, RecordingFigure):
+        return _ps_save(fig, path, **kwargs)
+    else:
+        fig.savefig(path, **kwargs)
+        return path
+
+
+# Expose commonly used functions explicitly for IDE support
+show = _plt.show
+savefig = _plt.savefig
+
+
+def close(fig=None):
+    """Close a figure window.
+
+    Parameters
+    ----------
+    fig : None, int, str, Figure, or RecordingFigure
+        The figure to close. See matplotlib.pyplot.close() for details.
+        RecordingFigure is automatically unwrapped to the underlying Figure.
+    """
+    if isinstance(fig, RecordingFigure):
+        _plt.close(fig.fig)
+    else:
+        _plt.close(fig)
+
+
+clf = _plt.clf
+cla = _plt.cla
+gcf = _plt.gcf
+gca = _plt.gca
+subplot = _plt.subplot
+tight_layout = _plt.tight_layout
+suptitle = _plt.suptitle
+xlabel = _plt.xlabel
+ylabel = _plt.ylabel
+title = _plt.title
+legend = _plt.legend
+xlim = _plt.xlim
+ylim = _plt.ylim
+grid = _plt.grid
+plot = _plt.plot
+scatter = _plt.scatter
+bar = _plt.bar
+hist = _plt.hist
+imshow = _plt.imshow
+contour = _plt.contour
+contourf = _plt.contourf
+colorbar = _plt.colorbar
+axhline = _plt.axhline
+axvline = _plt.axvline
+text = _plt.text
+annotate = _plt.annotate
+fill_between = _plt.fill_between
+errorbar = _plt.errorbar
+boxplot = _plt.boxplot
+violinplot = _plt.violinplot
+pie = _plt.pie
+stem = _plt.stem
+step = _plt.step
+stackplot = _plt.stackplot
+streamplot = _plt.streamplot
+quiver = _plt.quiver
+barbs = _plt.barbs
+hexbin = _plt.hexbin
+pcolormesh = _plt.pcolormesh
+tripcolor = _plt.tripcolor
+tricontour = _plt.tricontour
+tricontourf = _plt.tricontourf
+spy = _plt.spy
+matshow = _plt.matshow
+specgram = _plt.specgram
+psd = _plt.psd
+csd = _plt.csd
+cohere = _plt.cohere
+magnitude_spectrum = _plt.magnitude_spectrum
+angle_spectrum = _plt.angle_spectrum
+phase_spectrum = _plt.phase_spectrum
+xcorr = _plt.xcorr
+acorr = _plt.acorr
+semilogy = _plt.semilogy
+semilogx = _plt.semilogx
+loglog = _plt.loglog
+polar = _plt.polar
+subplot2grid = _plt.subplot2grid
+subplot_mosaic = _plt.subplot_mosaic
+subplots_adjust = _plt.subplots_adjust
+rc = _plt.rc
+rcdefaults = _plt.rcdefaults
+rcParams = _plt.rcParams
+style = _plt.style
+cm = _plt.cm
+get_cmap = _plt.get_cmap
+colormaps = _plt.colormaps
+
+
+__all__ = [
+    # Core functions (recording-enabled)
+    "subplots",
+    "figure",
+    "save",
+    # Display
+    "show",
+    "savefig",
+    "close",
+    "clf",
+    "cla",
+    # Getters
+    "gcf",
+    "gca",
+    # Layout
+    "subplot",
+    "subplot2grid",
+    "subplot_mosaic",
+    "subplots_adjust",
+    "tight_layout",
+    # Labels and titles
+    "suptitle",
+    "xlabel",
+    "ylabel",
+    "title",
+    "legend",
+    # Limits
+    "xlim",
+    "ylim",
+    # Grid
+    "grid",
+    # Plot types
+    "plot",
+    "scatter",
+    "bar",
+    "hist",
+    "imshow",
+    "contour",
+    "contourf",
+    "colorbar",
+    "axhline",
+    "axvline",
+    "text",
+    "annotate",
+    "fill_between",
+    "errorbar",
+    "boxplot",
+    "violinplot",
+    "pie",
+    "stem",
+    "step",
+    "stackplot",
+    "streamplot",
+    "quiver",
+    "barbs",
+    "hexbin",
+    "pcolormesh",
+    "tripcolor",
+    "tricontour",
+    "tricontourf",
+    "spy",
+    "matshow",
+    "specgram",
+    "psd",
+    "csd",
+    "cohere",
+    "magnitude_spectrum",
+    "angle_spectrum",
+    "phase_spectrum",
+    "xcorr",
+    "acorr",
+    # Log scale
+    "semilogy",
+    "semilogx",
+    "loglog",
+    "polar",
+    # Configuration
+    "rc",
+    "rcdefaults",
+    "rcParams",
+    "style",
+    # Colormaps
+    "cm",
+    "get_cmap",
+    "colormaps",
+]

figrecipe/styles/__init__.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Style management for figrecipe.
+
+Provides style loading, application, and management for publication-quality figures.
+
+Usage:
+    from figrecipe.styles import load_style, STYLE
+
+    # Load default style
+    style = load_style()
+
+    # Access style parameters
+    print(style.axes.width_mm)
+    print(style.fonts.axis_label_pt)
+
+    # Use with subplots
+    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,
+)
+
+__all__ = [
+    "load_style",
+    "unload_style",
+    "get_style",
+    "reload_style",
+    "list_presets",
+    "STYLE",
+    "to_subplots_kwargs",
+    "apply_style_mm",
+    "apply_theme_colors",
+    "check_font",
+    "list_available_fonts",
+]