tesorotools-python 0.1.9__tar.gz → 0.1.11__tar.gz

{tesorotools_python-0.1.9 → tesorotools_python-0.1.11}/.gitignore

@@ -32,8 +32,9 @@ test/
 # ruff
 .ruff_cache/
 
-# uv cache (CI restores it into the repo root)
+# uv cache and verified-tree marks (CI restores them into the repo root)
 .uv-cache/
+.ci-verified/
 
 demo_compacto/
 demo/

{tesorotools_python-0.1.9 → tesorotools_python-0.1.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tesorotools-python
-Version: 0.1.9
+Version: 0.1.11
 Requires-Python: >=3.13
 Requires-Dist: babel>=2.17
 Requires-Dist: matplotlib>=3.10

{tesorotools_python-0.1.9 → tesorotools_python-0.1.11}/pyproject.toml

@@ -45,7 +45,10 @@ tesorotools-presentacion = "tesorotools.presentation.cli:main"
 [dependency-groups]
 dev = [
     "ruff>=0.8",
-    "pyright>=1.1",
+    # Con `[nodejs]` node llega como rueda de PyPI; sin él pyright lo baja con
+    # nodeenv en cada job, y nodeenv 1.10 se rompió el 03/11/2026 con una
+    # versión `-alpha` de node.
+    "pyright[nodejs]>=1.1",
     "pre-commit>=4.0",
     "pandas-stubs>=2.2",
     "coverage>=7.0",

{tesorotools_python-0.1.9 → tesorotools_python-0.1.11}/src/tesorotools/artists/matrix.py

@@ -17,8 +17,10 @@ column per column id -- the same wide shape
 :class:`GroupedBarChart` consumes -- so ``rows`` selects and
 labels the index and ``cols`` selects and labels the columns.
 Cell shading uses a sequential colormap normalised over the
-selected values; text colour flips to stay legible on dark
-cells.  ``NaN`` cells are left blank (no fill, no text), which
+selected values or, when they have both signs, a diverging one
+centred on zero (:data:`DIVERGING`), so -0,6 reads as strongly as
+0,6 instead of almost white; text colour flips to stay legible on
+dark cells.  ``NaN`` cells are left blank (no fill, no text), which
 covers triangular or sparse matrices.
 
 Styling constants come from ``PLOT_CONFIG['matrix']``.
@@ -34,11 +36,12 @@ import matplotlib.pyplot as plt
 import numpy as np
 import pandas as pd
 from matplotlib.axes import Axes
-from matplotlib.colors import Colormap, Normalize
+from matplotlib.colors import Colormap, LinearSegmentedColormap, Normalize
 from matplotlib.figure import Figure
 from matplotlib.patches import Rectangle
 from yaml.nodes import MappingNode
 
+from tesorotools import palette
 from tesorotools.artists._common import (
     FigureLifecycle,
     FIG_CONFIG,
@@ -51,6 +54,12 @@ from tesorotools.utils.template import TemplateLoader
 __all__ = ["MatrixChart"]
 
 MATRIX_CONFIG: dict[str, Any] = PLOT_CONFIG["matrix"]
+#: The scale of a matrix with figures of both signs: red under zero,
+#: white at zero and blue over it, in the house colours.
+DIVERGING_STOPS = (f"#{palette.RED}", "#FFFFFF", f"#{palette.BLUE}")
+DIVERGING: Colormap = LinearSegmentedColormap.from_list(
+    "tesoro_diverging", list(DIVERGING_STOPS)
+)
 
 
 def _text_color(rgba: tuple[float, float, float, float]) -> str:
@@ -91,10 +100,12 @@ class MatrixChart(FigureLifecycle):
         :class:`Format` for the big per-cell value.
     cmap
         Matplotlib colormap name for the shading (default
-        ``PLOT_CONFIG['matrix']['cmap']``).
+        ``PLOT_CONFIG['matrix']['cmap']`` or, with values of both
+        signs, :data:`DIVERGING`).
     vmin, vmax
         Value range mapped to the colormap ends.  Default to
-        the min / max of the selected values.
+        the min / max of the selected values (with both signs,
+        symmetric around zero).
     xlabel, ylabel
         Axis titles (the column / row variable names).
     figsize
@@ -142,6 +153,8 @@ class MatrixChart(FigureLifecycle):
         self.scale = scale
         self.fmt = fmt or Format()
         self.cmap = cmap or MATRIX_CONFIG["cmap"]
+        #: The colormap was not chosen: values of both signs diverge.
+        self.default_cmap = cmap is None
         self.vmin = vmin
         self.vmax = vmax
         self.xlabel = xlabel
@@ -230,10 +243,7 @@ class MatrixChart(FigureLifecycle):
 
         values_arr = matrix.to_numpy(dtype=float)
         valid = values_arr[~np.isnan(values_arr)]
-        vmin = self.vmin if self.vmin is not None else float(valid.min())
-        vmax = self.vmax if self.vmax is not None else float(valid.max())
-        norm = Normalize(vmin=vmin, vmax=vmax)
-        cmap: Colormap = mpl.colormaps[self.cmap]
+        norm, cmap = self.shading(valid)
 
         fig_kw = dict(FIG_CONFIG)
         fig_kw["figsize"] = self.figsize if self.figsize is not None else (6, 6)
@@ -276,6 +286,23 @@ class MatrixChart(FigureLifecycle):
         self._style_axes(ax, row_ids, col_ids)
         return fig, ax
 
+    def shading(
+        self, valid: np.ndarray[Any, np.dtype[np.float64]]
+    ) -> tuple[Normalize, Colormap]:
+        """The colour scale of the cells with *valid* values.
+
+        With values of both signs, and no ``cmap``, ``vmin`` or ``vmax``
+        given, :data:`DIVERGING` centred on zero: a sequential scale
+        would paint -0,6 almost white, like a zero.
+        """
+        vmin = self.vmin if self.vmin is not None else float(valid.min())
+        vmax = self.vmax if self.vmax is not None else float(valid.max())
+        both = vmin < 0 < vmax and self.vmin is None and self.vmax is None
+        if self.default_cmap and both:
+            edge = max(-vmin, vmax)
+            return Normalize(vmin=-edge, vmax=edge), DIVERGING
+        return Normalize(vmin=vmin, vmax=vmax), mpl.colormaps[self.cmap]
+
     def _annotate_cell(
         self,
         ax: Axes,

{tesorotools_python-0.1.9 → tesorotools_python-0.1.11}/src/tesorotools/artists/plotly_backend.py

@@ -46,7 +46,6 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any
 
-import matplotlib as mpl
 import matplotlib.colors as mcolors
 import matplotlib.pyplot as plt
 import numpy as np
@@ -763,10 +762,8 @@ def waterfall_to_figure(chart: Waterfall) -> go.Figure:
     dec_color = WATERFALL_CONFIG.get("decrease_color", "C9")
     colors: list[str] = []
     for i in range(n):
-        if i == 0:
-            colors.append(_color(start_color))
-        elif i == n - 1 or is_total[i]:
-            colors.append(_color(end_color))
+        if is_total[i]:
+            colors.append(_color(start_color if i == 0 else end_color))
         else:
             base = inc_color if values[i] >= 0 else dec_color
             colors.append(_color(base, light_alpha))
@@ -919,17 +916,25 @@ def grouped_bar_to_figure(chart: GroupedBarChart) -> go.Figure:
 
 def matrix_to_figure(chart: MatrixChart) -> go.Figure:
     """Interactive ``Figure`` from a :class:`MatrixChart` (heatmap + labels)."""
-    from tesorotools.artists.matrix import _text_color
+    from tesorotools.artists.matrix import (
+        DIVERGING,
+        DIVERGING_STOPS,
+        _text_color,
+    )
 
     row_ids = list(chart.rows)
     col_ids = list(chart.cols)
     matrix = chart.data.loc[row_ids, col_ids] * chart.scale
     values = matrix.to_numpy(dtype=float)
     valid = values[~np.isnan(values)]
-    vmin = chart.vmin if chart.vmin is not None else float(valid.min())
-    vmax = chart.vmax if chart.vmax is not None else float(valid.max())
-    norm = mcolors.Normalize(vmin=vmin, vmax=vmax)
-    cmap = mpl.colormaps[chart.cmap]
+    norm, cmap = chart.shading(valid)
+    vmin, vmax = norm.vmin, norm.vmax
+    # the diverging scale of values of both signs, as in the PNG
+    colorscale: str | list[list[Any]] = (
+        [[n / 2, stop] for n, stop in enumerate(DIVERGING_STOPS)]
+        if cmap is DIVERGING
+        else "Blues"
+    )
 
     row_labels = [chart.rows[r] for r in row_ids]
     col_labels = [chart.cols[c] for c in col_ids]
@@ -954,7 +959,7 @@ def matrix_to_figure(chart: MatrixChart) -> go.Figure:
             z=values,
             x=col_labels,
             y=row_labels,
-            colorscale="Blues",
+            colorscale=colorscale,
             zmin=vmin,
             zmax=vmax,
             showscale=False,

{tesorotools_python-0.1.9 → tesorotools_python-0.1.11}/src/tesorotools/artists/waterfall.py

@@ -25,6 +25,7 @@ import pandas as pd
 from matplotlib.axes import Axes
 from matplotlib.colors import to_rgba
 from matplotlib.figure import Figure
+from matplotlib.text import Annotation
 from yaml.nodes import MappingNode
 
 from tesorotools.artists._common import (
@@ -47,6 +48,31 @@ __all__ = ["Waterfall"]
 
 WATERFALL_CONFIG: dict[str, Any] = PLOT_CONFIG.get("waterfall", {})
 
+# points of air between two value labels for them not to read as one
+_LABEL_GAP_PT = 2.0
+
+
+def _drop_crowded(
+    fig: Figure, labels: list[Annotation], is_total: list[bool]
+) -> None:
+    """Remove the deltas' value labels if any two neighbours collide.
+
+    Measured on the drawn figure: all of them go or none, so the
+    chart never labels some steps and not others; the totals stay.
+    """
+    if len(labels) < 2:
+        return
+    fig.draw_without_rendering()
+    gap = _LABEL_GAP_PT * fig.dpi / 72
+    boxes = [label.get_window_extent() for label in labels]
+    if any(
+        a.x1 + gap > b.x0 and a.y0 < b.y1 and b.y0 < a.y1
+        for a, b in zip(boxes, boxes[1:])
+    ):
+        for label, total in zip(labels, is_total):
+            if not total:
+                label.remove()
+
 
 class Waterfall(FigureLifecycle):
     """Waterfall / bridge chart with the tesorotools visual style.
@@ -205,12 +231,12 @@ class Waterfall(FigureLifecycle):
         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))
+        # the colour follows what the bar is, not where it sits: a first or
+        # last bar left out of ``totals`` is a delta like the rest
         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))
+            if is_total[i]:
+                colors.append(to_rgba(start_color if i == 0 else end_color))
             else:
                 base = inc_color if values[i] >= 0 else dec_color
                 colors.append(to_rgba(base, light_alpha))
@@ -243,19 +269,11 @@ class Waterfall(FigureLifecycle):
                     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,
-            )
+        labels = (
+            self._annotate_bars(ax, x, tops, values, is_total, font_pt)
+            if self.annotate
+            else []
+        )
 
         style_spines(
             ax,
@@ -286,6 +304,11 @@ class Waterfall(FigureLifecycle):
         top = float(tops.max())
         ax.set_ylim(bottom, top + (top - bottom) * headroom)
 
+        if self.compact:
+            # a compact chart at 7.4 cm has no room for every label; one as
+            # wide as a slide does, so the deltas go only if they collide
+            _drop_crowded(fig, labels, is_total)
+
         if self.plot_size is not None and not self.compact:
             adjust_figure_for_plot_size(fig, ax, self.plot_size)
 
@@ -299,22 +322,14 @@ class Waterfall(FigureLifecycle):
         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.
-        """
+    ) -> list[Annotation]:
+        """Write each bar's value just above its top (totals in bold)."""
+        labels: list[Annotation] = []
         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]
+            label = ax.annotate(  # type: ignore[reportUnknownMemberType]
                 text,
                 xy=(float(x[i]), float(tops[i])),
                 xytext=(0, 3),
@@ -324,6 +339,8 @@ class Waterfall(FigureLifecycle):
                 fontsize=font_pt,
                 fontweight="bold" if is_total[i] else "normal",
             )
+            labels.append(label)
+        return labels
 
     def save(
         self,

{tesorotools_python-0.1.9 → tesorotools_python-0.1.11}/src/tesorotools/note/lint.py

@@ -86,6 +86,8 @@ FOREIGN_WORDS: tuple[str, ...] = (
     "default",
     "tapering",
     "carry trade",
+    "home bias",
+    "unit-linked",
     "benchmark",
     "trading",
     "outlook",
@@ -108,12 +110,14 @@ _WORD_BEFORE = re.compile(r"(\w+)\s+$")
 _BEFORE_NUMBER = re.compile(
     r"(?:gráfico|tabla|apartado|sección|capítulo|anexo|nivel|punto|fase"
     r"|pilar|artículo|nota|paso|grupo|tramo|versión|n\.º|nº"
+    r"|alternativa|opción|escenario|propuesta|etapa|hito|eje|objetivo"
+    r"|medida|caso|tema"
     r"|art\.|arts\.|núm\.|pág\.|págs\.|p\.|pp\.|cap\.|apdo\.|vol\.)\s*$",
     re.I,
 )
 _UNIT_AFTER = re.compile(
-    r"\s*(?:%|por\s+ciento\b|pb\b|pp\b|puntos?\b|millones?\b|mil\b|miles\b"
-    r"|billones?\b|billions?\b"
+    r"\s*(?:%|por\s+cien(?:to)?\b|pb\b|pp\b|puntos?\b|millones?\b|mil\b"
+    r"|miles\b|billones?\b|billions?\b|bn\b|tn\b"
     r"|euros?\b|dólares?\b|€|\$|°|veces\b|x\b|h\b|horas?\b|de\s+(?:"
     + _MONTHS.lower()
     + r")\b)",
@@ -145,10 +149,10 @@ def _real_decimal(text: str, match: re.Match[str]) -> bool:
 def _month_context(text: str, match: re.Match[str]) -> bool:
     """«de Mayo» outside a proper name such as «Plaza de Mayo».
 
-    Only «de» can join a proper name; «en Octubre» is always a fault,
-    also after a capitalised word or in a title.
+    Only «de» can join a proper name; «en Octubre» or «desde Octubre» is
+    always a fault, also after a capitalised word or in a title.
     """
-    if not match.group(0).lower().startswith("de"):
+    if match.group(0).split()[0].lower() != "de":
         return True
     word = _WORD_BEFORE.search(text[: match.start()])
     return word is None or not word.group(1)[0].isupper()
@@ -187,6 +191,8 @@ def _small_number(text: str, match: re.Match[str]) -> bool:
     before, after = text[: match.start()], text[match.end() :]
     if _BEFORE_NUMBER.search(before) or _UNIT_AFTER.match(after):
         return False
+    if _quoted(text, match.start()):  # a name or a quote: «peso: 2»
+        return False
     if _NAME_AFTER.match(after) or _RANGE_AFTER.match(after):
         return False
     if _RANGE_BEFORE.search(before):
@@ -195,8 +201,14 @@ def _small_number(text: str, match: re.Match[str]) -> bool:
 
 
 def _empty_adjective(text: str, match: re.Match[str]) -> bool:
-    if match.group(0).lower().startswith("hist"):
+    word = match.group(0).lower()
+    if word.startswith("hist"):
         return not _HISTORIC.search(text[: match.start()])
+    if word.startswith("significativ"):
+        # the statistical term, not an intensifier
+        return not re.search(
+            r"estadísticamente\s+$", text[: match.start()], re.I
+        )
     return True
 
 
@@ -283,7 +295,7 @@ _RULES: tuple[_Rule, ...] = (
         "todo",
     ),
     _r(
-        r"\bpor ciento\b",
+        r"\bpor cien(?:to)?\b(?!\s+(?:de|del)\b)",
         "porcentaje",
         "escribe «%» con espacio fijo",
         scope="prosa",
@@ -346,7 +358,8 @@ _RULES: tuple[_Rule, ...] = (
         flags=re.I,
     ),
     _r(
-        rf"\b(?:de|en|el|del|\d+) (?:{_MONTHS})\b",
+        rf"\b(?:de|en|el|del|desde|hasta|entre|hacia|para|y|\d+)"
+        rf" (?:{_MONTHS})\b",
         "mes",
         "los meses y los días de la semana van en minúscula",
         _month_context,
@@ -391,6 +404,27 @@ _RULES: tuple[_Rule, ...] = (
         scope="prosa",
         flags=re.I,
     ),
+    _r(
+        r"\bse\s+desplom\w*|\bdesplom(?:e|es|ó|aron)\b",
+        "registro",
+        "registro coloquial: «cayó un 5 %», «registró la mayor caída desde...»",
+        scope="prosa",
+        flags=re.I,
+    ),
+    _r(
+        r"\bse\s+dispar(?:a|an|ó|aron|aba|aban)\b",
+        "registro",
+        "registro coloquial: «subió con fuerza», «aumentó un 5 %»",
+        scope="prosa",
+        flags=re.I,
+    ),
+    _r(
+        r"\btir[oó]n(?:es)?\b",
+        "registro",
+        "registro coloquial: «aumento», «repunte»",
+        scope="prosa",
+        flags=re.I,
+    ),
     _r(
         r"\ba trozos\b",
         "registro",
@@ -406,7 +440,8 @@ _RULES: tuple[_Rule, ...] = (
         flags=re.I,
     ),
     _r(
-        r"\b(?:burbuja|sobrevalora\w*|excesiv[oa]s?|insostenibles?)\b",
+        r"\b(?:burbuja|sobrevalora\w*|excesiv[oa]s?|insostenibles?"
+        r"|preocupantes?|alarmantes?)\b",
         "juicio",
         "sin juicios subjetivos: descríbelo con indicadores («valoraciones"
         " elevadas en perspectiva histórica») o atribúyelo a quien lo dice",
@@ -423,7 +458,8 @@ _RULES: tuple[_Rule, ...] = (
     ),
     _r(
         r"\b(?:enorme|enormes|histórico|histórica|históricos|históricas|muy"
-        r"|extraordinari[oa]s?|espectacular(?:es)?|dramátic[oa]s?)\b",
+        r"|extraordinari[oa]s?|espectacular(?:es)?|dramátic[oa]s?|realmente"
+        r"|claramente|significativ[oa]s?|significativamente|notablemente)\b",
         "precision",
         "adjetivo o intensificador que no añade información: úsalo solo si"
         " una cifra lo respalda",
@@ -439,7 +475,8 @@ _RULES: tuple[_Rule, ...] = (
         flags=re.I,
     ),
     _r(
-        r"\b(?:el|la|los|las|del)\s+(?:Presidente|Presidenta|Ministro|Ministra"
+        r"\b(?:[Ee]l|[Ll]a|[Ll]os|[Ll]as|[Dd]el)\s+(?:Presidente|Presidenta"
+        r"|Ministro|Ministra"
         r"|Gobernador|Gobernadora|Vicepresidente|Vicepresidenta|Consejero"
         r"|Consejera|Bolsa|Euro|Dólar)\b",
         "mayusculas",
@@ -547,7 +584,11 @@ _KNOWN_ACRONYMS = {
     "CNH",
     "RMB",
 }
-_ACRONYM = re.compile(r"\b[A-ZÁÉÍÓÚÑ]{2,6}\b")
+#: An acronym: in capitals («CNMV») or with a lowercase letter inside
+#: («AIReF», «BdE»).
+_ACRONYM = re.compile(
+    r"\b(?:[A-ZÁÉÍÓÚÑ]{2,6}|[A-Z]{2,4}[a-z][A-Z]{1,2}|[A-Z][a-z][A-Z])\b"
+)
 
 
 def _scope_texts(text: str, scope: str) -> Iterator[_Rule]:

{tesorotools_python-0.1.9 → tesorotools_python-0.1.11}/src/tesorotools/note/markdown.py

@@ -386,12 +386,55 @@ def _hash_comments(text: str, line: int) -> None:
             )
 
 
+#: A decimal comma («3,5», «1.234,5»), not a date («2024-01-01,2024»).
+_DECIMAL_COMMA = re.compile(
+    r"(?<![\d\-])(?:\d{1,3}(?:\.\d{3})+|\d+),\d+(?![\d\-:])"
+)
+#: A bracket, or a comma that separates the elements of a flow list.
+_SEPARATOR = re.compile(r"[\[\]{}]|,(?!\d)|(?<!\d),")
+
+
+def _decimal_commas(text: str, line: int) -> None:
+    """Reject «3,5» inside a flow list or map (``[...]``, ``{...}``):
+    YAML splits it at the comma, into «3» and «5»."""
+    depth = 0
+    for offset, raw in enumerate(text.splitlines()):
+        # quoted text keeps its length, so positions match *raw*
+        bare = _QUOTED.sub(lambda m: "'" + "_" * (len(m[0]) - 2) + "'", raw)
+        marks = [(m.start(), m[0]) for m in _SEPARATOR.finditer(bare)]
+        for match in _DECIMAL_COMMA.finditer(bare):
+            before = [(n, c) for n, c in marks if n < match.start()]
+            opened = depth + sum(
+                1 if c in "[{" else -1 for _, c in before if c != ","
+            )
+            if opened <= 0:
+                continue
+            start = before[-1][0] + 1 if before else 0
+            end = next((n for n, _ in marks if n >= match.end()), len(raw))
+            element = re.sub(r"^[\w-]+:\s+", "", raw[start:end].strip())
+            if re.fullmatch(r"[-+]?[\d.]+(?:,\d+)+", element):
+                plain = element.replace(".", "").replace(",", ".")
+                hint = (
+                    f"los decimales van con punto ({plain}); si son varias"
+                    " cifras, sepáralas con coma y espacio"
+                )
+            else:
+                hint = f'entrecomíllalo ("{element}")'
+            raise NoteSyntaxError(
+                line + offset,
+                f"«{element}» lleva coma decimal y, entre [...] o {{...}},"
+                f" YAML lo parte en dos por la coma: {hint}",
+            )
+        depth += sum(1 if c in "[{" else -1 for _, c in marks if c != ",")
+
+
 def _yaml(text: str, line: int) -> Any:
     """``yaml.safe_load`` with the errors in Spanish and with their line.
 
     *line* is the line of the source where *text* starts.
     """
     _hash_comments(text, line)
+    _decimal_commas(text, line)
     try:
         return yaml.safe_load(_windows_paths(text))
     except yaml.YAMLError as exc:

{tesorotools_python-0.1.9 → tesorotools_python-0.1.11}/src/tesorotools/palette.py

@@ -31,6 +31,8 @@ BLUE_PALE = "AEBAE7"
 BLUE_FAINT = "ECF0FD"
 #: Secondary text: captions, metadata, stale rows.
 GREY = "6D6D6D"
+#: Plot area of the slide charts, under white grid lines.
+GREY_PANEL = "EFEFEF"
 #: Tesoro yellow: highlights of the presentations (bands, frames, the
 #: section subtitles of the index) and its light shade for fills.
 YELLOW = "FFBD4C"