qc-core 0.0.1__tar.gz

qc_core-0.0.1/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.3
+Name: qc-core
+Version: 0.0.1
+Summary: Core operations that are used across the QuantClimate stack.
+Author: Thomas Pinder
+Author-email: Thomas Pinder <thomas@quantclimate.com>
+Requires-Dist: matplotlib>=3.11.1
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# qc-core
+
+Shared Python utilities for QuantClimate. The package includes the Calibrated Ledger Matplotlib style and plotting helpers.
+
+## Installation
+
+```bash
+pip install qc-core
+```
+
+qc-core requires Python 3.11 or later.
+
+## Matplotlib style
+
+Load the packaged style globally:
+
+```python
+import qc_core
+
+qc_core.use_ledger_style()
+```
+
+Use the plotting module for the complete plotting API:
+
+```python
+from qc_core import plotting
+
+plotting.use_ledger_style()
+```
+
+`qc_core.style_path()` returns the installed style file's path.

qc_core-0.0.1/README.md

@@ -0,0 +1,31 @@
+# qc-core
+
+Shared Python utilities for QuantClimate. The package includes the Calibrated Ledger Matplotlib style and plotting helpers.
+
+## Installation
+
+```bash
+pip install qc-core
+```
+
+qc-core requires Python 3.11 or later.
+
+## Matplotlib style
+
+Load the packaged style globally:
+
+```python
+import qc_core
+
+qc_core.use_ledger_style()
+```
+
+Use the plotting module for the complete plotting API:
+
+```python
+from qc_core import plotting
+
+plotting.use_ledger_style()
+```
+
+`qc_core.style_path()` returns the installed style file's path.

qc_core-0.0.1/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "qc-core"
+version = "0.0.1"
+description = "Core operations that are used across the QuantClimate stack."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = ["matplotlib>=3.11.1"]
+
+[[project.authors]]
+name = "Thomas Pinder"
+email = "thomas@quantclimate.com"
+
+[project.scripts]
+qc-core = "qc_core:main"
+
+[build-system]
+requires = ["uv_build>=0.11.32,<0.12.0"]
+build-backend = "uv_build"

qc_core-0.0.1/pyproject.toml.orig

@@ -0,0 +1,19 @@
+[project]
+name = "qc-core"
+version = "0.0.1"
+description = "Core operations that are used across the QuantClimate stack."
+readme = "README.md"
+authors = [
+    { name = "Thomas Pinder", email = "thomas@quantclimate.com" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "matplotlib>=3.11.1",
+]
+
+[project.scripts]
+qc-core = "qc_core:main"
+
+[build-system]
+requires = ["uv_build>=0.11.32,<0.12.0"]
+build-backend = "uv_build"

qc_core-0.0.1/src/qc_core/__init__.py

@@ -0,0 +1,9 @@
+"""Core operations used across the QuantClimate stack."""
+
+from qc_core import plotting
+from qc_core.plotting import style_path, use_ledger_style
+
+__all__ = ["main", "plotting", "style_path", "use_ledger_style"]
+
+def main() -> None:
+    print("Hello from qc-core!")

qc_core-0.0.1/src/qc_core/ledger.mplstyle

@@ -0,0 +1,135 @@
+## QuantClimate "Calibrated Ledger" matplotlib style -- light mode.
+## Aligned with landing-page/DESIGN.md: warm off-white paper, near-black umber
+## ink, hairline rules, and a single oxblood accent leading a short, muted
+## categorical cycle. Serif states the claim (titles, via
+## case_studies.plotting.serif_title); sans carries the evidence (labels,
+## ticks, legends).
+##
+## The color cycle passes the six categorical-palette checks (OKLab validator:
+## lightness band, chroma floor, CVD dE >= 8 adjacent, normal-vision dE >= 15,
+## contrast >= 3:1 on #faf9f7). Slot 1 is oxblood lifted one lightness step
+## (#8a332e vs brand #7a2e2a) to sit inside the series lightness band; the
+## brand oxblood itself remains the accent for single-series emphasis.
+##
+## ---- Fonts --------------------------------------------------------------
+## matplotlib can only use LOCALLY installed fonts (no web fonts). Install
+## Spectral and Public Sans (fonts.google.com) for full fidelity; otherwise
+## this falls back to Georgia / Helvetica / DejaVu.
+font.family: sans-serif
+font.sans-serif: Public Sans, Helvetica Neue, Arial, DejaVu Sans, sans-serif
+font.serif: Spectral, Georgia, Palatino, DejaVu Serif, serif
+font.monospace: Menlo, Consolas, DejaVu Sans Mono, monospace
+font.size: 9
+
+
+## ---- Figure -------------------------------------------------------------
+figure.facecolor: faf9f7
+figure.edgecolor: faf9f7
+figure.dpi: 250
+figure.figsize: 5.5, 3
+figure.constrained_layout.use: True
+figure.autolayout: False
+
+
+## ---- Saved figures ------------------------------------------------------
+## Transparent by default so figures sit directly on the site's paper ground.
+savefig.facecolor: faf9f7
+savefig.edgecolor: faf9f7
+savefig.dpi: 250
+savefig.bbox: tight
+savefig.pad_inches: 0.08
+savefig.transparent: True
+
+
+## ---- Axes ---------------------------------------------------------------
+## Hairline frame, bottom + left only: rules stay recessive so the data wears
+## the ink. Titles are ink, left-aligned ("the claim").
+axes.facecolor: faf9f7
+axes.edgecolor: e6dfd6
+axes.linewidth: 1.0
+axes.spines.top: False
+axes.spines.right: False
+axes.spines.left: True
+axes.spines.bottom: True
+axes.labelcolor: 423b36
+axes.labelsize: 9
+axes.labelpad: 3.0
+axes.titlecolor: 2a2320
+axes.titlesize: 11.5
+axes.titleweight: semibold
+axes.titlelocation: left
+axes.titlepad: 10.0
+axes.axisbelow: True
+## NB: hex without '#' -- an in-value '#' starts an rc-file comment and
+## silently truncates this line, dropping the whole cycle.
+axes.prop_cycle: cycler('color', ['8a332e', '31649e', '9a7020', '8f4a85', '5a7a2e'])
+
+
+## ---- Text ---------------------------------------------------------------
+## NOTE: ink (2a2320), body (423b36), muted (6b6058), hairline (e6dfd6) and
+## paper (faf9f7) mirror case_studies.plotting.COLORS -- keep them in sync.
+text.color: 2a2320
+
+
+## ---- Ticks --------------------------------------------------------------
+## Small outward calibration marks in muted; labels muted too (metadata).
+xtick.color: 6b6058
+ytick.color: 6b6058
+xtick.labelcolor: 6b6058
+ytick.labelcolor: 6b6058
+xtick.labelsize: 8.5
+ytick.labelsize: 8.5
+xtick.direction: out
+ytick.direction: out
+xtick.major.size: 3.5
+ytick.major.size: 3.5
+xtick.major.width: 0.8
+ytick.major.width: 0.8
+xtick.minor.size: 2.0
+ytick.minor.size: 2.0
+xtick.minor.width: 0.6
+ytick.minor.width: 0.6
+
+
+## ---- Grid ---------------------------------------------------------------
+## Horizontal hairline rules only -- the ledger's lines.
+axes.grid: True
+axes.grid.axis: y
+grid.color: e6dfd6
+grid.linewidth: 0.6
+grid.linestyle: -
+grid.alpha: 0.8
+
+
+## ---- Lines & markers ----------------------------------------------------
+lines.linewidth: 1.8
+lines.markersize: 5.5
+lines.solid_capstyle: round
+lines.dash_capstyle: round
+
+
+## ---- Patches (bars, histograms, ...) ------------------------------------
+## Paper-colored edges give adjacent bars / stacked segments a surface gap.
+patch.facecolor: 8a332e
+patch.edgecolor: faf9f7
+patch.linewidth: 0.8
+patch.force_edgecolor: True
+patch.antialiased: True
+
+
+## ---- Scatter ------------------------------------------------------------
+scatter.edgecolors: faf9f7
+
+
+## ---- Legend -------------------------------------------------------------
+## Frameless: identity comes from the mark swatch, text stays in body ink.
+legend.frameon: False
+legend.fontsize: 8.5
+legend.title_fontsize: 9
+legend.labelcolor: 423b36
+legend.loc: best
+legend.numpoints: 1
+
+## Keep text editable in vector editors.
+pdf.fonttype: 42
+ps.fonttype: 42

qc_core-0.0.1/src/qc_core/plotting.py

@@ -0,0 +1,583 @@
+""""Calibrated Ledger" matplotlib styling for QuantClimate case studies.
+
+Aligned with the landing-page design system (``landing-page/DESIGN.md``):
+warm off-white paper, near-black umber ink, hairline rules, and a single
+oxblood accent leading a short, muted categorical cycle. Spectral (serif)
+states the claim in titles via :func:`serif_title`; Public Sans (sans)
+carries the evidence in labels, ticks, and legends.
+
+This module supersedes ``case-studies/src/case_studies/style.py`` (the Tufte
+theme). The API mirrors it -- ``use_ledger_style`` replaces
+``use_tufte_style``; ``COLORS``, ``add_halo``,
+``legend_right``/``legend_below`` keep their names -- so migration is
+mechanical. Two rc files ship alongside this module: ``ledger.mplstyle``
+(light, the default) and ``ledger_dark.mplstyle``.
+
+Both color cycles pass the six categorical-palette checks (OKLab: lightness
+band, chroma floor, CVD separation dE >= 8 adjacent, normal-vision floor
+dE >= 15, contrast >= 3:1 on their surface). The first three slots also pass
+the stricter all-pairs test, so scatter plots should carry at most three
+series. Beyond five series, fold extras into an "Other" drawn in ``muted``
+or facet -- never invent a sixth hue.
+
+Note on fonts: matplotlib can only use locally *installed* fonts (no web
+fonts). Install Spectral and Public Sans (fonts.google.com) for full
+fidelity; otherwise the style falls back to Georgia / Helvetica.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from dataclasses import asdict, dataclass, fields
+from pathlib import Path
+from typing import TYPE_CHECKING, Iterator, Sequence
+
+if TYPE_CHECKING:
+    from matplotlib.artist import Artist
+    from matplotlib.axes import Axes
+    from matplotlib.legend import Legend
+    from matplotlib.typing import ColorType
+
+# The rc files ship next to this module as package resources.
+LIGHT_STYLE_PATH: Path = Path(__file__).with_name("ledger.mplstyle")
+DARK_STYLE_PATH: Path = Path(__file__).with_name("ledger_dark.mplstyle")
+
+#: Spectral-first serif stack for claims (titles); see :func:`serif_title`.
+SERIF_STACK: list[str] = ["Spectral", "Georgia", "Palatino", "DejaVu Serif", "serif"]
+
+
+@dataclass(frozen=True)
+class Palette:
+    """Named ledger colors, mirroring ``landing-page/src/config/theme.json``.
+
+    ``ink``..``paper`` and the ``oxblood*`` accents match the design tokens;
+    ``cycle`` is the validated categorical cycle whose values also live in the
+    rc files (keep them in sync). Reference colors by attribute
+    (autocompletes) or by name::
+
+        COLORS.oxblood        # "#7a2e2a"
+        COLORS["ink"]         # "#2a2320"
+
+    After :func:`use_ledger_style` (or a manual :func:`register_colors`) the
+    same names also work directly in any matplotlib call, e.g.
+    ``color="oxblood"``.
+    """
+
+    ink: str = "#2a2320"  # near-black warm umber; titles, emphasis
+    body: str = "#423b36"  # running text; axis labels
+    muted: str = "#6b6058"  # metadata; ticks, captions, "Other" series
+    hairline: str = "#e6dfd6"  # 1px rules; spines, grid
+    surface: str = "#f3efe9"  # insets, one warm step up from paper
+    paper: str = "#faf9f7"  # the page ground -- white, not cream
+    oxblood: str = "#7a2e2a"  # THE accent; the number that matters
+    oxblood_deep: str = "#5f231f"  # hover/pressed shade
+    oxblood_wash: str = "#f4e7e4"  # pale tint; distribution fills
+    #: Validated categorical cycle. Slot 1 is oxblood lifted one lightness
+    #: step so the series band holds; the brand oxblood stays the accent for
+    #: single-series emphasis.
+    cycle: tuple[str, ...] = ("#8a332e", "#31649e", "#9a7020", "#8f4a85", "#5a7a2e")
+
+    def __getitem__(self, name: str) -> str:
+        """Look a color up by name, e.g. ``COLORS["oxblood"]``."""
+        try:
+            value = getattr(self, name)
+        except AttributeError:
+            raise KeyError(name) from None
+        if not isinstance(value, str):
+            raise KeyError(name)
+        return value
+
+    def __iter__(self) -> Iterator[str]:
+        """Iterate the *color* names (the keys), like a mapping."""
+        return (name for name, _ in self._named_colors())
+
+    def _named_colors(self) -> list[tuple[str, str]]:
+        """The ``(name, hex)`` pairs, excluding the cycle tuple."""
+        return [(k, v) for k, v in asdict(self).items() if isinstance(v, str)]
+
+    def as_dict(self) -> dict[str, str]:
+        """Return the named colors as an ordered ``{name: hex}`` mapping."""
+        return dict(self._named_colors())
+
+
+#: Light mode -- the default, matching the site's light theme.
+COLORS = Palette()
+
+#: Dark mode -- the same roles re-lit on warm near-black. ``oxblood_deep`` is
+#: derived (the design system defines no dark pressed shade); ``oxblood_wash``
+#: matches the site's dark EstimateFigure wash.
+COLORS_DARK = Palette(
+    ink="#f2ece6",
+    body="#d8cfc7",
+    muted="#9a8d84",
+    hairline="#3a322e",
+    surface="#2a2320",
+    paper="#201b19",
+    oxblood="#cf6f60",
+    oxblood_deep="#a35043",
+    oxblood_wash="#2f211e",
+    cycle=("#cf6f60", "#5b8fd6", "#b3883b", "#b877ab", "#78933f"),
+)
+
+
+def register_colors(palette: Palette = COLORS) -> None:
+    """Register the palette names in matplotlib's global color table.
+
+    Makes every name usable as a literal color anywhere matplotlib accepts
+    one, e.g. ``ax.plot(x, y, color="oxblood")`` or
+    ``ax.axhline(0, color="hairline")`` -- exactly like a built-in name.
+
+    Idempotent. Note: ``ink`` and ``paper`` are also registered (with
+    different hexes) by the superseded ``case_studies.style``; whichever
+    module registers last wins, so avoid mixing the two themes in one
+    session. Called automatically by :func:`use_ledger_style`.
+    """
+    import matplotlib.colors as mcolors
+
+    mcolors.get_named_colors_mapping().update(palette.as_dict())
+
+
+def style_path(dark: bool = False) -> Path:
+    """Return the absolute path to the packaged ledger style file."""
+    return (DARK_STYLE_PATH if dark else LIGHT_STYLE_PATH).resolve()
+
+
+def use_ledger_style(dark: bool = False) -> None:
+    """Apply the Calibrated Ledger style globally by loading the rc file.
+
+    Equivalent to ``matplotlib.rc_file(style_path(dark))`` but independent of
+    the current working directory. Also registers the named palette colors
+    (see :func:`register_colors`) so ``color="oxblood"`` works immediately.
+
+    Args:
+        dark: Load the dark-mode variant (near-black paper, lifted accent).
+    """
+    import matplotlib as mpl
+
+    mpl.rc_file(style_path(dark))
+    register_colors(COLORS_DARK if dark else COLORS)
+
+
+@contextmanager
+def _ledger_context(dark: bool = False) -> Iterator[None]:
+    """Apply the ledger style only within the ``with`` block.
+
+    Note: rcParams revert on exit, but registered color names (harmless and
+    idempotent) persist in matplotlib's global table.
+    """
+    import matplotlib as mpl
+
+    register_colors(COLORS_DARK if dark else COLORS)
+    with mpl.rc_context(fname=style_path(dark)):
+        yield
+
+
+# Expose the context manager as ``use_ledger_style.context()`` for a single,
+# discoverable entry point while keeping ``use_ledger_style()`` callable.
+use_ledger_style.context = _ledger_context  # type: ignore[attr-defined]
+
+
+def palette(n: int | None = None) -> list[str]:
+    """Return the active color cycle as a list, so colors can be indexed.
+
+    Reads the currently-loaded cycle from ``rcParams['axes.prop_cycle']``
+    (i.e. the cycle set by :func:`use_ledger_style` or whatever style is
+    active), so you can grab a specific theme color::
+
+        cols = palette()
+        ax.plot(x, y, color=cols[1])
+
+    Tip: matplotlib's built-in shorthand ``"C0"``, ``"C1"``, ... refers to
+    the 1st, 2nd, ... colors of the active cycle with no helper at all.
+
+    Args:
+        n: If given, return exactly *n* colors, repeating the cycle as
+            needed. When ``None`` (default), return the cycle once at its
+            natural length. Prefer folding a 6th+ series into ``muted``
+            instead of repeating.
+
+    Returns:
+        List of color specs (hex strings) from the active cycle.
+    """
+    import matplotlib as mpl
+
+    colors = list(mpl.rcParams["axes.prop_cycle"].by_key().get("color", []))
+    if n is None or not colors:
+        return colors
+    return [colors[i % len(colors)] for i in range(n)]
+
+
+def serif_title(
+    label: str,
+    ax: Axes | None = None,
+    **kwargs,
+) -> Artist:
+    """Set a left-aligned Spectral (serif) axes title -- the claim.
+
+    The design rule is "serif states, sans measures": Spectral makes the
+    claim, Public Sans carries the evidence. The rc files set sans globally
+    (labels, ticks, legends); this helper opts the title into the serif
+    stack, since matplotlib has no per-element font-family rcParam::
+
+        serif_title("Low water halves Rhine tonnage", ax)
+
+    Args:
+        label: Title text.
+        ax: Target axes. Defaults to the current axes (``plt.gca()``).
+        **kwargs: Forwarded to ``Axes.set_title`` (e.g. ``fontsize``, ``pad``).
+
+    Returns:
+        The title ``Text`` artist.
+    """
+    ax = _resolve_ax(ax)
+    kwargs.setdefault("fontfamily", SERIF_STACK)
+    kwargs.setdefault("fontweight", 600)
+    return ax.set_title(label, **kwargs)
+
+
+def estimate_plot(
+    x: Sequence[float],
+    density: Sequence[float],
+    *,
+    interval: tuple[float, float],
+    median: float,
+    ax: Axes | None = None,
+    colors: Palette = COLORS,
+) -> Axes:
+    """Draw the brand's signature Estimate Figure: a posterior with its interval.
+
+    Mirrors the landing page's ``EstimateFigure`` component: the full
+    posterior in a pale oxblood wash, the credible interval in translucent
+    oxblood, the outline stroked in oxblood, the median as an ink rule, and
+    a hairline baseline. The density axis is meaningless to the reader, so
+    the left spine and y-ticks are removed::
+
+        estimate_plot(grid, pdf, interval=(6, 34), median=18)
+
+    Args:
+        x: Support of the distribution (e.g. a grid of % changes).
+        density: Density values over *x* (any positive scale).
+        interval: ``(lo, hi)`` credible-interval bounds, in *x* units.
+        median: Point estimate, in *x* units.
+        ax: Target axes. Defaults to the current axes (``plt.gca()``).
+        colors: Palette to draw with (pass ``COLORS_DARK`` for dark mode).
+
+    Returns:
+        The axes drawn on.
+    """
+    import numpy as np
+
+    ax = _resolve_ax(ax)
+    xs = np.asarray(x, dtype=float)
+    ys = np.asarray(density, dtype=float)
+    lo, hi = interval
+
+    ax.fill_between(xs, ys, 0.0, color=colors.oxblood_wash, lw=0, zorder=1)
+    band = (xs >= lo) & (xs <= hi)
+    ax.fill_between(
+        xs[band], ys[band], 0.0, color=colors.oxblood, alpha=0.3, lw=0, zorder=2
+    )
+    ax.plot(xs, ys, color=colors.oxblood, lw=1.8, solid_capstyle="round", zorder=4)
+    ax.axhline(0.0, color=colors.hairline, lw=1.0, zorder=3)
+    ax.vlines(
+        median,
+        0.0,
+        float(np.interp(median, xs, ys)),
+        color=colors.ink,
+        lw=1.4,
+        zorder=5,
+    )
+
+    ax.set_ylim(bottom=0.0)
+    ax.spines["left"].set_visible(False)
+    ax.set_yticks([])
+    ax.grid(False)
+    return ax
+
+
+def _blend(color: ColorType, target: tuple[float, float, float], amount: float) -> str:
+    """Blend *color* a fraction *amount* (0..1) toward *target*; preserve alpha."""
+    import matplotlib.colors as mcolors
+
+    amount = min(1.0, max(0.0, float(amount)))
+    r, g, b, a = mcolors.to_rgba(color)
+    tr, tg, tb = target
+    mixed = (
+        r + (tr - r) * amount,
+        g + (tg - g) * amount,
+        b + (tb - b) * amount,
+        a,
+    )
+    return mcolors.to_hex(mixed, keep_alpha=a < 1.0)
+
+
+def darken(color: ColorType, amount: float = 0.3) -> str:
+    """Return a darker shade of *color* as a hex string.
+
+    Blends *amount* of the way toward black (``0`` = unchanged, ``1`` =
+    black). Accepts any matplotlib color spec -- cycle refs (``"C0"``),
+    named colors (including the registered theme names like ``"oxblood"``),
+    hex, rgb(a) tuples, or grayscale strings -- so::
+
+        darken("C0")               # 30% darker than the 1st cycle color
+        darken(COLORS.oxblood, 0.5)
+        ax.plot(x, y, color=darken("C1", 0.2))
+    """
+    return _blend(color, (0.0, 0.0, 0.0), amount)
+
+
+def lighten(color: ColorType, amount: float = 0.3) -> str:
+    """Return a lighter shade of *color* as a hex string.
+
+    Blends *amount* of the way toward white (``0`` = unchanged, ``1`` =
+    white). Accepts the same color specs as :func:`darken`.
+    """
+    return _blend(color, (1.0, 1.0, 1.0), amount)
+
+
+def change_contrast(color: ColorType, value: float) -> str:
+    """Scale a color's saturation by *value*, returning a hex string.
+
+    Adjusts saturation in HLS space (lightness preserved), so the color
+    (de)saturates without getting darker or lighter:
+
+    * ``value == 1``     -> unchanged
+    * ``0 <= value < 1`` -> desaturated, toward grey (``0`` = fully grey)
+    * ``value > 1``      -> more saturated / vivid (capped at full saturation)
+
+    Accepts the same color specs as :func:`darken`; alpha is preserved.
+    """
+    import colorsys
+
+    import matplotlib.colors as mcolors
+
+    r, g, b, a = mcolors.to_rgba(color)
+    h, lightness, s = colorsys.rgb_to_hls(r, g, b)
+    s = min(1.0, max(0.0, s * float(value)))
+    r2, g2, b2 = colorsys.hls_to_rgb(h, lightness, s)
+    return mcolors.to_hex((r2, g2, b2, a), keep_alpha=a < 1.0)
+
+
+def add_halo(
+    artist: Artist | Sequence[Artist],
+    width: float = 4.0,
+    color: ColorType = COLORS.paper,
+) -> Artist | Sequence[Artist]:
+    """Give a line/text artist a contrasting outline ("casing") so it pops.
+
+    Strokes a wider line of *color* (default: theme ``paper``) beneath the
+    artist using matplotlib path effects -- ideal for a median/reference line
+    or a label drawn over a busy histogram.
+
+    Args:
+        artist: A single artist, or a sequence of them (e.g. the list
+            returned by ``Axes.plot``).
+        width: Casing line width in points. Make it a couple of points wider
+            than the artist's own line width so the outline shows on both
+            sides.
+        color: Casing color (default: theme paper ``#faf9f7``; pass
+            ``COLORS_DARK.paper`` on the dark style).
+
+    Returns:
+        The *artist* argument, for chaining::
+
+            add_halo(ax.axvline(median, color="ink", lw=1.8, zorder=5))
+            add_halo(ax.text(median, ymax, "median", ...))
+    """
+    import matplotlib.artist as martist
+    import matplotlib.patheffects as pe
+
+    effects: list[pe.AbstractPathEffect] = [
+        pe.withStroke(linewidth=width, foreground=color)
+    ]
+    artists: list[Artist] = (
+        [artist] if isinstance(artist, martist.Artist) else list(artist)
+    )
+    for a in artists:
+        a.set_path_effects(effects)
+    return artist
+
+
+def _resolve_ax(ax: Axes | None) -> Axes:
+    """Return *ax*, or the current axes when *ax* is ``None``."""
+    if ax is None:
+        import matplotlib.pyplot as plt
+
+        ax = plt.gca()
+    return ax
+
+
+def _resolve_handles_labels(
+    ax: Axes,
+    handles: Sequence[Artist] | None,
+    labels: Sequence[str] | None,
+) -> tuple[Sequence[Artist], Sequence[str]]:
+    """Fill in missing *handles*/*labels* from the artists drawn on *ax*."""
+    if handles is None or labels is None:
+        auto_handles, auto_labels = ax.get_legend_handles_labels()
+        handles = auto_handles if handles is None else handles
+        labels = auto_labels if labels is None else labels
+    return handles, labels
+
+
+def _expand_figure_for_legend(ax: Axes, legend: Legend, margin: float = 0.1) -> None:
+    """Grow the figure canvas so *legend* fits outside the axes WITHOUT shrinking it.
+
+    The active layout engine (e.g. ``constrained_layout``) would otherwise
+    resize the axes to fit an outside legend within the fixed figure size.
+    Instead, this turns the layout engine off, pins every axes to its current
+    size in inches, and enlarges the figure on whichever sides the legend
+    overflows.
+
+    Args:
+        ax: An axes belonging to the figure to expand.
+        legend: The (already-placed) external legend to make room for.
+        margin: Gap, in inches, left between the legend and the new canvas
+            edge.
+    """
+    from matplotlib.figure import Figure
+
+    fig = ax.get_figure()
+    if not isinstance(fig, Figure):
+        return  # SubFigures (and None) cannot be resized independently.
+
+    # constrained/tight layout re-shrinks the axes on every draw, so turn the
+    # layout engine off and manage the geometry ourselves.
+    fig.set_layout_engine("none")
+
+    # Draw once so the legend (and its text) have a concrete position and size.
+    fig.canvas.draw()
+
+    size = fig.get_size_inches()
+    w_in, h_in = float(size[0]), float(size[1])
+    dpi = float(fig.get_dpi())
+
+    # Pin every axes to its current geometry, in inches.
+    axes_inches = []
+    for a in fig.axes:
+        p = a.get_position()
+        axes_inches.append(
+            (a, p.x0 * w_in, p.y0 * h_in, p.width * w_in, p.height * h_in)
+        )
+
+    # Legend extent, in inches, relative to the figure's bottom-left origin.
+    bb = legend.get_window_extent()
+    lx0, ly0, lx1, ly1 = bb.x0 / dpi, bb.y0 / dpi, bb.x1 / dpi, bb.y1 / dpi
+
+    # How far the legend spills past each figure edge (plus a margin on that side).
+    add_left = (-lx0 + margin) if lx0 < 0 else 0.0
+    add_right = (lx1 - w_in + margin) if lx1 > w_in else 0.0
+    add_bottom = (-ly0 + margin) if ly0 < 0 else 0.0
+    add_top = (ly1 - h_in + margin) if ly1 > h_in else 0.0
+
+    if not (add_left or add_right or add_bottom or add_top):
+        return  # already inside the canvas; nothing to do.
+
+    new_w = w_in + add_left + add_right
+    new_h = h_in + add_bottom + add_top
+
+    # Re-pin axes at identical inch sizes; existing content shifts right by
+    # ``add_left`` and up by ``add_bottom`` to open up the new margins. The
+    # legend is anchored in axes coordinates, so it moves with the axes.
+    for a, ix0, iy0, iw, ih in axes_inches:
+        a.set_position(
+            (
+                (ix0 + add_left) / new_w,
+                (iy0 + add_bottom) / new_h,
+                iw / new_w,
+                ih / new_h,
+            )
+        )
+
+    fig.set_size_inches(new_w, new_h)
+    fig.canvas.draw()
+
+
+def legend_right(
+    ax: Axes | None = None,
+    *,
+    handles: Sequence[Artist] | None = None,
+    labels: Sequence[str] | None = None,
+    pad: float = 0.02,
+    expand: bool = True,
+    **kwargs,
+) -> Legend:
+    """Move the legend just outside the right edge of the plot, one entry per row.
+
+    Entries are stacked in a single column, so they read top-to-bottom row by
+    row -- handy for keeping a tall, multi-series key clear of the data area.
+
+    Args:
+        ax: Target axes. Defaults to the current axes (``plt.gca()``).
+        handles: Explicit legend handles. Auto-detected from *ax* when
+            omitted.
+        labels: Explicit legend labels. Auto-detected from *ax* when omitted.
+        pad: Horizontal gap between the axes and the legend, as a fraction of
+            axes width (the legend's left edge is anchored at ``1 + pad``).
+        expand: When ``True`` (default), keep the axes at its current size
+            and grow the figure canvas to the right to fit the legend,
+            instead of letting the layout engine shrink the axes. This
+            disables the figure's layout engine (e.g. ``constrained_layout``).
+        **kwargs: Forwarded to ``Axes.legend`` (e.g. ``title``, ``fontsize``).
+            ``ncol`` defaults to 1 to preserve the row-by-row layout.
+
+    Returns:
+        The created ``matplotlib.legend.Legend``.
+    """
+    ax = _resolve_ax(ax)
+    handles, labels = _resolve_handles_labels(ax, handles, labels)
+    kwargs.setdefault("loc", "center left")
+    kwargs.setdefault("bbox_to_anchor", (1.0 + pad, 0.5))
+    kwargs.setdefault("borderaxespad", 0.0)
+    kwargs.setdefault("ncol", 1)
+    legend = ax.legend(handles, labels, **kwargs)
+    if expand:
+        _expand_figure_for_legend(ax, legend)
+    return legend
+
+
+def legend_below(
+    ax: Axes | None = None,
+    *,
+    per_row: int | None = None,
+    handles: Sequence[Artist] | None = None,
+    labels: Sequence[str] | None = None,
+    pad: float = 0.12,
+    expand: bool = True,
+    **kwargs,
+) -> Legend:
+    """Move the legend below the plot, with *per_row* entries on each row.
+
+    Args:
+        ax: Target axes. Defaults to the current axes (``plt.gca()``).
+        per_row: Number of legend entries per row. Defaults to ``None``,
+            which lays every entry out on a single row.
+        handles: Explicit legend handles. Auto-detected from *ax* when
+            omitted.
+        labels: Explicit legend labels. Auto-detected from *ax* when omitted.
+        pad: Vertical gap between the axes and the legend, as a fraction of
+            axes height (the legend's top edge is anchored at ``-pad``).
+        expand: When ``True`` (default), keep the axes at its current size
+            and grow the figure canvas downward to fit the legend, instead of
+            letting the layout engine shrink the axes. This disables the
+            figure's layout engine (e.g. ``constrained_layout``).
+        **kwargs: Forwarded to ``Axes.legend`` (e.g. ``title``, ``fontsize``).
+
+    Returns:
+        The created ``matplotlib.legend.Legend``.
+    """
+    ax = _resolve_ax(ax)
+    handles, labels = _resolve_handles_labels(ax, handles, labels)
+    if per_row is None:
+        # Honor an explicit ncol if given; otherwise spread all entries on one row.
+        per_row = kwargs.pop("ncol", None) or len(labels) or 1
+    else:
+        kwargs.pop("ncol", None)
+    kwargs.setdefault("loc", "upper center")
+    kwargs.setdefault("bbox_to_anchor", (0.5, -pad))
+    kwargs.setdefault("borderaxespad", 0.0)
+    kwargs["ncol"] = max(1, int(per_row))
+    legend = ax.legend(handles, labels, **kwargs)
+    if expand:
+        _expand_figure_for_legend(ax, legend)
+    return legend