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

figrecipe/styles/_style_applier.py

@@ -5,188 +5,31 @@
 Applies mm-based styling to matplotlib axes for publication-quality figures.
 """
 
-__all__ = ["apply_style_mm", "apply_theme_colors", "check_font", "list_available_fonts"]
+__all__ = [
+    "apply_style_mm",
+    "apply_theme_colors",
+    "check_font",
+    "finalize_ticks",
+    "finalize_special_plots",
+    "list_available_fonts",
+]
 
-import warnings
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict
 
 from matplotlib.axes import Axes
 
 from .._utils._units import mm_to_pt
-
-
-def list_available_fonts() -> List[str]:
-    """List all available font families.
-
-    Returns
-    -------
-    list of str
-        Sorted list of available font family names.
-
-    Examples
-    --------
-    >>> fonts = ps.list_available_fonts()
-    >>> print(fonts[:5])
-    ['Arial', 'Courier New', 'DejaVu Sans', ...]
-    """
-    import matplotlib.font_manager as fm
-    fonts = set()
-    for font in fm.fontManager.ttflist:
-        fonts.add(font.name)
-    return sorted(fonts)
-
-
-def check_font(font_family: str, fallback: str = "DejaVu Sans") -> str:
-    """Check if font is available, with fallback and helpful error message.
-
-    Parameters
-    ----------
-    font_family : str
-        Requested font family name.
-    fallback : str
-        Fallback font if requested font is not available.
-
-    Returns
-    -------
-    str
-        The font to use (original if available, fallback otherwise).
-
-    Examples
-    --------
-    >>> font = check_font("Arial")  # Returns "Arial" if available
-    >>> font = check_font("NonExistentFont")  # Returns fallback with warning
-    """
-    import matplotlib.font_manager as fm
-
-    available = list_available_fonts()
-
-    if font_family in available:
-        return font_family
-
-    # Font not found - show helpful message
-    similar = [f for f in available if font_family.lower() in f.lower()]
-
-    msg = f"Font '{font_family}' not found.\n"
-    if similar:
-        msg += f"  Similar fonts available: {similar[:5]}\n"
-    msg += f"  Using fallback: '{fallback}'\n"
-    msg += f"  To see all available fonts: ps.list_available_fonts()\n"
-    msg += f"  To install Arial on Linux: sudo apt install ttf-mscorefonts-installer"
-
-    warnings.warn(msg, UserWarning)
-
-    return fallback if fallback in available else "DejaVu Sans"
-
-
-# Default theme color palettes (Monaco/VS Code style for dark)
-THEME_COLORS = {
-    "dark": {
-        "figure_bg": "#1e1e1e",     # VS Code main background
-        "axes_bg": "#252526",       # VS Code panel background
-        "legend_bg": "#252526",     # Same as axes
-        "text": "#d4d4d4",          # VS Code default text
-        "spine": "#3c3c3c",         # Subtle border color
-        "tick": "#d4d4d4",          # Match text
-        "grid": "#3a3a3a",          # Subtle grid
-    },
-    "light": {
-        "figure_bg": "none",        # Transparent
-        "axes_bg": "none",          # Transparent
-        "legend_bg": "none",        # Transparent
-        "text": "black",
-        "spine": "black",
-        "tick": "black",
-        "grid": "#cccccc",
-    },
-}
-
-
-def apply_theme_colors(
-    ax: Axes,
-    theme: str = "light",
-    custom_colors: Optional[Dict[str, str]] = None,
-) -> None:
-    """Apply theme colors to axes for dark/light mode support.
-
-    Parameters
-    ----------
-    ax : matplotlib.axes.Axes
-        Target axes to apply theme to
-    theme : str
-        Color theme: "light" or "dark" (default: "light")
-    custom_colors : dict, optional
-        Custom color overrides. Keys: figure_bg, axes_bg, legend_bg, text, spine, tick, grid
-
-    Examples
-    --------
-    >>> fig, ax = plt.subplots()
-    >>> apply_theme_colors(ax, theme="dark")  # Eye-friendly dark mode
-    """
-    # Get base theme colors
-    colors = THEME_COLORS.get(theme, THEME_COLORS["light"]).copy()
-
-    # Apply custom overrides
-    if custom_colors:
-        # Handle legacy key name (background -> figure_bg)
-        if "background" in custom_colors and "figure_bg" not in custom_colors:
-            custom_colors["figure_bg"] = custom_colors.pop("background")
-        colors.update(custom_colors)
-
-    # Helper to check for transparent/none
-    def is_transparent(color):
-        if color is None:
-            return False
-        return str(color).lower() in ("none", "transparent")
-
-    # Apply axes background (handle "none"/"transparent" for transparency)
-    axes_bg = colors.get("axes_bg", "none")
-    if is_transparent(axes_bg):
-        ax.set_facecolor("none")
-        ax.patch.set_alpha(0)
-    else:
-        ax.set_facecolor(axes_bg)
-
-    # Apply figure background if accessible
-    fig = ax.get_figure()
-    if fig is not None:
-        fig_bg = colors.get("figure_bg", "none")
-        if is_transparent(fig_bg):
-            fig.patch.set_facecolor("none")
-            fig.patch.set_alpha(0)
-        else:
-            fig.patch.set_facecolor(fig_bg)
-
-    # Apply text colors (labels, titles)
-    ax.xaxis.label.set_color(colors["text"])
-    ax.yaxis.label.set_color(colors["text"])
-    ax.title.set_color(colors["text"])
-
-    # Apply spine colors
-    for spine in ax.spines.values():
-        spine.set_color(colors["spine"])
-
-    # Apply tick colors (both marks and labels)
-    ax.tick_params(colors=colors["tick"], which="both")
-    for label in ax.get_xticklabels() + ax.get_yticklabels():
-        label.set_color(colors["tick"])
-
-    # Apply legend colors if legend exists
-    legend = ax.get_legend()
-    if legend is not None:
-        for text in legend.get_texts():
-            text.set_color(colors["text"])
-        title = legend.get_title()
-        if title:
-            title.set_color(colors["text"])
-        frame = legend.get_frame()
-        if frame:
-            legend_bg = colors.get("legend_bg", colors.get("axes_bg", "none"))
-            if is_transparent(legend_bg):
-                frame.set_facecolor("none")
-                frame.set_alpha(0)
-            else:
-                frame.set_facecolor(legend_bg)
-            frame.set_edgecolor(colors["spine"])
+from ._finalize import finalize_special_plots, finalize_ticks
+from ._fonts import check_font, list_available_fonts
+from ._plot_styles import (
+    apply_barplot_style,
+    apply_boxplot_style,
+    apply_histogram_style,
+    apply_matrix_style,
+    apply_pie_style,
+    apply_violinplot_style,
+)
+from ._themes import THEME_COLORS, apply_theme_colors
 
 
 def apply_style_mm(ax: Axes, style: Dict[str, Any]) -> float:
@@ -239,6 +82,8 @@ def apply_style_mm(ax: Axes, style: Dict[str, Any]) -> float:
     >>> trace_lw = apply_style_mm(ax, style)
     >>> ax.plot(x, y, lw=trace_lw)
     """
+    import matplotlib as mpl
+
     # Apply theme colors (dark/light mode)
     theme = style.get("theme", "light")
     theme_colors = style.get("theme_colors", None)
@@ -261,10 +106,28 @@ def apply_style_mm(ax: Axes, style: Dict[str, Any]) -> float:
     # Convert marker size from mm to points
     marker_size_mm = style.get("marker_size_mm")
     if marker_size_mm is not None:
-        import matplotlib as mpl
         marker_size_pt = mm_to_pt(marker_size_mm)
         mpl.rcParams["lines.markersize"] = marker_size_pt
 
+    # Set boxplot flier (outlier) marker size
+    flier_mm = style.get("markers_flier_mm", style.get("flier_mm"))
+    if flier_mm is not None:
+        flier_size_pt = mm_to_pt(flier_mm)
+        mpl.rcParams["boxplot.flierprops.markersize"] = flier_size_pt
+
+    # Set boxplot median color
+    median_color = style.get("boxplot_median_color")
+    if median_color is not None:
+        mpl.rcParams["boxplot.medianprops.color"] = median_color
+
+    # Apply plot-specific styles
+    apply_boxplot_style(ax, style)
+    apply_violinplot_style(ax, style)
+    apply_barplot_style(ax, style)
+    apply_histogram_style(ax, style)
+    apply_pie_style(ax, style)
+    apply_matrix_style(ax, style)
+
     # Configure tick parameters
     tick_pad_pt = style.get("tick_pad_pt", 2.0)
     tick_direction = style.get("tick_direction", "out")
@@ -277,7 +140,7 @@ def apply_style_mm(ax: Axes, style: Dict[str, Any]) -> float:
         right=False,
     )
 
-    # Apply font sizes and family (with font availability check)
+    # Apply font sizes and family
     axis_fs = style.get("axis_font_size_pt", 8)
     tick_fs = style.get("tick_font_size_pt", 7)
     title_fs = style.get("title_font_size_pt", 9)
@@ -303,10 +166,9 @@ def apply_style_mm(ax: Axes, style: Dict[str, Any]) -> float:
     title_pad_pt = style.get("title_pad_pt", 4.0)
     ax.set_title(ax.get_title(), pad=title_pad_pt)
 
-    # Set legend font size and background via rcParams (for future legends)
-    import matplotlib as mpl
-    mpl.rcParams['legend.fontsize'] = legend_fs
-    mpl.rcParams['legend.title_fontsize'] = legend_fs
+    # Set legend font size and background via rcParams
+    mpl.rcParams["legend.fontsize"] = legend_fs
+    mpl.rcParams["legend.title_fontsize"] = legend_fs
 
     # Set legend colors from theme
     theme = style.get("theme", "light")
@@ -323,15 +185,15 @@ def apply_style_mm(ax: Axes, style: Dict[str, Any]) -> float:
 
     # Handle transparent backgrounds
     if str(legend_bg).lower() in ("none", "transparent"):
-        mpl.rcParams['legend.facecolor'] = 'none'
-        mpl.rcParams['legend.framealpha'] = 0
+        mpl.rcParams["legend.facecolor"] = "none"
+        mpl.rcParams["legend.framealpha"] = 0
     else:
-        mpl.rcParams['legend.facecolor'] = legend_bg
-        mpl.rcParams['legend.framealpha'] = 1.0
+        mpl.rcParams["legend.facecolor"] = legend_bg
+        mpl.rcParams["legend.framealpha"] = 1.0
 
     # Set legend text and edge colors
-    mpl.rcParams['legend.edgecolor'] = spine_color
-    mpl.rcParams['legend.labelcolor'] = text_color
+    mpl.rcParams["legend.edgecolor"] = spine_color
+    mpl.rcParams["legend.labelcolor"] = text_color
 
     legend = ax.get_legend()
     if legend is not None:
@@ -345,31 +207,26 @@ def apply_style_mm(ax: Axes, style: Dict[str, Any]) -> float:
     else:
         ax.grid(False)
 
-    # Configure number of ticks
-    n_ticks = style.get("n_ticks")
-    if n_ticks is not None:
-        from matplotlib.ticker import MaxNLocator
-        ax.xaxis.set_major_locator(MaxNLocator(nbins=n_ticks))
-        ax.yaxis.set_major_locator(MaxNLocator(nbins=n_ticks))
+    # Configure number of ticks (deferred to finalize_ticks)
+    n_ticks_min = style.get("n_ticks_min")
+    n_ticks_max = style.get("n_ticks_max")
+    if n_ticks_min is not None or n_ticks_max is not None:
+        ax._figrecipe_n_ticks_min = n_ticks_min or 3
+        ax._figrecipe_n_ticks_max = n_ticks_max or 4
 
     # Apply color palette to both rcParams and this specific axes
     color_palette = style.get("color_palette")
     if color_palette is not None:
-        import matplotlib as mpl
-        # Normalize colors (RGB 0-255 to 0-1)
         normalized_palette = []
         for c in color_palette:
             if isinstance(c, (list, tuple)) and len(c) >= 3:
-                # Check if already normalized
                 if all(v <= 1.0 for v in c):
                     normalized_palette.append(tuple(c))
                 else:
                     normalized_palette.append(tuple(v / 255.0 for v in c))
             else:
                 normalized_palette.append(c)
-        # Set rcParams for future axes
-        mpl.rcParams['axes.prop_cycle'] = mpl.cycler(color=normalized_palette)
-        # Also set the color cycle on this specific axes (axes cache cycler at creation)
+        mpl.rcParams["axes.prop_cycle"] = mpl.cycler(color=normalized_palette)
         ax.set_prop_cycle(color=normalized_palette)
 
     # Store style in axes for reference
@@ -384,7 +241,6 @@ if __name__ == "__main__":
     import matplotlib.pyplot as plt
     import numpy as np
 
-    # Test styling
     print("Testing style application...")
 
     fig, ax = plt.subplots(figsize=(4, 3))
@@ -410,3 +266,5 @@ if __name__ == "__main__":
     plt.savefig("/tmp/test_style.png", dpi=300, bbox_inches="tight")
     print("Saved to /tmp/test_style.png")
     plt.close()
+
+# EOF

figrecipe/styles/_style_loader.py

@@ -18,12 +18,15 @@ Usage:
 
 __all__ = [
     "load_style",
+    "load_preset",
     "unload_style",
     "get_style",
+    "get_current_style_dict",
     "reload_style",
     "list_presets",
     "STYLE",
     "to_subplots_kwargs",
+    "DotDict",
 ]
 
 from pathlib import Path
@@ -31,6 +34,8 @@ from typing import Any, Dict, List, Optional, Union
 
 from ruamel.yaml import YAML
 
+from ._dotdict import DotDict
+from ._kwargs_converter import to_subplots_kwargs
 
 # Path to presets directory
 _PRESETS_DIR = Path(__file__).parent / "presets"
@@ -44,7 +49,7 @@ _PRESET_ALIASES = {
 }
 
 # Global style cache
-_STYLE_CACHE: Optional["DotDict"] = None
+_STYLE_CACHE: Optional[DotDict] = None
 _CURRENT_STYLE_NAME: Optional[str] = None
 
 
@@ -70,52 +75,6 @@ def list_presets() -> List[str]:
     return ["MATPLOTLIB", "SCITEX"]
 
 
-class DotDict(dict):
-    """Dictionary with dot-notation access to nested keys.
-
-    Examples
-    --------
-    >>> d = DotDict({"axes": {"width_mm": 40}})
-    >>> d.axes.width_mm
-    40
-    """
-
-    def __getattr__(self, key: str) -> Any:
-        # Handle special methods first
-        if key == 'to_subplots_kwargs':
-            return lambda: to_subplots_kwargs(self)
-        try:
-            value = self[key]
-            if isinstance(value, dict) and not isinstance(value, DotDict):
-                value = DotDict(value)
-                self[key] = value
-            return value
-        except KeyError:
-            raise AttributeError(f"'{type(self).__name__}' has no attribute '{key}'")
-
-    def __setattr__(self, key: str, value: Any) -> None:
-        self[key] = value
-
-    def __delattr__(self, key: str) -> None:
-        try:
-            del self[key]
-        except KeyError:
-            raise AttributeError(f"'{type(self).__name__}' has no attribute '{key}'")
-
-    def get(self, key: str, default: Any = None) -> Any:
-        """Get value with default, supporting nested keys with dots."""
-        if "." in key:
-            parts = key.split(".")
-            value = self
-            for part in parts:
-                if isinstance(value, dict) and part in value:
-                    value = value[part]
-                else:
-                    return default
-            return value
-        return super().get(key, default)
-
-
 def _deep_merge(base: Dict, override: Dict) -> Dict:
     """Deep merge two dictionaries, with override taking precedence."""
     result = base.copy()
@@ -172,17 +131,18 @@ def _apply_dark_theme(style_dict: Dict) -> Dict:
         Style dictionary with dark theme applied
     """
     import copy
+
     result = copy.deepcopy(style_dict)
 
     # Monaco/VS Code dark theme colors (from scitex-cloud UIUX.md)
     dark_colors = {
-        "figure_bg": "#1e1e1e",     # VS Code main background
-        "axes_bg": "#1e1e1e",       # Same as figure background
-        "legend_bg": "#1e1e1e",     # Same as figure background
-        "text": "#d4d4d4",          # VS Code default text
-        "spine": "#3c3c3c",         # Subtle border color
-        "tick": "#d4d4d4",          # Match text
-        "grid": "#3a3a3a",          # Subtle grid
+        "figure_bg": "#1e1e1e",  # VS Code main background
+        "axes_bg": "#1e1e1e",  # Same as figure background
+        "legend_bg": "#1e1e1e",  # Same as figure background
+        "text": "#d4d4d4",  # VS Code default text
+        "spine": "#3c3c3c",  # Subtle border color
+        "tick": "#d4d4d4",  # Match text
+        "grid": "#3a3a3a",  # Subtle grid
     }
 
     # Update theme section
@@ -198,6 +158,43 @@ def _apply_dark_theme(style_dict: Dict) -> Dict:
     return result
 
 
+def load_preset(name: str, dark: bool = False) -> Optional[DotDict]:
+    """Load a style preset without affecting global cache.
+
+    This is useful for GUI editors that need to switch themes
+    without affecting the global state.
+
+    Parameters
+    ----------
+    name : str
+        Preset name (e.g., "SCITEX", "MATPLOTLIB")
+    dark : bool, optional
+        If True, apply dark theme transformation
+
+    Returns
+    -------
+    DotDict or None
+        Style configuration as DotDict, or None if not found
+    """
+    # Resolve aliases
+    resolved_name = _PRESET_ALIASES.get(name.upper(), name.upper())
+
+    # Find the preset file
+    style_path = _PRESETS_DIR / f"{resolved_name}.yaml"
+
+    if not style_path.exists():
+        return None
+
+    style_dict = _load_yaml(style_path)
+    style_dict["_name"] = name.upper()
+
+    # Apply dark theme if requested
+    if dark:
+        style_dict = _apply_dark_theme(style_dict)
+
+    return DotDict(style_dict)
+
+
 def unload_style() -> None:
     """Unload the current style and reset to matplotlib defaults.
 
@@ -218,10 +215,13 @@ def unload_style() -> None:
 
     # Reset matplotlib rcParams to defaults
     import matplotlib as mpl
+
     mpl.rcParams.update(mpl.rcParamsDefault)
 
 
-def load_style(style: Optional[Union[str, Path, bool]] = "SCITEX", dark: bool = False) -> Optional[DotDict]:
+def load_style(
+    style: Optional[Union[str, Path, bool]] = "SCITEX", dark: bool = False
+) -> Optional[DotDict]:
     """Load style configuration from preset or YAML file.
 
     Parameters
@@ -294,7 +294,14 @@ def load_style(style: Optional[Union[str, Path, bool]] = "SCITEX", dark: bool =
         resolved_style = base_style
 
     # Determine the style path
-    if isinstance(resolved_style, Path) or (isinstance(resolved_style, str) and ("/" in resolved_style or "\\" in resolved_style or resolved_style.endswith(".yaml"))):
+    if isinstance(resolved_style, Path) or (
+        isinstance(resolved_style, str)
+        and (
+            "/" in resolved_style
+            or "\\" in resolved_style
+            or resolved_style.endswith(".yaml")
+        )
+    ):
         # Explicit file path
         style_path = Path(resolved_style)
         style_name = str(resolved_style)
@@ -343,76 +350,19 @@ def get_style() -> DotDict:
     return _STYLE_CACHE
 
 
-def to_subplots_kwargs(style: Optional[DotDict] = None) -> Dict[str, Any]:
-    """Convert style DotDict to kwargs for ps.subplots().
-
-    Parameters
-    ----------
-    style : DotDict, optional
-        Style configuration. If None, uses current loaded style.
+def get_current_style_dict() -> Dict[str, Any]:
+    """Get current style as a flat dictionary for style applier functions.
 
     Returns
     -------
     dict
-        Keyword arguments for ps.subplots()
-
-    Examples
-    --------
-    >>> style = load_style()
-    >>> kwargs = to_subplots_kwargs(style)
-    >>> fig, ax = ps.subplots(**kwargs)
+        Flattened style dictionary with keys like 'pie_show_axes', 'imshow_show_axes'.
+        Returns empty dict if no style is loaded.
     """
-    if style is None:
-        style = get_style()
-
-    result = {
-        # Axes dimensions
-        "axes_width_mm": style.axes.width_mm,
-        "axes_height_mm": style.axes.height_mm,
-        "axes_thickness_mm": style.axes.thickness_mm,
-        # Margins
-        "margin_left_mm": style.margins.left_mm,
-        "margin_right_mm": style.margins.right_mm,
-        "margin_bottom_mm": style.margins.bottom_mm,
-        "margin_top_mm": style.margins.top_mm,
-        # Spacing
-        "space_w_mm": style.spacing.horizontal_mm,
-        "space_h_mm": style.spacing.vertical_mm,
-        # Ticks
-        "tick_length_mm": style.ticks.length_mm,
-        "tick_thickness_mm": style.ticks.thickness_mm,
-        "n_ticks": style.ticks.n_ticks,
-        # Lines
-        "trace_thickness_mm": style.lines.trace_mm,
-        # Markers
-        "marker_size_mm": style.markers.size_mm,
-        # Fonts
-        "font_family": style.fonts.family,
-        "axis_font_size_pt": style.fonts.axis_label_pt,
-        "tick_font_size_pt": style.fonts.tick_label_pt,
-        "title_font_size_pt": style.fonts.title_pt,
-        "suptitle_font_size_pt": style.fonts.suptitle_pt,
-        "legend_font_size_pt": style.fonts.legend_pt,
-        # Padding
-        "label_pad_pt": style.padding.label_pt,
-        "tick_pad_pt": style.padding.tick_pt,
-        "title_pad_pt": style.padding.title_pt,
-        # Output
-        "dpi": style.output.dpi,
-        # Theme
-        "theme": style.theme.mode,
-    }
-
-    # Add theme colors from preset if available
-    theme_mode = style.theme.mode
-    if "theme" in style and theme_mode in style.theme:
-        result["theme_colors"] = dict(style.theme[theme_mode])
-
-    # Add color palette if available
-    if "colors" in style and "palette" in style.colors:
-        result["color_palette"] = list(style.colors.palette)
-
-    return result
+    global _STYLE_CACHE
+    if _STYLE_CACHE is None:
+        return {}
+    return to_subplots_kwargs(_STYLE_CACHE)
 
 
 # Lazy-loaded global STYLE object
@@ -448,3 +398,5 @@ if __name__ == "__main__":
 
     print("\nUsing STYLE proxy...")
     print(f"  STYLE.fonts.family: {STYLE.fonts.family}")
+
+# EOF