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

figrecipe/__main__.py

@@ -0,0 +1,12 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""figrecipe CLI entry point.
+
+Allows running figrecipe as a module:
+    python -m figrecipe <command>
+"""
+
+from ._cli import main
+
+if __name__ == "__main__":
+    main()

figrecipe/_api/__init__.py

@@ -0,0 +1,48 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""API helper modules for figrecipe.
+
+This package contains helper functions extracted from the main __init__.py
+to reduce file size and improve maintainability.
+"""
+
+from ._extract import DECORATION_FUNCS, extract_call_data, to_array
+from ._panel import calculate_panel_position, get_panel_label_fontsize
+from ._save import (
+    IMAGE_EXTENSIONS,
+    YAML_EXTENSIONS,
+    get_save_dpi,
+    get_save_transparency,
+    resolve_save_paths,
+)
+from ._subplots import (
+    _apply_mm_layout_to_figure,
+    _apply_style_to_axes,
+    _calculate_mm_layout,
+    _check_mm_layout,
+    _get_mm_value,
+)
+
+__all__ = [
+    # Subplots helpers
+    "_get_mm_value",
+    "_check_mm_layout",
+    "_calculate_mm_layout",
+    "_apply_mm_layout_to_figure",
+    "_apply_style_to_axes",
+    # Save helpers
+    "IMAGE_EXTENSIONS",
+    "YAML_EXTENSIONS",
+    "resolve_save_paths",
+    "get_save_dpi",
+    "get_save_transparency",
+    # Extract helpers
+    "DECORATION_FUNCS",
+    "to_array",
+    "extract_call_data",
+    # Panel helpers
+    "get_panel_label_fontsize",
+    "calculate_panel_position",
+]
+
+# EOF

figrecipe/_api/_extract.py

@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Data extraction helpers for the public API."""
+
+from typing import Any, Dict, Set
+
+import numpy as np
+
+# Decoration functions to skip when extracting data
+DECORATION_FUNCS: Set[str] = {
+    "set_xlabel",
+    "set_ylabel",
+    "set_title",
+    "set_xlim",
+    "set_ylim",
+    "legend",
+    "grid",
+    "axhline",
+    "axvline",
+    "text",
+    "annotate",
+}
+
+
+def to_array(data: Any) -> np.ndarray:
+    """Convert data to numpy array, handling YAML types.
+
+    Parameters
+    ----------
+    data : any
+        Data to convert.
+
+    Returns
+    -------
+    np.ndarray
+        Converted numpy array.
+    """
+    # Handle dict with 'data' key (serialized array format)
+    if isinstance(data, dict) or (hasattr(data, "keys") and "data" in data):
+        return np.array(data["data"])
+    if hasattr(data, "tolist"):  # Already array-like
+        return np.array(data)
+    return np.array(
+        list(data) if hasattr(data, "__iter__") and not isinstance(data, str) else data
+    )
+
+
+def extract_call_data(call) -> Dict[str, Any]:
+    """Extract data arrays from a single call record.
+
+    Parameters
+    ----------
+    call : CallRecord
+        The call to extract data from.
+
+    Returns
+    -------
+    dict
+        Dictionary with extracted data arrays.
+    """
+    call_data = {}
+
+    # Extract positional arguments based on function type
+    if call.function in ("plot", "scatter", "fill_between"):
+        if len(call.args) >= 1:
+            call_data["x"] = to_array(call.args[0])
+        if len(call.args) >= 2:
+            call_data["y"] = to_array(call.args[1])
+
+    elif call.function == "bar":
+        if len(call.args) >= 1:
+            call_data["x"] = to_array(call.args[0])
+        if len(call.args) >= 2:
+            call_data["height"] = to_array(call.args[1])
+
+    elif call.function == "hist":
+        if len(call.args) >= 1:
+            call_data["x"] = to_array(call.args[0])
+
+    elif call.function == "errorbar":
+        if len(call.args) >= 1:
+            call_data["x"] = to_array(call.args[0])
+        if len(call.args) >= 2:
+            call_data["y"] = to_array(call.args[1])
+
+    # Extract relevant kwargs
+    for key in ("c", "s", "yerr", "xerr", "weights", "bins"):
+        if key in call.kwargs:
+            val = call.kwargs[key]
+            if (
+                isinstance(val, (list, tuple))
+                or hasattr(val, "__iter__")
+                and not isinstance(val, str)
+            ):
+                call_data[key] = to_array(val)
+            else:
+                call_data[key] = val
+
+    return call_data
+
+
+__all__ = [
+    "DECORATION_FUNCS",
+    "to_array",
+    "extract_call_data",
+]
+
+# EOF

figrecipe/_api/_notebook.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Notebook utilities for figrecipe.
+
+Provides SVG rendering for Jupyter notebooks.
+"""
+
+__all__ = [
+    "enable_svg",
+]
+
+# Notebook display format flag (set once per session)
+_notebook_format_set = False
+
+
+def _enable_notebook_svg():
+    """Enable SVG format for Jupyter notebook display.
+
+    This provides crisp vector graphics at any zoom level.
+    Called automatically when load_style() or subplots() is used.
+    """
+    global _notebook_format_set
+    if _notebook_format_set:
+        return
+
+    try:
+        # Method 1: matplotlib_inline (IPython 7.0+, JupyterLab)
+        from matplotlib_inline.backend_inline import set_matplotlib_formats
+
+        set_matplotlib_formats("svg")
+        _notebook_format_set = True
+    except (ImportError, Exception):
+        try:
+            # Method 2: IPython config (older IPython)
+            from IPython import get_ipython
+
+            ipython = get_ipython()
+            if ipython is not None and hasattr(ipython, "kernel"):
+                # Only run in actual Jupyter kernel, not IPython console
+                ipython.run_line_magic(
+                    "config", "InlineBackend.figure_formats = ['svg']"
+                )
+                _notebook_format_set = True
+        except Exception:
+            pass  # Not in Jupyter environment or method not available
+
+
+def enable_svg():
+    """Manually enable SVG format for Jupyter notebook display.
+
+    Call this if figures appear pixelated in notebooks.
+
+    Examples
+    --------
+    >>> import figrecipe as fr
+    >>> fr.enable_svg()  # Enable SVG rendering
+    >>> fig, ax = fr.subplots()  # Now renders as crisp SVG
+    """
+    global _notebook_format_set
+    _notebook_format_set = False  # Force re-application
+    _enable_notebook_svg()

figrecipe/_api/_panel.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Panel label helper for the public API."""
+
+from typing import Optional, Tuple
+
+
+def get_panel_label_fontsize(explicit_fontsize: Optional[float] = None) -> float:
+    """Get fontsize for panel labels from style or default."""
+    if explicit_fontsize is not None:
+        return explicit_fontsize
+
+    try:
+        from ..styles._style_loader import _STYLE_CACHE
+
+        if _STYLE_CACHE is not None:
+            return getattr(getattr(_STYLE_CACHE, "fonts", None), "panel_label_pt", 10)
+    except Exception:
+        pass
+    return 10
+
+
+def calculate_panel_position(
+    loc: str,
+    offset: Tuple[float, float],
+) -> Tuple[float, float]:
+    """Calculate x, y position based on location and offset."""
+    if loc == "upper left":
+        x, y = offset
+    elif loc == "upper right":
+        x, y = 1.0 + abs(offset[0]), offset[1]
+    elif loc == "lower left":
+        x, y = offset[0], -abs(offset[1]) + 1.0
+    elif loc == "lower right":
+        x, y = 1.0 + abs(offset[0]), -abs(offset[1]) + 1.0
+    else:
+        x, y = offset
+    return x, y
+
+
+def panel_label(
+    ax,
+    label: str,
+    loc: str = "upper left",
+    fontsize: Optional[float] = None,
+    fontweight: str = "bold",
+    offset: Tuple[float, float] = (-0.1, 1.05),
+    **kwargs,
+):
+    """Add a panel label (A, B, C, ...) to an axes.
+
+    Parameters
+    ----------
+    ax : Axes or RecordingAxes
+        The axes to label.
+    label : str
+        The label text (e.g., 'A', 'B', 'a)', '(1)').
+    loc : str, optional
+        Label location: 'upper left', 'upper right', etc.
+    fontsize : float, optional
+        Font size in points.
+    fontweight : str, optional
+        Font weight (default: 'bold').
+    offset : tuple of float, optional
+        (x, y) offset in axes coordinates.
+    **kwargs
+        Additional arguments passed to ax.text().
+
+    Returns
+    -------
+    Text
+        The matplotlib Text object.
+    """
+    import matplotlib.pyplot as mpl_plt
+
+    fontsize = get_panel_label_fontsize(fontsize)
+    x, y = calculate_panel_position(loc, offset)
+
+    default_color = mpl_plt.rcParams.get("text.color", "black")
+
+    text_kwargs = {
+        "fontsize": fontsize,
+        "fontweight": fontweight,
+        "color": default_color,
+        "transform": "axes",
+        "va": "bottom",
+        "ha": "right" if "right" in loc else "left",
+    }
+    text_kwargs.update(kwargs)
+
+    mpl_ax = ax._ax if hasattr(ax, "_ax") else ax
+
+    render_kwargs = text_kwargs.copy()
+    render_kwargs["transform"] = mpl_ax.transAxes
+
+    if hasattr(ax, "_recorder") and hasattr(ax, "_position"):
+        ax._recorder.record_call(
+            ax_position=ax._position,
+            method_name="text",
+            args=(x, y, label),
+            kwargs=text_kwargs,
+        )
+
+    return mpl_ax.text(x, y, label, **render_kwargs)
+
+
+__all__ = [
+    "get_panel_label_fontsize",
+    "calculate_panel_position",
+    "panel_label",
+]
+
+# EOF

figrecipe/_api/_save.py

@@ -0,0 +1,287 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Save function helpers for the public API."""
+
+import shutil
+import tempfile
+import zipfile
+from pathlib import Path
+from typing import Optional, Tuple
+
+# Image extensions supported for saving
+IMAGE_EXTENSIONS = {
+    ".png",
+    ".pdf",
+    ".svg",
+    ".jpg",
+    ".jpeg",
+    ".eps",
+    ".tiff",
+    ".tif",
+}
+YAML_EXTENSIONS = {".yaml", ".yml"}
+BUNDLE_RECIPE_NAME = "recipe.yaml"
+
+
+def resolve_save_paths(
+    path: Path,
+    image_format: Optional[str] = None,
+) -> Tuple[Path, Path, str]:
+    """Resolve image and YAML paths from the provided path.
+
+    Parameters
+    ----------
+    path : Path
+        User-provided output path.
+    image_format : str, optional
+        Explicit image format when path is YAML.
+
+    Returns
+    -------
+    tuple
+        (image_path, yaml_path, img_format)
+    """
+    suffix_lower = path.suffix.lower()
+
+    if suffix_lower in IMAGE_EXTENSIONS:
+        # User provided image path
+        image_path = path
+        yaml_path = path.with_suffix(".yaml")
+        img_format = suffix_lower[1:]  # Remove leading dot
+    elif suffix_lower in YAML_EXTENSIONS:
+        # User provided YAML path
+        yaml_path = path
+        img_format = _get_default_image_format(image_format)
+        image_path = path.with_suffix(f".{img_format}")
+    else:
+        # Unknown extension - treat as base name, add both extensions
+        yaml_path = path.with_suffix(".yaml")
+        img_format = _get_default_image_format(image_format)
+        image_path = path.with_suffix(f".{img_format}")
+
+    return image_path, yaml_path, img_format
+
+
+def _get_default_image_format(explicit_format: Optional[str] = None) -> str:
+    """Get default image format from style or fallback to png."""
+    if explicit_format is not None:
+        return explicit_format.lower().lstrip(".")
+
+    # Check global style for preferred format
+    from ..styles._style_loader import _STYLE_CACHE
+
+    if _STYLE_CACHE is not None:
+        try:
+            return _STYLE_CACHE.output.format.lower()
+        except (KeyError, AttributeError):
+            pass
+    return "png"
+
+
+def get_save_dpi(explicit_dpi: Optional[int] = None) -> int:
+    """Get DPI for saving, using style default if not specified."""
+    if explicit_dpi is not None:
+        return explicit_dpi
+
+    from ..styles._style_loader import _STYLE_CACHE
+
+    if _STYLE_CACHE is not None:
+        try:
+            return _STYLE_CACHE.output.dpi
+        except (KeyError, AttributeError):
+            pass
+    return 300
+
+
+def get_save_transparency() -> bool:
+    """Get transparency setting from style."""
+    from ..styles._style_loader import _STYLE_CACHE
+
+    if _STYLE_CACHE is not None:
+        try:
+            return _STYLE_CACHE.output.transparent
+        except (KeyError, AttributeError):
+            pass
+    return False
+
+
+def _is_bundle_path(path: Path) -> bool:
+    """Check if path represents a bundle (directory or ZIP)."""
+    suffix = path.suffix.lower()
+    # ZIP file
+    if suffix == ".zip":
+        return True
+    # Existing directory
+    if path.is_dir():
+        return True
+    # Path ending with / (explicit directory)
+    if str(path).endswith("/"):
+        return True
+    # No extension and doesn't look like a file
+    if not suffix and not path.exists():
+        return True
+    return False
+
+
+def _save_as_bundle(
+    fig,
+    path: Path,
+    include_data: bool,
+    data_format: str,
+    dpi: int,
+    transparent: bool,
+    image_format: str,
+    verbose: bool,
+) -> Tuple[Path, Path]:
+    """Save figure as a bundle (directory or ZIP)."""
+    suffix = path.suffix.lower()
+    is_zip = suffix == ".zip"
+
+    # Create temporary directory for bundle contents
+    with tempfile.TemporaryDirectory() as tmpdir:
+        tmpdir = Path(tmpdir)
+
+        # Determine image format
+        img_format = image_format or _get_default_image_format()
+        image_name = f"figure.{img_format}"
+
+        # Save image
+        image_path = tmpdir / image_name
+        fig.fig.savefig(
+            image_path, dpi=dpi, bbox_inches="tight", transparent=transparent
+        )
+
+        # Save recipe
+        yaml_path = tmpdir / BUNDLE_RECIPE_NAME
+        fig.save_recipe(yaml_path, include_data=include_data, data_format=data_format)
+
+        if is_zip:
+            # Create ZIP bundle
+            zip_path = path.with_suffix(".zip")
+            with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as zf:
+                zf.write(yaml_path, BUNDLE_RECIPE_NAME)
+                zf.write(image_path, image_name)
+            if verbose:
+                print(f"Saved: {zip_path} (ZIP bundle)")
+            return zip_path, zip_path
+        else:
+            # Create directory bundle
+            bundle_dir = Path(str(path).rstrip("/"))
+            bundle_dir.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(yaml_path, bundle_dir / BUNDLE_RECIPE_NAME)
+            shutil.copy2(image_path, bundle_dir / image_name)
+            if verbose:
+                print(f"Saved: {bundle_dir}/ (directory bundle)")
+            return bundle_dir, bundle_dir / BUNDLE_RECIPE_NAME
+
+
+def save_figure(
+    fig,
+    path,
+    include_data: bool = True,
+    data_format: str = "csv",
+    validate: bool = True,
+    validate_mse_threshold: float = 100.0,
+    validate_error_level: str = "error",
+    verbose: bool = True,
+    dpi: Optional[int] = None,
+    image_format: Optional[str] = None,
+):
+    """Core save implementation.
+
+    Supports multiple output formats:
+    - Image file (.png, .pdf, etc.): Saves image + .yaml recipe
+    - YAML file (.yaml): Saves recipe + image
+    - Directory (path/ or no extension): Saves as bundle directory
+    - ZIP file (.zip): Saves as ZIP bundle
+    """
+    from .._wrappers import RecordingFigure
+
+    path = Path(path)
+
+    if not isinstance(fig, RecordingFigure):
+        raise TypeError(
+            "Expected RecordingFigure. Use fr.subplots() to create "
+            "a recording-enabled figure."
+        )
+
+    # Get DPI and transparency from style if not specified
+    dpi = get_save_dpi(dpi)
+    transparent = get_save_transparency()
+
+    # Finalize tick configuration and special plot types for all axes
+    from ..styles._style_applier import finalize_special_plots, finalize_ticks
+
+    # Get style for special plot finalization
+    style_dict = {}
+    if hasattr(fig, "style") and fig.style:
+        from ..styles import get_style
+
+        style_dict = get_style(fig.style)
+
+    for ax in fig.fig.get_axes():
+        finalize_ticks(ax)
+        finalize_special_plots(ax, style_dict)
+
+    # Check if saving as bundle
+    if _is_bundle_path(path):
+        bundle_path, yaml_path = _save_as_bundle(
+            fig,
+            path,
+            include_data,
+            data_format,
+            dpi,
+            transparent,
+            image_format or _get_default_image_format(),
+            verbose,
+        )
+        # No validation for bundles (yet)
+        return bundle_path, yaml_path, None
+
+    # Resolve paths for standard save
+    image_path, yaml_path, _ = resolve_save_paths(path, image_format)
+
+    # Save the image
+    fig.fig.savefig(image_path, dpi=dpi, bbox_inches="tight", transparent=transparent)
+
+    # Save the recipe
+    saved_yaml = fig.save_recipe(
+        yaml_path, include_data=include_data, data_format=data_format
+    )
+
+    # Validate if requested
+    if validate:
+        from .._validator import validate_on_save
+
+        result = validate_on_save(fig, saved_yaml, mse_threshold=validate_mse_threshold)
+        status = "PASSED" if result.valid else "FAILED"
+        if verbose:
+            print(
+                f"Saved: {image_path} + {yaml_path} (Reproducible Validation: {status})"
+            )
+        if not result.valid:
+            msg = f"Reproducibility validation failed (MSE={result.mse:.1f}): {result.message}"
+            if validate_error_level == "error":
+                raise ValueError(msg)
+            elif validate_error_level == "warning":
+                import warnings
+
+                warnings.warn(msg, UserWarning)
+            # "debug" level: silent, just return the result
+        return image_path, yaml_path, result
+
+    if verbose:
+        print(f"Saved: {image_path} + {yaml_path}")
+    return image_path, yaml_path, None
+
+
+__all__ = [
+    "IMAGE_EXTENSIONS",
+    "YAML_EXTENSIONS",
+    "resolve_save_paths",
+    "get_save_dpi",
+    "get_save_transparency",
+    "save_figure",
+]
+
+# EOF

figrecipe/_api/_seaborn_proxy.py

@@ -0,0 +1,34 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Seaborn proxy for figrecipe.
+
+Provides lazy seaborn integration via ps.sns.
+"""
+
+__all__ = [
+    "sns",
+]
+
+# Lazy import for seaborn to avoid hard dependency
+_sns_recorder = None
+
+
+def _get_sns():
+    """Get the seaborn recorder (lazy initialization)."""
+    global _sns_recorder
+    if _sns_recorder is None:
+        from .._seaborn import get_seaborn_recorder
+
+        _sns_recorder = get_seaborn_recorder()
+    return _sns_recorder
+
+
+class _SeabornProxy:
+    """Proxy object for seaborn access via ps.sns."""
+
+    def __getattr__(self, name: str):
+        return getattr(_get_sns(), name)
+
+
+# Create seaborn proxy
+sns = _SeabornProxy()