tesorotools-python 0.0.47__tar.gz → 0.0.48__tar.gz

{tesorotools_python-0.0.47 → tesorotools_python-0.0.48}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tesorotools-python
-Version: 0.0.47
+Version: 0.0.48
 Requires-Python: >=3.13
 Requires-Dist: babel>=2.17
 Requires-Dist: matplotlib>=3.10

{tesorotools_python-0.0.47 → tesorotools_python-0.0.48}/pyproject.toml

@@ -54,12 +54,25 @@ artifacts = ["src/tesorotools/assets/fonts/*.otf"]
 include = ["src/tesorotools"]
 artifacts = ["src/tesorotools/assets/fonts/*.otf"]
 
+[tool.coverage.run]
+source = ["tesorotools"]
+# Único módulo excluido: el cliente LSEG/Refinitiv es un wrapper de un SDK
+# externo propietario (`import lseg.data`) que necesita sesión y credenciales
+# en vivo; cubrirlo al 100% exigiría mocks frágiles atados a la API del SDK.
+# Todo lo demás (incluida la resolución de dependencias de series derivadas)
+# se cubre con tests reales.
+omit = ["*/providers/lseg.py"]
+
 [tool.coverage.report]
 exclude_lines = [
+    'pragma: no cover',
     'if __name__ == "__main__"',
     '^\s*\.\.\.$',
     'if TYPE_CHECKING',
+    'raise NotImplementedError',
+    '@(abc\.)?abstractmethod',
 ]
+fail_under = 100
 
 [tool.ruff]
 line-length = 80

{tesorotools_python-0.0.47 → tesorotools_python-0.0.48}/src/tesorotools/artists/__init__.py

@@ -1,7 +1,8 @@
 """Image artists.
 
-Five chart classes, one shared helpers module, one
-matplotlib stylesheet side effect on import.
+Five chart classes and one shared helpers module.  Importing
+``_common`` applies the house style (palette + fonts) as a side
+effect, so the cycle is active no matter which artist is imported.
 
 Each class follows the same shape:
 
@@ -24,8 +25,6 @@ live under :mod:`tesorotools.render`; this package is
 strictly image output.
 """
 
-import matplotlib.style
-
 from tesorotools.artists._common import Artist, Format, Legend
 from tesorotools.artists.barh_plot import GroupedBarChart, HorizontalBarChart
 from tesorotools.artists.line_plot import LinePlot
@@ -34,9 +33,6 @@ from tesorotools.artists.stacked import StackedAreaPlot, StackedBarPlot
 from tesorotools.artists.type_curve import TypeCurve
 from tesorotools.artists.vector_plot import VectorPlot
 from tesorotools.artists.waterfall import Waterfall
-from tesorotools.utils.globals import STYLE_SHEET
-
-matplotlib.style.use(STYLE_SHEET)
 
 __all__ = [
     "Artist",

{tesorotools_python-0.0.47 → tesorotools_python-0.0.48}/src/tesorotools/artists/_common.py

@@ -33,28 +33,60 @@ from matplotlib.dates import AutoDateLocator, ConciseDateFormatter
 from matplotlib.dates import (
     date2num,  # type: ignore[reportUnknownVariableType]
 )
+from matplotlib.dates import (
+    num2date,  # type: ignore[reportUnknownVariableType]
+)
 from matplotlib.figure import Figure
 from matplotlib.font_manager import FontProperties
 from matplotlib.legend import Legend as MplLegend
-from matplotlib.ticker import FixedLocator, FuncFormatter
+from matplotlib.ticker import FixedLocator, FuncFormatter, MaxNLocator
 from yaml.nodes import MappingNode
 
 from tesorotools.utils.matplotlib import (
     PLOT_CONFIG,
+    apply_house_style,
     format_annotation,
-    load_fonts,
 )
 from tesorotools.utils.template import TemplateLoader
 
-load_fonts()
+# Apply the full house look (colour cycle + grid + tick sizes from the
+# stylesheet, then the bundled fonts) once, here at import: every image
+# artist imports this module, so the cycle is active no matter which
+# artist (or caller) triggers the import first.
+apply_house_style()
 
 AX_CONFIG: dict[str, Any] = PLOT_CONFIG["ax"]
 FIG_CONFIG: dict[str, Any] = PLOT_CONFIG["figure"]
 COMPACT_CONFIG: dict[str, Any] = PLOT_CONFIG.get("compact", {})
+SAVE_CONFIG: dict[str, Any] = PLOT_CONFIG.get("save", {})
 
 CM_TO_IN: float = 1.0 / 2.54
 
 
+def dynamic_dpi(fig: Figure) -> int:
+    """Save DPI adapted to the figure's physical size.
+
+    The figure DPI (``figure.dpi`` in ``plots.yaml``) drives *layout* and
+    is deliberately high; saving every PNG at it wastes memory on large
+    figures (a 16 cm chart at 500 dpi is ~3150 px wide).  Instead the save
+    DPI scales **inversely with size** so the long side lands near
+    ``save.target_px`` pixels: big figures save at fewer dpi (lighter
+    files), small ones at more.  It is clamped to ``[save.min_dpi,
+    figure.dpi]`` -- never below ``save.min_dpi`` (so the result is always
+    print-sharp, never pixelated) and never above the layout dpi (above
+    which extra pixels are pure waste).
+    """
+    target_px: float = float(SAVE_CONFIG.get("target_px", 2000))
+    min_dpi: float = float(SAVE_CONFIG.get("min_dpi", 300))
+    max_dpi: float = float(FIG_CONFIG.get("dpi", 500))
+    width_in, height_in = (float(v) for v in fig.get_size_inches())
+    long_in = max(width_in, height_in)
+    if long_in <= 0:  # pragma: no cover - defensive: a real figure
+        # never has a zero/negative side; guards against a 0/0 division.
+        return int(max_dpi)
+    return int(round(min(max_dpi, max(min_dpi, target_px / long_in))))
+
+
 # ----------------------------------------------------------------------
 # Structural contract for image artists
 # ----------------------------------------------------------------------
@@ -224,6 +256,11 @@ def auto_ncol(
     ax: Axes,
     labels: list[str],
     available_width_px: float | None = None,
+    *,
+    fontsize: float | None = None,
+    handlelength: float | None = None,
+    handletextpad: float | None = None,
+    columnspacing: float | None = None,
 ) -> int:
     """Choose the maximum legend ``ncol`` that fits the axes.
 
@@ -236,6 +273,12 @@ def auto_ncol(
     Pass ``available_width_px`` when the legend will live in
     ``fig.legend`` (figure-wide space) instead of
     ``ax.legend``; defaults to the axes width.
+
+    The keyword overrides (``fontsize`` / ``handlelength`` /
+    ``handletextpad`` / ``columnspacing``) let a caller measure
+    against a legend styled differently from ``rcParams`` -- the
+    compact mode passes its smaller legend font and shorter
+    handles here so the column count matches what is drawn.
     """
     fig = ax.get_figure()
     if fig is None:
@@ -245,18 +288,35 @@ def auto_ncol(
     if available_width_px is None:
         available_width_px = ax.get_window_extent(renderer).width  # type: ignore[reportUnknownArgumentType]
 
-    fontsize_pt: float = FontProperties(
-        size=plt.rcParams["legend.fontsize"]
-    ).get_size_in_points()
+    legend_fs: Any = (
+        fontsize if fontsize is not None else plt.rcParams["legend.fontsize"]
+    )
+    hl: float = (
+        handlelength
+        if handlelength is not None
+        else float(plt.rcParams["legend.handlelength"])
+    )
+    htp: float = (
+        handletextpad
+        if handletextpad is not None
+        else float(plt.rcParams["legend.handletextpad"])
+    )
+    cs: float = (
+        columnspacing
+        if columnspacing is not None
+        else float(plt.rcParams["legend.columnspacing"])
+    )
+
+    fontsize_pt: float = FontProperties(size=legend_fs).get_size_in_points()
     fs_px: float = fontsize_pt * fig.dpi / 72.0
-    handle_px: float = float(plt.rcParams["legend.handlelength"]) * fs_px
-    pad_px: float = float(plt.rcParams["legend.handletextpad"]) * fs_px
-    col_pad_px: float = float(plt.rcParams["legend.columnspacing"]) * fs_px
+    handle_px: float = hl * fs_px
+    pad_px: float = htp * fs_px
+    col_pad_px: float = cs * fs_px
 
     max_label_px = 0.0
     for label in labels:
         t = ax.text(  # type: ignore[reportUnknownMemberType]
-            0, 0, label
+            0, 0, label, fontsize=legend_fs
         )
         bbox = t.get_window_extent(renderer)  # type: ignore[reportUnknownArgumentType]
         max_label_px = max(max_label_px, bbox.width)
@@ -334,6 +394,92 @@ def compact_font_pt() -> float | None:
     return None if raw is None else float(raw)
 
 
+def compact_legend_font_pt() -> float:
+    """Font size (points) for the compact legend -- never ``None``.
+
+    Falls back ``legend_font_pt`` -> ``font_pt`` -> ``9`` so the legend
+    never silently reverts to the stylesheet's body size (the original
+    "11 pt legend" bug): the legend must be measured and drawn at the
+    same, smaller size for the column count to be right.
+    """
+    return float(
+        COMPACT_CONFIG.get("legend_font_pt", COMPACT_CONFIG.get("font_pt", 9))
+    )
+
+
+def compact_legend_kwargs() -> dict[str, Any]:
+    """Legend styling for compact charts, from the ``compact`` config.
+
+    Returns ``fontsize`` / ``handlelength`` / ``handletextpad`` /
+    ``columnspacing`` as concrete values (never ``None``), so the metrics
+    used to *measure* the column count in :func:`auto_ncol` match exactly
+    the metrics used to *draw* the legend in :func:`legend_above` -- the
+    invariant that prevents an over-counted ``ncol``.  The smaller font
+    and shorter handles let several wide labels share one legend row.
+    """
+    return {
+        "fontsize": compact_legend_font_pt(),
+        "handlelength": float(COMPACT_CONFIG.get("legend_handlelength", 1.2)),
+        "handletextpad": float(COMPACT_CONFIG.get("legend_handletextpad", 0.4)),
+        "columnspacing": float(COMPACT_CONFIG.get("legend_columnspacing", 0.8)),
+    }
+
+
+def compact_legend_max_ncol() -> int | None:
+    """Hard cap on the compact legend column count (``None`` if unset)."""
+    raw: Any = COMPACT_CONFIG.get("legend_max_ncol")
+    return None if raw is None else int(raw)
+
+
+def compact_headroom_pad_pt() -> float:
+    """Points of clearance to leave above the top value label (0 if unset)."""
+    return float(COMPACT_CONFIG.get("annotate_headroom_pad_pt", 0))
+
+
+class _StartLabeledConcise(ConciseDateFormatter):
+    """``ConciseDateFormatter`` that spells out the first (start) tick.
+
+    When the compact date axis pins the first datum as the leading tick
+    (see :func:`compact_date_axis`) that date is rarely a clean month
+    boundary, so the concise formatter would label it with a bare day
+    number (e.g. ``31``).  This subclass relabels just that tick so the
+    chart's origin is unambiguous: a January start shows the **year only**
+    (``2020`` -- narrow, like the other year ticks), any other month shows
+    ``month year`` (``jul. 2020``).  Every other tick keeps the concise
+    label.
+    """
+
+    def __init__(self, locator: Any, start_num: float) -> None:
+        # show_offset=False: don't append the trailing "year-month" offset
+        # text (it duplicated the month of the last tick, e.g. "jul." plus
+        # "2026-jul."). With it off, ConciseDateFormatter shows the year
+        # inline at year-boundary ticks instead.
+        super().__init__(  # type: ignore[reportUnknownMemberType]
+            locator, show_offset=False
+        )
+        self._start_num = start_num
+
+    def format_ticks(self, values: Any) -> Any:
+        labels: list[str] = list(super().format_ticks(values))
+        for i, value in enumerate(values):
+            moment = num2date(value)
+            if abs(float(value) - self._start_num) < 0.5:  # within half a day
+                if moment.month == 1:
+                    # January start: the year alone is unambiguous and narrow,
+                    # so it won't collide with the next (year) tick.
+                    labels[i] = str(moment.year)
+                else:
+                    # locale's %b may already carry a trailing dot ("ene.");
+                    # strip it so we don't end up with "jul.. 2020".
+                    month = moment.strftime("%b").lower().rstrip(".")
+                    labels[i] = f"{month}. {moment.year}"
+            elif moment.month == 1:
+                # year boundary: show the year ("2026") instead of "ene." so
+                # the reader sees the year change without a trailing offset.
+                labels[i] = str(moment.year)
+        return labels
+
+
 def compact_date_axis(
     ax: Axes,
     data_min: Any,
@@ -341,15 +487,18 @@ def compact_date_axis(
     *,
     maxticks: int = 4,
 ) -> None:
-    """Compact date x-axis: few horizontal ticks, last one near the data end.
+    """Compact date x-axis: few horizontal ticks, anchored to the data span.
 
     Ticks are computed over the **data span** ``[data_min,
     data_max]`` and pinned with a ``FixedLocator``, so none
     float in the right-hand margin that the value labels open
     up -- the last tick lands as close to the final data
-    point as the tick step allows.  Requires the series to
-    have been plotted with ``x_compat=True`` (pandas' own
-    date plotting ignores this formatter).
+    point as the tick step allows.  When ``compact.date_show_start``
+    is true (the default) the first data point is pinned as the
+    leading tick, so the reader can see exactly when the series
+    begins.  Requires the series to have been plotted with
+    ``x_compat=True`` (pandas' own date plotting ignores this
+    formatter).
     """
     lo: float = float(cast(Any, date2num(data_min)))
     hi: float = float(cast(Any, date2num(data_max)))
@@ -357,19 +506,80 @@ def compact_date_axis(
     candidates: list[float] = cast(
         "list[float]", locator.tick_values(data_min, data_max)
     )
-    ticks: list[float] = [t for t in candidates if lo <= t <= hi]
-    if not ticks:
-        ticks = [lo, hi]
-    fixed = FixedLocator(ticks)
-    ax.xaxis.set_major_locator(fixed)
-    ax.xaxis.set_major_formatter(ConciseDateFormatter(fixed))
+    interior: list[float] = [t for t in candidates if lo < t <= hi]
+    if COMPACT_CONFIG.get("date_show_start", True):
+        # pin the first data point as the leading tick so the reader sees
+        # exactly when the series starts (the natural calendar tick often
+        # falls just *before* the first datum and is clipped by margins=0).
+        # Drop any auto tick that would crowd the start label.
+        min_gap: float = (hi - lo) * 0.10
+        interior = [t for t in interior if t - lo >= min_gap]
+        ticks: list[float] = [lo, *interior]
+    else:
+        ticks = [t for t in candidates if lo <= t <= hi] or [lo, hi]
+    show_start = bool(COMPACT_CONFIG.get("date_show_start", True))
+
+    def _set_ticks(values: list[float]) -> None:
+        loc = FixedLocator(values)
+        ax.xaxis.set_major_locator(loc)
+        ax.xaxis.set_major_formatter(
+            _StartLabeledConcise(loc, lo)
+            if show_start
+            else ConciseDateFormatter(loc)
+        )
+
+    _set_ticks(ticks)
     ax.tick_params(  # type: ignore[reportUnknownMemberType]
         axis="x", rotation=0
     )
+
+    # A priori de-overlap: render the labels, measure their boxes, and drop
+    # any tick whose label would collide with the previous kept one (the
+    # start tick is always kept). Catches a wide start label (e.g. a January
+    # start widened to a year, or "jul. 2020") crowding the next tick.
+    fig = ax.get_figure()
+    if fig is not None and len(ticks) > 1:
+        fig.canvas.draw()  # type: ignore[reportUnknownMemberType]
+        renderer = fig.canvas.get_renderer()  # type: ignore[reportUnknownMemberType]
+        boxes = [
+            lbl.get_window_extent(renderer)  # type: ignore[reportUnknownArgumentType]
+            for lbl in ax.get_xticklabels()
+        ]
+        if len(boxes) == len(ticks):
+            pad_px = 2.0
+            kept: list[float] = [ticks[0]]
+            last_x1: float = boxes[0].x1
+            for tick, box in zip(ticks[1:], boxes[1:]):
+                if box.x0 <= last_x1 + pad_px:
+                    continue  # collides with previous kept label -> drop
+                kept.append(tick)
+                last_x1 = box.x1
+            if len(kept) < len(ticks):
+                _set_ticks(kept)
+
     for label in ax.get_xticklabels():
         label.set_horizontalalignment("center")
 
 
+def compact_y_axis(ax: Axes) -> None:
+    """Denser y-ticks for compact charts (more reference numbers).
+
+    Compact charts are read at body-text size, so Matplotlib's default
+    of a couple of y-numbers on a short axis is too sparse.  Bump the
+    count to ``compact.y_max_ticks`` "nice" steps (1/2/2.5/5/10 decades)
+    so the reader gets more gridline references -- e.g. every 20 instead
+    of every 50.  Leaves the default locator untouched when the knob is
+    unset, and never changes the y-tick *formatter* set by
+    :func:`style_spines`.
+    """
+    raw: Any = COMPACT_CONFIG.get("y_max_ticks")
+    if raw is None:
+        return
+    ax.yaxis.set_major_locator(
+        MaxNLocator(nbins=int(raw), steps=[1, 2, 2.5, 5, 10])
+    )
+
+
 def legend_above(
     ax: Axes,
     handles: list[Any],
@@ -377,26 +587,35 @@ def legend_above(
     *,
     ncol: int,
     fontsize: float | None = None,
+    handlelength: float | None = None,
+    handletextpad: float | None = None,
+    columnspacing: float | None = None,
 ) -> MplLegend:
-    """Place the legend **above** the axes, expanded to its full width.
-
-    Uses ``mode="expand"`` so the legend spans exactly the
-    plot width (never wider) and ``bbox_to_anchor`` from the
-    ``compact`` config (default ``(0, 1.06, 1, 0.12)`` -- the
-    ``y0 > 1`` lifts it clear of the axes).  The legend
-    becomes a child of the axes, so constrained layout
-    reserves room for it inside the fixed compact figure.
+    """Place the legend in a band **above the axes, spanning the figure**.
+
+    Uses ``loc="outside upper center"`` so constrained layout reserves a
+    strip at the top of the *figure* and the legend may use the whole
+    figure width -- wider than the narrow compact axes, whose left edge
+    is eaten by the y-tick numbers and whose right edge is eaten by the
+    end-of-series value labels.  Spanning the figure lets the maximum
+    number of columns share one row, which **minimises the vertical
+    space the legend steals from the plot** (fewer rows = taller chart).
+
+    ``fontsize`` / ``handlelength`` / ``handletextpad`` /
+    ``columnspacing`` style the legend (``None`` keeps the
+    ``rcParams`` default); the compact mode passes a smaller
+    font and shorter handles so more labels fit per row.
     """
-    bbox: Any = COMPACT_CONFIG.get("legend_bbox", [0.0, 1.06, 1.0, 0.12])
-    return ax.legend(  # type: ignore[reportUnknownMemberType]
+    fig = ax.get_figure()
+    return fig.legend(  # type: ignore[reportUnknownMemberType, reportOptionalMemberAccess]
         handles,
         labels,
-        loc="lower left",
-        bbox_to_anchor=tuple(bbox),
-        mode="expand",
-        borderaxespad=0.0,
+        loc="outside upper center",
         ncol=ncol,
         fontsize=fontsize,
+        handlelength=handlelength,
+        handletextpad=handletextpad,
+        columnspacing=columnspacing,
         frameon=False,  # no box: less clutter in the tight compact figure
     )
 
@@ -452,13 +671,15 @@ def style_spines(
     ax.tick_params(  # type: ignore[reportUnknownMemberType]
         which="minor", size=0, width=0
     )
+    # Set the tick-mark colour via tick_params (not by recolouring each
+    # Line2D): this stores it in the axis' tick kwargs, so ANY tick
+    # regenerated after this call inherits it. Compact mode swaps in a
+    # denser y-locator later, which rebuilds the tick objects; recolouring
+    # the lines directly here would leave those new ticks the default black
+    # (only the relocated ones would stay grey -- hence a lone black tick).
     ax.tick_params(  # type: ignore[reportUnknownMemberType]
-        axis="both", which="major"
+        axis="both", which="major", color=color
     )
-    for tick in ax.get_xticklines():
-        tick.set_markeredgecolor(color)
-    for tick in ax.get_yticklines():
-        tick.set_markeredgecolor(color)
 
 
 def style_baseline(
@@ -500,6 +721,7 @@ def annotate_last_values(
     weight: str | None = None,
     fontsize: float | None = None,
     right_pad_px: float = 10.0,
+    headroom_pad_pt: float = 0.0,
 ) -> None:
     """Label the last non-NaN value of each column on the right.
 
@@ -520,6 +742,13 @@ def annotate_last_values(
     ``right_pad_px`` (e.g. on compact charts) to open more
     blank space on the right and keep the labels clear of both
     the data lines and the right-hand y-tick labels.
+
+    ``headroom_pad_pt`` is the clearance kept above the top
+    label: if the packed stack would reach past the top
+    y-limit, that limit grows enough to keep this many points
+    free and the labels are re-packed at the new scale, so a
+    tall stack never spills into a legend above the axes (nor
+    is clipped at the top).
     """
     fig = ax.get_figure()
     if fig is None:
@@ -563,14 +792,39 @@ def annotate_last_values(
     sample.remove()
 
     entries.sort(key=lambda e: e[1])
-    placements: list[float] = []
-    prev_y = -float("inf")
-    for _, val, _, _ in entries:
-        y_display: float = trans.transform((0, val))[1]  # type: ignore[reportUnknownArgumentType]
-        if y_display - prev_y < text_height:
-            y_display = prev_y + text_height
-        placements.append(y_display)
-        prev_y = y_display
+
+    def _pack(top_data: float) -> list[float]:
+        # Set the final y-scale BEFORE packing. Spacing is enforced in display
+        # space, so it must be measured at the scale the labels are drawn at;
+        # growing the y-limit *after* packing (the old approach) rescaled the
+        # data points and quietly reopened the overlaps packing should remove.
+        ax.set_ylim(top=top_data)
+        fig.canvas.draw()  # type: ignore[reportUnknownMemberType]
+        packed: list[float] = []
+        prev = -float("inf")
+        for _, value, _, _ in entries:
+            y_disp: float = trans.transform((0, value))[1]  # type: ignore[reportUnknownArgumentType]
+            if y_disp - prev < text_height:
+                y_disp = prev + text_height
+            packed.append(y_disp)
+            prev = y_disp
+        return packed
+
+    _, ymax = ax.get_ylim()
+    placements = _pack(ymax)
+
+    # The stack packs upward; if it reaches past the top y-limit it renders
+    # over the legend (compact, legend above) or is clipped (normal). Grow the
+    # y-limit so the top label keeps headroom_pad_pt of clearance, then RE-PACK
+    # so the spacing is exact at the new (final) scale.
+    pad_px = headroom_pad_pt * fig.dpi / 72.0
+    top_axes_px: float = trans.transform((0, ymax))[1]  # type: ignore[reportUnknownArgumentType]
+    needed_px = placements[-1] + text_height / 2 + pad_px
+    if needed_px > top_axes_px:
+        new_top: float = trans.inverted().transform(  # type: ignore[reportUnknownArgumentType]
+            (0, needed_px)
+        )[1]
+        placements = _pack(new_top)
 
     max_label_width = 0.0
     for (date, val, _, color), packed_y in zip(entries, placements):
@@ -593,7 +847,8 @@ def annotate_last_values(
 
     # labels spill right of the data, so widen the x-limit by the widest
     # label plus right_pad_px to keep them unclipped (and, with a larger
-    # pad, clear of the right-hand y-tick labels).
+    # pad, clear of the right-hand y-tick labels). x is independent of the
+    # y-limit set above, so this stays correct.
     inv = trans.inverted()
     x0: float = inv.transform((0, 0))[0]  # type: ignore[reportUnknownArgumentType]
     x1: float = inv.transform((max_label_width + right_pad_px, 0))[0]  # type: ignore[reportUnknownArgumentType]

{tesorotools_python-0.0.47 → tesorotools_python-0.0.48}/src/tesorotools/artists/barh_plot.py

@@ -36,6 +36,7 @@ from tesorotools.artists._common import (
     Legend,
     adjust_figure_for_plot_size,
     auto_ncol,
+    dynamic_dpi,
     resolve_data,
 )
 from tesorotools.utils.matplotlib import PLOT_CONFIG, format_annotation
@@ -370,7 +371,7 @@ class HorizontalBarChart:
         _style_zero_baseline(ax, **AX_CONFIG["baseline"])
 
         fig.savefig(  # type: ignore[reportUnknownMemberType]
-            self.out_path
+            self.out_path, dpi=dynamic_dpi(fig)
         )
         plt.close(fig)
         return ax
@@ -572,7 +573,7 @@ class GroupedBarChart:
             adjust_figure_for_plot_size(fig, ax, self.plot_size)
 
         fig.savefig(  # type: ignore[reportUnknownMemberType]
-            self.out_path
+            self.out_path, dpi=dynamic_dpi(fig)
         )
         plt.close(fig)
         return ax

{tesorotools_python-0.0.47 → tesorotools_python-0.0.48}/src/tesorotools/artists/line_plot.py

@@ -32,8 +32,13 @@ from tesorotools.artists._common import (
     compact_date_axis,
     compact_figsize,
     compact_font_pt,
+    compact_headroom_pad_pt,
+    compact_legend_kwargs,
+    compact_legend_max_ncol,
+    compact_y_axis,
     declutter_spines,
     draw_vlines,
+    dynamic_dpi,
     legend_above,
     style_baseline,
     style_spines,
@@ -65,6 +70,17 @@ class LinePlot:
       (color, linestyle, ...).
     * ``baseline`` -- draw an axhline at 0 (or 100 when
       ``base_100``).
+    * ``ref_lines`` -- arbitrary horizontal reference lines;
+      a list of dicts ``{"y": float, "label"?: str,
+      "color"?, "linestyle"?, "linewidth"?, "in_legend"?:
+      bool}``. Dashed and above the data by default; an entry
+      with ``in_legend: true`` and a ``label`` also shows in
+      the legend (e.g. a long-run PER mean, a vol threshold).
+    * ``show_means`` / ``means_window`` -- draw each series'
+      historical mean as a dotted same-colour line (the old
+      ``medias=True``); the mean is taken over ``means_window``
+      (a ``(start, end)`` pair) or the whole series. Not
+      meaningful together with ``base_100``.
     * ``compact`` -- render at a fixed physical size (7.4 cm
       wide *including* the legend, from ``plots.yaml``) for
       placing two charts per row inside a Word table. Moves
@@ -99,6 +115,9 @@ class LinePlot:
         plot_size: tuple[float, float] | None = None,
         vlines: list[dict[str, Any]] | None = None,
         compact: bool = False,
+        ref_lines: list[dict[str, Any]] | None = None,
+        show_means: bool = False,
+        means_window: tuple[Any, Any] | None = None,
     ) -> None:
         if out_path.suffix != ".png":
             raise ValueError(f"out_path must be .png: {out_path}")
@@ -121,6 +140,9 @@ class LinePlot:
         self.plot_size = plot_size
         self.vlines = vlines or []
         self.compact = compact
+        self.ref_lines = ref_lines or []
+        self.show_means = show_means
+        self.means_window = means_window
 
     @classmethod
     def from_yaml(cls, loader: TemplateLoader, node: MappingNode) -> Self:
@@ -143,7 +165,8 @@ class LinePlot:
         ``base_100_date``, ``annotate``, ``annotate_color``,
         ``baseline``, ``fmt`` (``!format``), ``legend``
         (``!legend``), ``figsize``, ``series_styles``,
-        ``plot_size``, ``vlines``, ``compact``.
+        ``plot_size``, ``vlines``, ``compact``, ``ref_lines``,
+        ``show_means``, ``means_window``.
 
         Example
         -------
@@ -261,6 +284,9 @@ class LinePlot:
                     if self.compact
                     else 1.6 * plt.rcParams["font.size"] * fig.dpi / 72.0
                 ),
+                headroom_pad_pt=(
+                    compact_headroom_pad_pt() if self.compact else 0.0
+                ),
             )
 
         style_spines(
@@ -273,6 +299,48 @@ class LinePlot:
             reference = 100 if self.base_100 else 0
             style_baseline(ax, reference, **AX_CONFIG["baseline"])
 
+        # arbitrary horizontal reference lines (e.g. a PER long-run mean, a
+        # volatility threshold). Dashed and in front of the data by default;
+        # only those flagged in_legend with a label enter the legend -- they
+        # are picked up automatically by get_legend_handles_labels() below.
+        for ref_line in self.ref_lines:
+            ref_label = ref_line.get("label")
+            in_legend = bool(ref_line.get("in_legend"))
+            ax.axhline(  # type: ignore[reportUnknownMemberType]
+                ref_line["y"],
+                color=ref_line.get("color", AX_CONFIG["baseline"]["color"]),
+                linestyle=ref_line.get("linestyle", "--"),
+                linewidth=ref_line.get("linewidth", 0.9),
+                zorder=2.5,
+                label=ref_label if (in_legend and ref_label) else None,
+            )
+            lo, hi = ax.get_ylim()
+            ax.set_ylim(min(ref_line["y"], lo), max(ref_line["y"], hi))
+
+        # per-series historical mean as a dotted same-colour line (the old
+        # `medias=True`): the mean is taken over means_window (or the whole
+        # series) and scaled to match the plotted axis. Not meaningful with
+        # base_100, where the rebased axis no longer matches the raw mean.
+        if self.show_means:
+            mean_lines = {str(line.get_label()): line for line in ax.lines}
+            for col in plot_data.columns:
+                window: Any = (
+                    self.data[col]
+                    if self.means_window is None
+                    else self.data.loc[slice(*self.means_window), col]
+                )
+                mean_val = float(window.dropna().mean()) * self.scale
+                line = mean_lines.get(self.series[col])
+                color = line.get_color() if line is not None else "black"
+                ax.axhline(  # type: ignore[reportUnknownMemberType]
+                    mean_val,
+                    color=color,
+                    linestyle=":",
+                    linewidth=0.8,
+                    alpha=0.55,
+                    zorder=1,
+                )
+
         if self.compact:
             # pin the date ticks to the data span (after annotate widened the
             # x-limit) so the last tick sits next to the final data point and
@@ -283,33 +351,45 @@ class LinePlot:
             # spines. Normal mode keeps the house right-hand y-axis and box.
             ax.yaxis.tick_left()
             declutter_spines(ax)
+            # denser y-numbers (e.g. every 20 instead of every 50) so the
+            # small chart still has enough reference gridlines.
+            compact_y_axis(ax)
             if font_pt is not None:
                 ax.tick_params(  # type: ignore[reportUnknownMemberType]
                     axis="both", labelsize=font_pt
                 )
 
         if self.legend is not None:
-            labels = [self.series[c] for c in plot_data.columns]
+            # measure and draw from the actual labelled artists, so any
+            # in-legend reference lines are counted in the column fit too.
             handles, label_strs = ax.get_legend_handles_labels()
             if self.compact:
-                # legend ABOVE the plot, expanded to the plot width. ncol is
-                # auto-fitted to the (narrow) axes width so labels never
-                # overlap; long labels stack into rows. Override the column
-                # count via !legend {ncol: N} when you know they fit.
-                ncol = (
-                    self.legend.ncol
-                    if self.legend.ncol is not None
-                    else auto_ncol(ax, labels)
-                )
-                legend_above(
-                    ax, handles, label_strs, ncol=ncol, fontsize=font_pt
-                )
+                # legend in a band ABOVE the plot, spanning the FIGURE width.
+                # ncol is auto-fitted to that full width (not the narrow axes)
+                # with the compact legend metrics (small font, short handles)
+                # so the maximum number of labels share a row -- fewer rows
+                # means the legend steals less height from the chart. Then
+                # hard-capped by legend_max_ncol. Override via !legend {ncol}.
+                legend_kw = compact_legend_kwargs()
+                if self.legend.ncol is not None:
+                    ncol = self.legend.ncol
+                else:
+                    fig_w_px: float = fig.get_size_inches()[0] * fig.dpi
+                    ncol = auto_ncol(
+                        ax, label_strs, available_width_px=fig_w_px, **legend_kw
+                    )
+                    max_ncol = compact_legend_max_ncol()
+                    if max_ncol is not None:
+                        ncol = min(ncol, max_ncol)
+                legend_above(ax, handles, label_strs, ncol=ncol, **legend_kw)
             else:
                 fig_width_px: float = fig.get_size_inches()[0] * fig.dpi
                 ncol = (
                     self.legend.ncol
                     if self.legend.ncol is not None
-                    else auto_ncol(ax, labels, available_width_px=fig_width_px)
+                    else auto_ncol(
+                        ax, label_strs, available_width_px=fig_width_px
+                    )
                 )
                 fig.legend(  # type: ignore[reportUnknownMemberType]
                     handles,
@@ -335,17 +415,16 @@ class LinePlot:
         """Persist *fig* as a PNG and return the path written.
 
         Defaults to ``self.out_path``; pass ``path`` to
-        redirect or ``dpi`` to override the figure DPI for
-        the saved file (useful when embedding in Word at
-        fixed widths, where the default 500 dpi balloons
-        file sizes).
+        redirect.  ``dpi`` overrides the save resolution;
+        when omitted it is derived from the figure size via
+        :func:`dynamic_dpi` (size-adapted, never below the
+        sharpness floor) instead of the high layout DPI, so
+        large figures do not balloon the PNG.
         """
         target: Path = path if path is not None else self.out_path
-        save_kwargs: dict[str, Any] = {}
-        if dpi is not None:
-            save_kwargs["dpi"] = dpi
+        save_dpi: int = dpi if dpi is not None else dynamic_dpi(fig)
         fig.savefig(  # type: ignore[reportUnknownMemberType]
-            target, **save_kwargs
+            target, dpi=save_dpi
         )
         return target
 

{tesorotools_python-0.0.47 → tesorotools_python-0.0.48}/src/tesorotools/artists/matrix.py

@@ -39,7 +39,12 @@ from matplotlib.figure import Figure
 from matplotlib.patches import Rectangle
 from yaml.nodes import MappingNode
 
-from tesorotools.artists._common import FIG_CONFIG, Format, resolve_data
+from tesorotools.artists._common import (
+    FIG_CONFIG,
+    Format,
+    dynamic_dpi,
+    resolve_data,
+)
 from tesorotools.utils.matplotlib import PLOT_CONFIG, format_annotation
 from tesorotools.utils.template import TemplateLoader
 
@@ -246,7 +251,7 @@ class MatrixChart:
 
         self._style_axes(ax, row_ids, col_ids)
         fig.savefig(  # type: ignore[reportUnknownMemberType]
-            self.out_path
+            self.out_path, dpi=dynamic_dpi(fig)
         )
         plt.close(fig)
         return ax

{tesorotools_python-0.0.47 → tesorotools_python-0.0.48}/src/tesorotools/artists/stacked.py

@@ -18,6 +18,7 @@ from tesorotools.artists._common import (
     resolve_data,
     adjust_figure_for_plot_size,
     auto_ncol,
+    dynamic_dpi,
     style_baseline,
     style_spines,
 )
@@ -170,7 +171,7 @@ class StackedAreaPlot:
             adjust_figure_for_plot_size(fig, ax, self.plot_size)
 
         fig.savefig(  # type: ignore[reportUnknownMemberType]
-            self.out_path
+            self.out_path, dpi=dynamic_dpi(fig)
         )
         plt.close(fig)
         return ax
@@ -415,7 +416,7 @@ class StackedBarPlot:
             adjust_figure_for_plot_size(fig, ax, self.plot_size)
 
         fig.savefig(  # type: ignore[reportUnknownMemberType]
-            self.out_path
+            self.out_path, dpi=dynamic_dpi(fig)
         )
         plt.close(fig)
         return ax

{tesorotools_python-0.0.47 → tesorotools_python-0.0.48}/src/tesorotools/artists/type_curve.py

@@ -16,6 +16,7 @@ from tesorotools.artists._common import (
     Format,
     Legend,
     resolve_data,
+    dynamic_dpi,
     style_baseline,
     style_spines,
 )
@@ -259,7 +260,7 @@ class TypeCurve:
             ncol=ncol,
         )
         fig.savefig(  # type: ignore[reportUnknownMemberType]
-            self.out_path
+            self.out_path, dpi=dynamic_dpi(fig)
         )
         plt.close(fig)
         return ax

{tesorotools_python-0.0.47 → tesorotools_python-0.0.48}/src/tesorotools/artists/vector_plot.py

@@ -39,6 +39,7 @@ from tesorotools.artists._common import (
     AX_CONFIG,
     FIG_CONFIG,
     Format,
+    dynamic_dpi,
     resolve_data,
 )
 from tesorotools.utils.matplotlib import PLOT_CONFIG, format_annotation
@@ -260,7 +261,7 @@ class VectorPlot:
 
         self._style_axes(ax, xs, ys)
         fig.savefig(  # type: ignore[reportUnknownMemberType]
-            self.out_path
+            self.out_path, dpi=dynamic_dpi(fig)
         )
         plt.close(fig)
         return ax

{tesorotools_python-0.0.47 → tesorotools_python-0.0.48}/src/tesorotools/artists/waterfall.py

@@ -35,6 +35,7 @@ from tesorotools.artists._common import (
     compact_figsize,
     compact_font_pt,
     declutter_spines,
+    dynamic_dpi,
     resolve_data,
     style_spines,
 )
@@ -304,13 +305,16 @@ class Waterfall:
         path: Path | None = None,
         dpi: int | None = None,
     ) -> Path:
-        """Persist *fig* as a PNG and return the path written."""
+        """Persist *fig* as a PNG and return the path written.
+
+        ``dpi`` overrides the save resolution; when omitted it is
+        derived from the figure size via :func:`dynamic_dpi`
+        (size-adapted, never below the sharpness floor).
+        """
         target: Path = path if path is not None else self.out_path
-        save_kwargs: dict[str, Any] = {}
-        if dpi is not None:
-            save_kwargs["dpi"] = dpi
+        save_dpi: int = dpi if dpi is not None else dynamic_dpi(fig)
         fig.savefig(  # type: ignore[reportUnknownMemberType]
-            target, **save_kwargs
+            target, dpi=save_dpi
         )
         return target
 

{tesorotools_python-0.0.47 → tesorotools_python-0.0.48}/src/tesorotools/assets/plots.yaml

@@ -4,9 +4,18 @@ style:
   font: Cabinet Grotesk
 
 figure:
-  dpi: 500
+  dpi: 500              # DPI de LAYOUT (medidas, px de fuente, ancho de leyenda)
   layout: constrained
 
+# DPI de GUARDADO dinámico: se adapta al tamaño físico de la figura para no
+# malgastar memoria. El lado largo se acota a ~target_px (las figuras grandes
+# se guardan con menos dpi -> ficheros más ligeros), pero nunca por debajo de
+# min_dpi (nitidez de impresión: jamás pixelado) ni por encima del dpi de
+# layout (más píxeles serían desperdicio).
+save:
+  target_px: 2000
+  min_dpi: 300
+
 ax:
   spines:
     color: gray
@@ -75,17 +84,26 @@ line:
 
 # Modo "compact": gráfico pensado para ir dentro de una tabla del Word,
 # dos por fila, a tamaño físico real (sin que Word lo reduzca). El ancho
-# es TOTAL e INCLUYE la leyenda, que se coloca encima expandida al ancho
-# del gráfico. Las dimensiones se interpretan en centímetros.
+# es TOTAL e INCLUYE la leyenda, que se coloca en una banda ENCIMA que
+# abarca el ancho COMPLETO de la figura. Dimensiones en centímetros.
 compact:
   width_cm: 7.4          # ancho total de la figura (gráfico + leyenda)
   height_cm: 5.5         # alto total de la figura
   # Tamaño de letra del gráfico EN PUNTOS. Como la figura se renderiza a su
   # tamaño físico real (7,4 cm) y se embebe sin reducir, estos puntos son los
   # mismos que verá el Word: ponlo IGUAL al texto corrido del documento.
-  font_pt: 11
-  # Leyenda encima, expandida al ancho del gráfico. y0 > 1.0 la separa del eje.
-  legend_bbox: [0.0, 1.06, 1.0, 0.12]   # x0, y0, ancho, alto (coords de ejes)
+  font_pt: 11                  # ticks + etiquetas de valor (tamaño de cuerpo)
+  # Leyenda en banda superior, a ancho de figura. ncol se calcula como el
+  # MÁXIMO de columnas que caben en ese ancho (menos filas = menos espacio
+  # robado al gráfico), topado por legend_max_ncol.
+  legend_font_pt: 9            # leyenda algo MENOR que el texto de cuerpo
+  legend_handlelength: 1.2     # línea de muestra corta: caben más etiquetas/fila
+  legend_handletextpad: 0.4    # hueco línea-texto en la leyenda
+  legend_columnspacing: 0.8    # hueco entre columnas de la leyenda
+  legend_max_ncol: 3           # tope duro de columnas de la leyenda
+  annotate_headroom_pad_pt: 4  # hueco por encima de la etiqueta de valor más alta
+  date_show_start: true        # fija la fecha del primer dato como primer tick X
+  y_max_ticks: 10              # nº máx. de números en el eje Y (más referencias)
 
 table:
   style: Light Shading Accent 1

{tesorotools_python-0.0.47 → tesorotools_python-0.0.48}/src/tesorotools/utils/matplotlib.py

@@ -2,9 +2,10 @@ from typing import Any
 
 import matplotlib
 import matplotlib.font_manager
+import matplotlib.style
 
 from .config import read_config
-from .globals import FONTS, PLOT_CONFIG_FILE
+from .globals import FONTS, PLOT_CONFIG_FILE, STYLE_SHEET
 
 # this should only be done once
 PLOT_CONFIG: dict[str, Any] = read_config(PLOT_CONFIG_FILE)
@@ -17,6 +18,23 @@ def load_fonts() -> None:
     matplotlib.rcParams["font.family"] = PLOT_CONFIG["style"]["font"]
 
 
+def apply_house_style() -> None:
+    """Apply the full tesorotools look: stylesheet first, then fonts.
+
+    ``matplotlib.style.use`` loads the colour cycle (``C0``/``C1``/... =
+    the Tesoro palette), grid and tick sizes from ``tesoro.mplstyle``;
+    :func:`load_fonts` then registers the bundled OTFs and sets
+    ``font.family``.  Fonts are applied **last** so the registered family
+    always wins over any ``font.*`` key the stylesheet might carry.
+
+    Without this the artists only ran :func:`load_fonts`, so the palette
+    cycle was never activated and lines fell back to Matplotlib's default
+    blue/orange unless the caller set colours explicitly.
+    """
+    matplotlib.style.use(str(STYLE_SHEET))
+    load_fonts()
+
+
 # this is not really matplotlib specific, so it should be elsewhere
 def format_annotation(value: float, decimals: int, units: str) -> str:
     decimal_formatted: str = f"{value:_.{decimals}f}".replace(".", ",").replace(