#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""Wrapped Axes that records all plotting calls."""
from typing import TYPE_CHECKING, Any, Dict, Optional, Tuple
import numpy as np
from matplotlib.axes import Axes
from ._axes_diagram import DiagramMixin
from ._axes_methods import RecordingAxesMethods
from ._axes_scatter_labels import ScatterLabelsMixin
from ._axes_scitex import SciTexMixin
from ._axes_style_mixin import AxesStyleMixin
if TYPE_CHECKING:
from .._recorder import Recorder
[docs]
class RecordingAxes(
RecordingAxesMethods,
AxesStyleMixin,
SciTexMixin,
DiagramMixin,
ScatterLabelsMixin,
):
"""Wrapper around matplotlib Axes that records all calls.
This wrapper intercepts calls to plotting methods and records them
for later reproduction.
Parameters
----------
ax : matplotlib.axes.Axes
The underlying matplotlib axes.
recorder : Recorder
The recorder instance to log calls to.
position : tuple
(row, col) position in the figure grid.
Examples
--------
>>> import figrecipe as ps
>>> fig, ax = ps.subplots()
>>> ax.plot([1, 2, 3], [4, 5, 6], color='red', id='my_line')
>>> # The call is recorded automatically
"""
# Internal: Methods whose results can be referenced by other methods
_RESULT_REFERENCEABLE_METHODS = {"contour", "contourf"}
# Internal: Methods that take results from other methods as arguments
_RESULT_REFERENCING_METHODS = {"clabel"}
[docs]
def __init__(
self,
ax: Axes,
recorder: "Recorder",
position: Tuple[int, int] = (0, 0),
):
self._ax = ax
self._recorder = recorder
self._position = position
self._track = True
# Map matplotlib result objects (by id) to their source call_id
self._result_refs: Dict[int, str] = {}
# call_id -> weakrefs ... keyed by the RECORD's identity: {id(record):
# (record, [weakref(artist), ...])}. Read at SAVE time to drop recorded
# calls whose artists the figure no longer holds (card
# figrecipe-recipe-keeps-artists-removed-before-save-20260906); see
# _recorder/_artists.py. Held per-axes, so there is no global state, and
# holding the RECORD in the entry keeps the key valid (no id-reuse).
self._artist_refs: Dict[int, tuple] = {}
@property
def ax(self) -> Axes:
"""Get the underlying matplotlib axes."""
return self._ax
@property
def position(self) -> Tuple[int, int]:
"""Get axes position in grid."""
return self._position
[docs]
def __getattr__(self, name: str) -> Any:
"""Intercept attribute access to wrap methods."""
attr = getattr(self._ax, name)
# Use custom wrappers for methods with special styling
if callable(attr) and name == "bar":
return self._create_bar_wrapper()
# Route boxplot to wrapper that sets patch_artist=True
if callable(attr) and name == "boxplot":
return self._create_boxplot_wrapper()
# Route legend to wrapper that applies frame styling
if callable(attr) and name == "legend":
return self._create_legend_wrapper()
# Route stem to wrapper that handles color kwarg
if callable(attr) and name == "stem":
return self._create_stem_wrapper()
# Route cla() to a wrapper that also clears this axes' recorded calls
# and decorations: the live cla() removes every artist and every
# decoration from the axes, but the records kept claiming them, so a
# replay drew a cleared axes (card
# figrecipe-cla-replay-still-diverges-20260927).
if callable(attr) and name == "cla":
return self._create_cla_wrapper()
# Route add_patch to a wrapper that records a serializable patch spec
# (raw patches are objects that otherwise vanish on replay)
if callable(attr) and name == "add_patch":
from ._axes_patches import build_add_patch_wrapper
return build_add_patch_wrapper(self)
# Route add_line/add_artist/add_collection to wrappers that record a
# serializable artist spec (raw artists otherwise vanish on replay;
# card figrecipe-unrecorded-axes-artist-methods-20261005). Non-Line2D
# artists fail loud at call time; twinx/twiny stay unrouted (raw Axes
# needs its own secondary-axes design, same card).
if callable(attr) and name in (
"add_line",
"add_artist",
"add_collection",
):
from . import _axes_lines
return {
"add_line": _axes_lines.build_add_line_wrapper,
"add_artist": _axes_lines.build_add_artist_wrapper,
"add_collection": _axes_lines.build_add_collection_wrapper,
}[name](self)
# Route inset_axes to a wrapper that records its content as a managed
# sub-panel (raw inset axes are otherwise unrecorded and vanish on replay)
if callable(attr) and name == "inset_axes":
from ._axes_insets import build_inset_axes_wrapper
return build_inset_axes_wrapper(self)
# Route bar_label to a wrapper that freezes each label into a recorded
# annotate (its live BarContainer arg is otherwise un-serializable).
if callable(attr) and name == "bar_label":
from ._axes_barlabel import build_bar_label_wrapper
return build_bar_label_wrapper(self)
# Route secondary_xaxis/secondary_yaxis to a wrapper that records the
# plain-location case and warns when custom transform functions are given.
if callable(attr) and name in ("secondary_xaxis", "secondary_yaxis"):
from ._axes_barlabel import build_secondary_axis_wrapper
return build_secondary_axis_wrapper(self, name)
# If it's a plotting or decoration method, wrap it
if callable(attr) and name in (
self._recorder.PLOTTING_METHODS | self._recorder.DECORATION_METHODS
):
return self._create_recording_wrapper(name, attr)
# For other methods/attributes, return as-is
return attr
[docs]
def embed(self, source, bounds=None, *, ax_key=None, track=True, id=None):
"""Embed a recipe or diagram as a managed sub-panel that round-trips.
``source`` may be a recipe path, image, FigureRecord, diagram recipe,
composed multi-panel recipe, or ``(source, ax_key)``. ``bounds`` is an
axes-fraction ``[x, y, w, h]`` (defaults to the whole axes). Returns the
embedded inset RecordingAxes (or a list for a multi-panel source).
"""
from ._axes_embed import embed_source
return embed_source(self, source, bounds, ax_key=ax_key, track=track, id=id)
[docs]
def __dir__(self):
"""Return list of attributes for tab completion.
Exposes all matplotlib plotting and decoration methods alongside
figrecipe's custom methods and properties.
"""
# Get base attributes (excluding private)
base_attrs = [a for a in super().__dir__() if not a.startswith("_")]
# Add all matplotlib plotting methods
from .._params import DECORATION_METHODS, PLOTTING_METHODS
matplotlib_methods = sorted(PLOTTING_METHODS | DECORATION_METHODS)
# Combine and deduplicate
return sorted(set(base_attrs + matplotlib_methods))
[docs]
def _create_recording_wrapper(self, method_name: str, method: callable):
"""Create a wrapper function that records the call."""
from ._axes_helpers import (
inject_clip_on_from_style,
inject_method_defaults,
record_call_with_color_capture,
)
def wrapper(
*args,
id: Optional[str] = None,
track: bool = True,
stats: Optional[Dict[str, Any]] = None,
**kwargs,
):
from ..styles._internal import resolve_colors_in_kwargs
kwargs = resolve_colors_in_kwargs(kwargs)
kwargs = inject_clip_on_from_style(kwargs, method_name)
kwargs = inject_method_defaults(kwargs, method_name)
result = method(*args, **kwargs)
if self._track and track:
record_kwargs = kwargs.copy()
if stats is not None:
record_kwargs["stats"] = stats
record_args = args
if method_name in ("set_xticks", "set_yticks") and args:
# Read the tick POSITIONS back from the live axis after
# the call instead of recording the caller's raw arg.
# matplotlib happily accepts a range/tuple/generator for
# ``ticks``, none of which the generic arg serializer
# round-trips (a bare ``range(19)`` degrades to the
# literal string ``"range(0, 19)"`` and later fails to
# replay) — the live axis always holds a well-formed
# numeric array, so recording that is both simpler and
# self-consistent with whatever a later
# set_xticklabels() on this axis will see.
axis_letter = "x" if method_name == "set_xticks" else "y"
live_ticks = list(getattr(self._ax, f"get_{axis_letter}ticks")())
record_args = (live_ticks,) + tuple(args[1:])
record_call_with_color_capture(
self._recorder,
self._position,
method_name,
record_args,
record_kwargs,
result,
id,
self._result_refs,
self._RESULT_REFERENCING_METHODS,
self._RESULT_REFERENCEABLE_METHODS,
self._artist_refs,
)
return result
return wrapper
[docs]
def _create_cla_wrapper(self):
"""Create wrapper for cla() that resets the axes' recorded state.
matplotlib's ``Axes.cla()`` resets the axes: every artist it holds is
gone and the axis label/title/ticks are blanked. Two things then went
wrong (card figrecipe-cla-replay-still-diverges-20260927):
* the recorder kept the calls and decorations that made those artists,
so a replay re-drew the cleared axes -- after ``ax.set_xlabel("x");
ax.cla()`` the recipe still carried the label and the replay showed
it. A cleared axes has no recorded state to replay, so its records
are dropped, and the artist registry goes with them (the artists they
noted are gone; a stale weakref must not be read as a live one).
* ``cla()`` rebuilds the tick/axis text artists with matplotlib's
default font, discarding the figrecipe style family applied at axes
creation. The replayed axes (styled fresh) then used the style font
while the live one used the default, and the renders differed over
the tick labels even though every readable state entry matched
(measured MSE 428.51 for a bare draw-then-cla). Re-applying the
recorded style restores the family and the renders match at 0.00.
"""
base_cla = self._ax.cla
def wrapper(*args, **kwargs):
result = base_cla(*args, **kwargs)
if self._track:
ax_record = self._recorder.figure_record.get_or_create_axes(
*self._position
)
ax_record.calls.clear()
ax_record.decorations.clear()
self._artist_refs.clear()
self._result_refs.clear()
# Restore the figrecipe style the fresh tick/axis text artists
# lost in the reset (font family, sizes, tick params).
style = getattr(self._recorder.figure_record, "style", None)
if style:
from ..styles._internal import apply_style_mm
apply_style_mm(self._ax, style)
return result
return wrapper
[docs]
def _create_bar_wrapper(self):
"""Create wrapper for bar() with SCITEX error bar styling."""
from ._axes_plots import bar_plot
def wrapper(
*args,
id: Optional[str] = None,
track: bool = True,
stats: Optional[Dict[str, Any]] = None,
**kwargs,
):
if stats is not None:
kwargs["stats"] = stats
return bar_plot(
self._ax,
args,
kwargs,
self._recorder,
self._position,
track=self._track and track,
call_id=id,
artist_refs=self._artist_refs,
)
return wrapper
[docs]
def _create_boxplot_wrapper(self):
"""Create wrapper for boxplot() with patch_artist=True default."""
from ._boxplot import boxplot_plot
def wrapper(
*args,
id: Optional[str] = None,
track: bool = True,
**kwargs,
):
# Handle positional x argument
x = args[0] if args else kwargs.pop("x", None)
if x is None:
raise ValueError("boxplot requires data argument")
return boxplot_plot(
self._ax,
x,
self._recorder,
self._position,
track=self._track and track,
call_id=id,
**kwargs,
)
return wrapper
[docs]
def _create_stem_wrapper(self):
"""Create wrapper for stem() that accepts color kwarg."""
original_stem = self._ax.stem
def wrapper(
*args,
id: Optional[str] = None,
track: bool = True,
color=None,
**kwargs,
):
# Call original stem
container = original_stem(*args, **kwargs)
# Apply color if provided (stem doesn't accept color kwarg natively)
if color is not None:
import matplotlib.colors as mcolors
color_val = mcolors.to_rgba(color)
container.markerline.set_color(color_val)
container.stemlines.set_color(color_val)
container.baseline.set_color(color_val)
# Record the call with color
if self._track and track:
record_kwargs = kwargs.copy()
# Capture the actual color (either provided or from cycle)
if color is not None:
import matplotlib.colors as mcolors
record_kwargs["color"] = mcolors.to_hex(color)
else:
# Capture from result
try:
import matplotlib.colors as mcolors
c = container.markerline.get_color()
record_kwargs["color"] = mcolors.to_hex(c)
except Exception:
pass
self._recorder.record_call(
ax_position=self._position,
method_name="stem",
args=args,
kwargs=record_kwargs,
call_id=id,
)
return container
return wrapper
[docs]
def _create_legend_wrapper(self):
"""Build the legend() wrapper that handles SCITEX styling +
figrecipe loc extensions + recording. Implementation lives
in `_legend_wrapper.py` so this file stays focused.
"""
from ._legend_wrapper import build_legend_wrapper
return build_legend_wrapper(self)
[docs]
def set_caption(self, caption: str) -> "RecordingAxes":
"""Set panel caption metadata (not rendered, stored in recipe)."""
ax_record = self._recorder.figure_record.get_or_create_axes(*self._position)
ax_record.caption = caption
return self
@property
def panel_caption(self) -> Optional[str]:
"""Get the panel caption metadata."""
ax_record = self._recorder.figure_record.get_or_create_axes(*self._position)
return ax_record.caption
[docs]
def set_stats(self, stats: Dict[str, Any]) -> "RecordingAxes":
"""Set panel-level statistics metadata (not rendered, stored in recipe)."""
ax_record = self._recorder.figure_record.get_or_create_axes(*self._position)
ax_record.stats = stats
return self
@property
def stats(self) -> Optional[Dict[str, Any]]:
"""Get the panel-level statistics metadata."""
ax_record = self._recorder.figure_record.get_or_create_axes(*self._position)
return ax_record.stats
[docs]
def _no_record(self):
"""Context manager to temporarily disable recording (internal)."""
return _NoRecordContext(self)
[docs]
def _record_seaborn_call(
self,
func_name: str,
args: tuple,
kwargs: Dict[str, Any],
data_arrays: Dict[str, np.ndarray],
call_id: Optional[str] = None,
) -> None:
"""Record a seaborn plotting call."""
if not self._track:
return
from ._axes_seaborn import record_seaborn_call
record_seaborn_call(
self._recorder,
self._position,
func_name,
args,
kwargs,
data_arrays,
call_id,
)
# Expose common properties directly
@property
def figure(self):
return self._ax.figure
@property
def xaxis(self):
return self._ax.xaxis
@property
def yaxis(self):
return self._ax.yaxis
# Methods that should not be recorded
[docs]
def get_xlim(self):
return self._ax.get_xlim()
[docs]
def get_ylim(self):
return self._ax.get_ylim()
[docs]
def get_xlabel(self):
return self._ax.get_xlabel()
[docs]
def get_ylabel(self):
return self._ax.get_ylabel()
[docs]
def get_title(self):
return self._ax.get_title()
@property
def caption(self) -> Optional[str]:
"""Get the panel caption metadata."""
ax_record = self._recorder.figure_record.get_or_create_axes(*self._position)
return ax_record.caption
[docs]
def generate_panel_caption(
self, label: Optional[str] = None, style: str = "publication"
) -> str:
"""Generate a caption for this panel from stats metadata."""
from ._caption_generator import generate_panel_caption
return generate_panel_caption(label=label, stats=self.stats, style=style)
class _NoRecordContext:
"""Context manager to temporarily disable recording."""
def __init__(self, axes: RecordingAxes):
self._axes = axes
self._original_track = axes._track
def __enter__(self):
self._axes._track = False
return self
def __exit__(self, exc_type, exc_val, exc_tb):
self._axes._track = self._original_track
return False