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

{tesorotools_python-0.0.46 → tesorotools_python-0.0.47}/.gitignore

@@ -24,4 +24,6 @@ test/
 .coverage
 
 # ruff
-.ruff_cache/
+.ruff_cache/
+
+demo_compacto/

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

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

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

@@ -54,6 +54,7 @@ from tesorotools.artists import (
     StackedBarPlot,
     TypeCurve,
     VectorPlot,
+    Waterfall,
 )
 from tesorotools.orchestration import CompositeRegistry, iter_contexts
 from tesorotools.providers.base import (
@@ -83,6 +84,7 @@ def _register_builtins() -> None:
     register_artist("type_curve", TypeCurve)
     register_artist("vector_plot", VectorPlot)
     register_artist("matrix", MatrixChart)
+    register_artist("waterfall", Waterfall)
 
     register_tag("format", Format)
     register_tag("legend", Legend)
@@ -127,6 +129,7 @@ __all__ = [
     "Title",
     "TypeCurve",
     "VectorPlot",
+    "Waterfall",
     "YamlConstructor",
     "all_artists",
     "all_providers",

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

@@ -33,6 +33,7 @@ from tesorotools.artists.matrix import MatrixChart
 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)
@@ -49,4 +50,5 @@ __all__ = [
     "StackedBarPlot",
     "TypeCurve",
     "VectorPlot",
+    "Waterfall",
 ]

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

@@ -29,9 +29,14 @@ from typing import Any, Protocol, Self, cast, runtime_checkable
 import matplotlib.pyplot as plt
 import pandas as pd
 from matplotlib.axes import Axes
+from matplotlib.dates import AutoDateLocator, ConciseDateFormatter
+from matplotlib.dates import (
+    date2num,  # type: ignore[reportUnknownVariableType]
+)
 from matplotlib.figure import Figure
 from matplotlib.font_manager import FontProperties
-from matplotlib.ticker import FuncFormatter
+from matplotlib.legend import Legend as MplLegend
+from matplotlib.ticker import FixedLocator, FuncFormatter
 from yaml.nodes import MappingNode
 
 from tesorotools.utils.matplotlib import (
@@ -45,6 +50,9 @@ load_fonts()
 
 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", {})
+
+CM_TO_IN: float = 1.0 / 2.54
 
 
 # ----------------------------------------------------------------------
@@ -295,6 +303,117 @@ def export_legend(
         legend.remove()
 
 
+# ----------------------------------------------------------------------
+# Compact mode (charts that live inside a Word table, two per row)
+# ----------------------------------------------------------------------
+
+
+def compact_figsize() -> tuple[float, float]:
+    """Return the compact figure size ``(width, height)`` in inches.
+
+    The width is the **total** figure width (chart + legend),
+    read from the ``compact`` section of ``plots.yaml`` in
+    centimetres and converted to inches.  Defaults to
+    7.4 cm x 5.5 cm when the config is absent.
+    """
+    width_cm: float = float(COMPACT_CONFIG.get("width_cm", 7.4))
+    height_cm: float = float(COMPACT_CONFIG.get("height_cm", 5.5))
+    return (width_cm * CM_TO_IN, height_cm * CM_TO_IN)
+
+
+def compact_font_pt() -> float | None:
+    """Font size (points) for compact charts, or ``None`` to keep the style.
+
+    Because the compact figure is rendered at its true
+    physical size (7.4 cm) and embedded without rescaling,
+    these points equal the points the reader sees in Word --
+    set ``compact.font_pt`` in ``plots.yaml`` to the document
+    body-text size so chart text matches running text.
+    """
+    raw: Any = COMPACT_CONFIG.get("font_pt")
+    return None if raw is None else float(raw)
+
+
+def compact_date_axis(
+    ax: Axes,
+    data_min: Any,
+    data_max: Any,
+    *,
+    maxticks: int = 4,
+) -> None:
+    """Compact date x-axis: few horizontal ticks, last one near the data end.
+
+    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).
+    """
+    lo: float = float(cast(Any, date2num(data_min)))
+    hi: float = float(cast(Any, date2num(data_max)))
+    locator = AutoDateLocator(minticks=2, maxticks=maxticks)
+    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))
+    ax.tick_params(  # type: ignore[reportUnknownMemberType]
+        axis="x", rotation=0
+    )
+    for label in ax.get_xticklabels():
+        label.set_horizontalalignment("center")
+
+
+def legend_above(
+    ax: Axes,
+    handles: list[Any],
+    labels: list[str],
+    *,
+    ncol: int,
+    fontsize: 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.
+    """
+    bbox: Any = COMPACT_CONFIG.get("legend_bbox", [0.0, 1.06, 1.0, 0.12])
+    return ax.legend(  # type: ignore[reportUnknownMemberType]
+        handles,
+        labels,
+        loc="lower left",
+        bbox_to_anchor=tuple(bbox),
+        mode="expand",
+        borderaxespad=0.0,
+        ncol=ncol,
+        fontsize=fontsize,
+        frameon=False,  # no box: less clutter in the tight compact figure
+    )
+
+
+def declutter_spines(ax: Axes) -> None:
+    """Hide the spines that carry no ticks (top and right).
+
+    Compact line charts move the y-ticks to the **left** (so
+    the right edge is free for the end-of-series value labels)
+    and keep x-ticks on the bottom, leaving the top and right
+    spines as pure clutter -- drop them to free space and
+    reduce visual noise.
+    """
+    ax.spines["top"].set_visible(False)
+    ax.spines["right"].set_visible(False)
+
+
 # ----------------------------------------------------------------------
 # Cartesian (vertical-y) styling
 # ----------------------------------------------------------------------
@@ -378,6 +497,9 @@ def annotate_last_values(
     labels: dict[str, str] | None = None,
     series_styles: dict[str, dict[str, Any]] | None = None,
     annotate_color: str | None = None,
+    weight: str | None = None,
+    fontsize: float | None = None,
+    right_pad_px: float = 10.0,
 ) -> None:
     """Label the last non-NaN value of each column on the right.
 
@@ -392,8 +514,12 @@ def annotate_last_values(
 
     Labels are packed vertically in display space so that
     series ending at nearly the same value do not overlap.
-    The x-axis limit is extended by the widest label so
-    the text is not clipped by the axes frame.
+    They sit just right of the last point and the x-axis
+    limit is extended by the widest label plus ``right_pad_px``
+    so the text is not clipped by the axes frame; raise
+    ``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.
     """
     fig = ax.get_figure()
     if fig is None:
@@ -428,7 +554,7 @@ def annotate_last_values(
     trans = ax.transData
 
     sample = ax.text(  # type: ignore[reportUnknownMemberType]
-        0, 0, "0"
+        0, 0, "0", fontsize=fontsize
     )
     text_height = (
         sample.get_window_extent(renderer).height  # type: ignore[reportUnknownArgumentType]
@@ -459,13 +585,18 @@ def annotate_last_values(
             color=color,
             va="center",
             ha="left",
+            fontweight=weight if weight is not None else "normal",
+            fontsize=fontsize,
         )
         width = t.get_window_extent(renderer).width  # type: ignore[reportUnknownArgumentType]
         max_label_width = max(max_label_width, width)
 
+    # 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).
     inv = trans.inverted()
     x0: float = inv.transform((0, 0))[0]  # type: ignore[reportUnknownArgumentType]
-    x1: float = inv.transform((max_label_width + 10, 0))[0]  # type: ignore[reportUnknownArgumentType]
+    x1: float = inv.transform((max_label_width + right_pad_px, 0))[0]  # type: ignore[reportUnknownArgumentType]
     xmin, xmax = ax.get_xlim()
     ax.set_xlim(xmin, xmax + (x1 - x0))
 

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

@@ -29,7 +29,12 @@ from tesorotools.artists._common import (
     adjust_figure_for_plot_size,
     annotate_last_values,
     auto_ncol,
+    compact_date_axis,
+    compact_figsize,
+    compact_font_pt,
+    declutter_spines,
     draw_vlines,
+    legend_above,
     style_baseline,
     style_spines,
 )
@@ -60,6 +65,12 @@ class LinePlot:
       (color, linestyle, ...).
     * ``baseline`` -- draw an axhline at 0 (or 100 when
       ``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
+      the legend above the plot expanded to its width, uses a
+      ``ConciseDateFormatter`` date axis and bold end-of-series
+      labels.
 
     Render lifecycle: ``build()`` returns ``(Figure, Axes)``
     in memory; ``save(fig)`` persists to ``out_path``;
@@ -87,6 +98,7 @@ class LinePlot:
         series_styles: dict[str, dict[str, Any]] | None = None,
         plot_size: tuple[float, float] | None = None,
         vlines: list[dict[str, Any]] | None = None,
+        compact: bool = False,
     ) -> None:
         if out_path.suffix != ".png":
             raise ValueError(f"out_path must be .png: {out_path}")
@@ -108,6 +120,7 @@ class LinePlot:
         self.series_styles = series_styles or {}
         self.plot_size = plot_size
         self.vlines = vlines or []
+        self.compact = compact
 
     @classmethod
     def from_yaml(cls, loader: TemplateLoader, node: MappingNode) -> Self:
@@ -130,7 +143,7 @@ class LinePlot:
         ``base_100_date``, ``annotate``, ``annotate_color``,
         ``baseline``, ``fmt`` (``!format``), ``legend``
         (``!legend``), ``figsize``, ``series_styles``,
-        ``plot_size``, ``vlines``.
+        ``plot_size``, ``vlines``, ``compact``.
 
         Example
         -------
@@ -199,13 +212,30 @@ class LinePlot:
         fig_kw = dict(FIG_CONFIG)
         if self.figsize is not None:
             fig_kw["figsize"] = self.figsize
+        elif self.compact:
+            fig_kw["figsize"] = compact_figsize()
         fig: Figure = plt.figure(  # type: ignore[reportUnknownMemberType]
             **fig_kw
         )
+        font_pt = compact_font_pt() if self.compact else None
+
         ax = fig.add_subplot()
         for col in plot_data.columns:
             style = self.series_styles.get(col, {})
-            plot_data[col].plot(ax=ax, label=self.series[col], **style)
+            # compact mode needs matplotlib's native date axis so the
+            # ConciseDateFormatter takes effect (x_compat disables pandas'
+            # own date plotting machinery).
+            plot_data[col].plot(
+                ax=ax,
+                label=self.series[col],
+                x_compat=self.compact,
+                **style,
+            )
+
+        if self.compact:
+            # no left/right padding: the line starts exactly at the first
+            # data point. annotate_last_values reopens room on the right.
+            ax.margins(x=0)
 
         if self.vlines:
             draw_vlines(ax, self.vlines)
@@ -219,6 +249,18 @@ class LinePlot:
                 labels=self.series,
                 series_styles=self.series_styles,
                 annotate_color=self.annotate_color,
+                weight="bold" if self.compact else None,
+                fontsize=font_pt,
+                # blank space (dynamic, scales with font + dpi) opened past
+                # the label. compact has the y-axis on the LEFT, so half an em
+                # of clearance is enough; normal keeps the y-axis on the RIGHT,
+                # so leave a wider gap to separate the value labels from the
+                # y-tick numbers they would otherwise butt against.
+                right_pad_px=(
+                    0.5 * (font_pt or 12.0) * fig.dpi / 72.0
+                    if self.compact
+                    else 1.6 * plt.rcParams["font.size"] * fig.dpi / 72.0
+                ),
             )
 
         style_spines(
@@ -231,23 +273,54 @@ class LinePlot:
             reference = 100 if self.base_100 else 0
             style_baseline(ax, reference, **AX_CONFIG["baseline"])
 
+        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
+            # none float in the value-label margin; match Word's body font.
+            compact_date_axis(ax, plot_data.index.min(), plot_data.index.max())
+            # compact only: y-numbers on the LEFT so the right edge is free
+            # for the value labels, and drop the now-tickless top/right
+            # spines. Normal mode keeps the house right-hand y-axis and box.
+            ax.yaxis.tick_left()
+            declutter_spines(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]
             handles, label_strs = ax.get_legend_handles_labels()
-            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)
-            )
-            fig.legend(  # type: ignore[reportUnknownMemberType]
-                handles,
-                label_strs,
-                loc="outside lower center",
-                ncol=ncol,
-            )
+            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
+                )
+            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)
+                )
+                fig.legend(  # type: ignore[reportUnknownMemberType]
+                    handles,
+                    label_strs,
+                    loc="outside lower center",
+                    ncol=ncol,
+                )
 
-        if self.plot_size is not None:
+        # compact mode fixes the *figure* size (width includes the legend),
+        # so the axes-sizing pass would fight it; skip it there.
+        if self.plot_size is not None and not self.compact:
             adjust_figure_for_plot_size(fig, ax, self.plot_size)
 
         return fig, ax

tesorotools_python-0.0.47/src/tesorotools/artists/waterfall.py

@@ -0,0 +1,322 @@
+"""Waterfall (bridge) chart artist.
+
+Defines :class:`Waterfall`, registered as ``!waterfall``.  A
+waterfall shows how an initial absolute total is bridged to a
+final absolute total through a sequence of signed
+contributions: the first and last bars rise from zero
+(``start_color`` / ``end_color``), the intermediate bars
+float between running cumulatives (``increase_color`` /
+``decrease_color``).
+
+Like :class:`LinePlot` it exposes ``build()`` / ``save()`` /
+``plot()`` and honours ``compact`` for charts that go two per
+row inside a Word table, reusing the shared compact helpers in
+:mod:`tesorotools.artists._common`.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Self
+
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+from matplotlib.axes import Axes
+from matplotlib.colors import to_rgba
+from matplotlib.figure import Figure
+from yaml.nodes import MappingNode
+
+from tesorotools.artists._common import (
+    AX_CONFIG,
+    FIG_CONFIG,
+    Format,
+    adjust_figure_for_plot_size,
+    compact_figsize,
+    compact_font_pt,
+    declutter_spines,
+    resolve_data,
+    style_spines,
+)
+from tesorotools.utils.matplotlib import PLOT_CONFIG, format_annotation
+from tesorotools.utils.template import TemplateLoader
+
+__all__ = ["Waterfall"]
+
+WATERFALL_CONFIG: dict[str, Any] = PLOT_CONFIG.get("waterfall", {})
+
+
+class Waterfall:
+    """Waterfall / bridge chart with the tesorotools visual style.
+
+    The input is a single column of values indexed by category
+    label (e.g. ``1-1-25``, ``Consumo``, ..., ``19-6-26``).
+    Entries listed in ``totals`` are drawn as absolute bars
+    from zero; the rest are signed deltas that float on the
+    running cumulative.  ``totals`` defaults to the first and
+    last categories (opening and closing balance).
+    """
+
+    def __init__(
+        self,
+        out_path: Path,
+        *,
+        data: pd.DataFrame | None = None,
+        data_path: Path | None = None,
+        value_col: str | None = None,
+        labels: dict[str, str] | None = None,
+        totals: list[str] | None = None,
+        scale: float = 1,
+        annotate: bool = True,
+        fmt: Format | None = None,
+        figsize: tuple[float, float] | None = None,
+        plot_size: tuple[float, float] | None = None,
+        compact: bool = False,
+        bar_width: float | None = None,
+        connectors: bool = False,
+        x_rotation: float = 45,
+    ) -> None:
+        if out_path.suffix != ".png":
+            raise ValueError(f"out_path must be .png: {out_path}")
+        self.out_path = out_path
+        self.data = resolve_data(data, data_path)
+        self.value_col = value_col
+        self.labels = labels or {}
+        self.totals = totals
+        self.scale = scale
+        self.annotate = annotate
+        self.fmt = fmt or Format()
+        self.figsize = figsize
+        self.plot_size = plot_size
+        self.compact = compact
+        self.bar_width = (
+            bar_width
+            if bar_width is not None
+            else float(WATERFALL_CONFIG.get("bar_width", 0.8))
+        )
+        self.connectors = connectors
+        self.x_rotation = x_rotation
+
+    @classmethod
+    def from_yaml(cls, loader: TemplateLoader, node: MappingNode) -> Self:
+        """Build a :class:`Waterfall` from the ``!waterfall`` YAML tag.
+
+        Required keys
+        -------------
+        ``out_path``
+            ``.png`` destination path.
+        ``data_path``
+            ``.feather`` file with a category-indexed DataFrame;
+            the value column is ``value_col`` or the first column.
+
+        Optional keys (forwarded to ``__init__``)
+        -----------------------------------------
+        ``value_col``, ``labels`` (``id -> display label``),
+        ``totals`` (category labels drawn from zero; default
+        first & last), ``scale``, ``annotate``, ``fmt``
+        (``!format``), ``figsize``, ``plot_size``, ``compact``,
+        ``bar_width``, ``connectors``, ``x_rotation``.
+
+        Example
+        -------
+        .. code-block:: yaml
+
+            cartera: !waterfall
+              out_path: out/cartera.png
+              data_path: data/cartera.feather
+              fmt: !format {decimals: 0}
+              compact: true
+        """
+        cfg: dict[str, Any] = loader.construct_mapping(  # type: ignore[assignment]
+            node, deep=True
+        )
+        cfg.pop("id")
+        cfg["out_path"] = Path(cfg["out_path"])
+        if "data_path" in cfg:
+            cfg["data_path"] = Path(cfg["data_path"])
+        return cls(**cfg)
+
+    def build(self) -> tuple[Figure, Axes]:
+        """Render the waterfall in memory and return ``(Figure, Axes)``."""
+        col = (
+            self.value_col
+            if self.value_col is not None
+            else (self.data.columns[0])
+        )
+        values = self.data[col].to_numpy(dtype=np.float64) * self.scale
+        cats = [str(idx) for idx in self.data.index]
+        display = [self.labels.get(c, c) for c in cats]
+        n = len(values)
+
+        totals = (
+            set(self.totals) if self.totals is not None else {cats[0], cats[-1]}
+        )
+        is_total = [c in totals for c in cats]
+
+        # bottoms/tops of each bar plus the cumulative *after* each bar (the
+        # height the connector line should hop from).
+        bottoms = np.zeros(n)
+        tops = np.zeros(n)
+        running_after = np.zeros(n)
+        running = 0.0
+        for i in range(n):
+            if is_total[i]:
+                bottoms[i], tops[i] = 0.0, values[i]
+                running = values[i]
+            else:
+                start, end = running, running + values[i]
+                bottoms[i], tops[i] = min(start, end), max(start, end)
+                running = end
+            running_after[i] = running
+        heights = tops - bottoms
+
+        # Totals use full-opacity cycle colours; the floating deltas use cycle
+        # colours faded by light_alpha (a light tint of the same palette).
+        start_color = WATERFALL_CONFIG.get("start_color", "C1")
+        end_color = WATERFALL_CONFIG.get("end_color", "C0")
+        inc_color = WATERFALL_CONFIG.get("increase_color", "C0")
+        dec_color = WATERFALL_CONFIG.get("decrease_color", "C9")
+        light_alpha = float(WATERFALL_CONFIG.get("light_alpha", 0.35))
+        colors: list[Any] = []
+        for i in range(n):
+            if i == 0:
+                colors.append(to_rgba(start_color))
+            elif i == n - 1 or is_total[i]:
+                colors.append(to_rgba(end_color))
+            else:
+                base = inc_color if values[i] >= 0 else dec_color
+                colors.append(to_rgba(base, light_alpha))
+
+        font_pt = compact_font_pt() if self.compact else None
+
+        fig_kw = dict(FIG_CONFIG)
+        if self.figsize is not None:
+            fig_kw["figsize"] = self.figsize
+        elif self.compact:
+            fig_kw["figsize"] = compact_figsize()
+        fig: Figure = plt.figure(  # type: ignore[reportUnknownMemberType]
+            **fig_kw
+        )
+        ax: Axes = fig.add_subplot()
+
+        x = np.arange(n)
+        ax.bar(  # type: ignore[reportUnknownMemberType]
+            x, heights, bottom=bottoms, width=self.bar_width, color=colors
+        )
+
+        if self.connectors:
+            conn = WATERFALL_CONFIG.get("connector_color", "#bcbcbc")
+            for i in range(n - 1):
+                ax.plot(  # type: ignore[reportUnknownMemberType]
+                    [i + self.bar_width / 2, i + 1 - self.bar_width / 2],
+                    [running_after[i], running_after[i]],
+                    color=conn,
+                    linewidth=0.8,
+                    zorder=0,
+                )
+
+        if self.annotate:
+            # at 7.4 cm the per-delta labels collide horizontally, so compact
+            # charts label only the opening/closing totals (the bars and the
+            # y-axis already convey the steps).
+            self._annotate_bars(
+                ax,
+                x,
+                tops,
+                values,
+                is_total,
+                font_pt,
+                only_totals=self.compact,
+            )
+
+        style_spines(
+            ax,
+            decimals=self.fmt.decimals,
+            units=self.fmt.units,
+            **AX_CONFIG["spines"],
+        )
+        # y-numbers on the left, drop the tickless top/right spines (bar
+        # charts read cleaner without the full box).
+        ax.yaxis.tick_left()
+        declutter_spines(ax)
+
+        ax.set_xticks(x)  # type: ignore[reportUnknownMemberType]
+        ax.set_xticklabels(  # type: ignore[reportUnknownMemberType]
+            display,
+            rotation=self.x_rotation,
+            ha="right" if self.x_rotation else "center",
+            fontsize=font_pt,
+        )
+        if font_pt is not None:
+            ax.tick_params(  # type: ignore[reportUnknownMemberType]
+                axis="y", labelsize=font_pt
+            )
+
+        # headroom on top so the value labels are not clipped.
+        headroom = float(WATERFALL_CONFIG.get("headroom", 0.12))
+        bottom = float(min(0.0, bottoms.min()))
+        top = float(tops.max())
+        ax.set_ylim(bottom, top + (top - bottom) * headroom)
+
+        if self.plot_size is not None and not self.compact:
+            adjust_figure_for_plot_size(fig, ax, self.plot_size)
+
+        return fig, ax
+
+    def _annotate_bars(
+        self,
+        ax: Axes,
+        x: np.ndarray[tuple[int], np.dtype[np.intp]],
+        tops: np.ndarray[tuple[int], np.dtype[np.float64]],
+        values: np.ndarray[tuple[int], np.dtype[np.float64]],
+        is_total: list[bool],
+        font_pt: float | None,
+        *,
+        only_totals: bool = False,
+    ) -> None:
+        """Write each bar's value just above its top (totals in bold).
+
+        With ``only_totals`` set, the floating deltas are left
+        unlabelled -- used by compact charts where the per-delta
+        labels would overlap.
+        """
+        for i in range(len(x)):
+            if only_totals and not is_total[i]:
+                continue
+            text = format_annotation(
+                float(values[i]), self.fmt.decimals, self.fmt.units
+            )
+            ax.annotate(  # type: ignore[reportUnknownMemberType]
+                text,
+                xy=(float(x[i]), float(tops[i])),
+                xytext=(0, 3),
+                textcoords="offset points",
+                ha="center",
+                va="bottom",
+                fontsize=font_pt,
+                fontweight="bold" if is_total[i] else "normal",
+            )
+
+    def save(
+        self,
+        fig: Figure,
+        *,
+        path: Path | None = None,
+        dpi: int | None = None,
+    ) -> Path:
+        """Persist *fig* as a PNG and return the path written."""
+        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
+        fig.savefig(  # type: ignore[reportUnknownMemberType]
+            target, **save_kwargs
+        )
+        return target
+
+    def plot(self) -> Axes:
+        """Build the chart and persist it to ``self.out_path``."""
+        fig, ax = self.build()
+        self.save(fig)
+        plt.close(fig)
+        return ax

tesorotools_python-0.0.47/src/tesorotools/assets/plots.yaml

@@ -0,0 +1,95 @@
+# general plot config file
+
+style:
+  font: Cabinet Grotesk
+
+figure:
+  dpi: 500
+  layout: constrained
+
+ax:
+  spines:
+    color: gray
+    linewidth: 1
+  baseline:
+    color: "#d9e1fc"
+    linestyle: solid
+    linewidth: 1
+    zorder: 1
+
+type_curve:
+  last:
+    alpha: 0.2
+    color: C1
+  current:
+    alpha: 0.3
+    color: C0
+  line:
+    linewidth: 2
+    marker: D
+    color: C0
+
+vector:
+  linewidth: 2
+  arrowstyle: "-|>"
+  mutation_scale: 14   # arrow-head size in points
+  label_pad: 5         # gap (points) between arrow head and its label
+  margin: 0.15         # fraction of the data range left as padding
+  center_line:
+    color: gray
+    linestyle: dashed
+    linewidth: 1
+    zorder: 1
+
+matrix:
+  cmap: Blues
+  gap: 0.04              # white gutter between cells (fraction of a cell)
+  value_fontsize: 26
+  label_fontsize: 13
+  value_weight: bold
+  light_text: white      # value/label colour on dark cells
+  dark_text: "#1a1a1a"   # value/label colour on light cells
+  luminance_threshold: 0.55
+  value_offset: 0.08     # value sits this fraction of a cell above centre
+  label_offset: 0.14     # label sits this fraction of a cell below centre
+
+barh:
+  highlight_factor: 0.4
+  padding: 5
+
+waterfall:
+  start_color: C1            # barra inicial (total absoluto), opacidad plena
+  end_color: C0              # barra final (total absoluto), opacidad plena
+  # Los deltas usan colores DEL CICLO atenuados (menor opacidad): el azul
+  # claro de los incrementos es C0 con light_alpha; los decrementos, un rojo
+  # del ciclo igualmente atenuado.
+  increase_color: C0         # delta positivo (= color de cierre, atenuado)
+  decrease_color: C9         # delta negativo (rojo del ciclo, atenuado)
+  light_alpha: 0.35          # opacidad de las barras de delta
+  connector_color: "#bcbcbc" # líneas de unión entre barras (si connectors=True)
+  bar_width: 0.8
+  headroom: 0.12             # margen superior para las etiquetas (fracción)
+
+line:
+  ncol: 5
+
+# 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.
+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)
+
+table:
+  style: Light Shading Accent 1
+  autofit: False
+  block_separator:
+    fill: "BFBFBF"      # hex color of the inter-block band
+    height_twips: 20    # half-band height; total band = 2 * height_twips

{tesorotools_python-0.0.46 → tesorotools_python-0.0.47}/src/tesorotools/assets/tesoro.mplstyle

@@ -13,8 +13,8 @@ lines.markersize: 8
 # grids
 grid.color: d9e1fc
 grid.linestyle: dashed
-grid.linewidth: 0.5
-grid.alpha: 0.5
+grid.linewidth: 0.8
+grid.alpha: 0.9
 
 # color palette
 axes.prop_cycle: cycler('color', ['001e93', 'ffbd4c', '6d6d6d', '000000', 'e6821e', '2957ff', 'fba737', '5da6ff', '00ebb2', '6d0000', '009200', 'df2871', 'd9e1fc', 'ffddab'])

tesorotools_python-0.0.46/src/tesorotools/assets/plots.yaml

@@ -1,68 +0,0 @@
-# general plot config file
-
-style:
-  font: Cabinet Grotesk
-
-figure:
-  dpi: 500
-  layout: constrained
-
-ax:
-  spines:
-    color: gray
-    linewidth: 1
-  baseline:
-    color: "#d9e1fc"
-    linestyle: solid
-    linewidth: 1
-    zorder: 1
-
-type_curve:
-  last:
-    alpha: 0.2
-    color: C1
-  current:
-    alpha: 0.3
-    color: C0
-  line:
-    linewidth: 2
-    marker: D
-    color: C0
-
-vector:
-  linewidth: 2
-  arrowstyle: "-|>"
-  mutation_scale: 14   # arrow-head size in points
-  label_pad: 5         # gap (points) between arrow head and its label
-  margin: 0.15         # fraction of the data range left as padding
-  center_line:
-    color: gray
-    linestyle: dashed
-    linewidth: 1
-    zorder: 1
-
-matrix:
-  cmap: Blues
-  gap: 0.04              # white gutter between cells (fraction of a cell)
-  value_fontsize: 26
-  label_fontsize: 13
-  value_weight: bold
-  light_text: white      # value/label colour on dark cells
-  dark_text: "#1a1a1a"   # value/label colour on light cells
-  luminance_threshold: 0.55
-  value_offset: 0.08     # value sits this fraction of a cell above centre
-  label_offset: 0.14     # label sits this fraction of a cell below centre
-
-barh:
-  highlight_factor: 0.4
-  padding: 5
-
-line:
-  ncol: 5
-
-table:
-  style: Light Shading Accent 1
-  autofit: False
-  block_separator:
-    fill: "BFBFBF"      # hex color of the inter-block band
-    height_twips: 20    # half-band height; total band = 2 * height_twips