tesorotools-python 0.0.50__tar.gz → 0.0.52__tar.gz

{tesorotools_python-0.0.50 → tesorotools_python-0.0.52}/.gitignore

@@ -3,7 +3,11 @@
 
 __pycache__
 
-.vscode/
+# Ignorar ajustes personales de VS Code, pero versionar los compartidos
+# (recomendación de extensiones y formato de markdown con prettier).
+.vscode/*
+!.vscode/extensions.json
+!.vscode/settings.json
 
 data/
 config/

{tesorotools_python-0.0.50 → tesorotools_python-0.0.52}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tesorotools-python
-Version: 0.0.50
+Version: 0.0.52
 Requires-Python: >=3.13
 Requires-Dist: babel>=2.17
 Requires-Dist: matplotlib>=3.10
@@ -19,5 +19,7 @@ Requires-Dist: requests>=2.31; extra == 'ecb'
 Provides-Extra: imf
 Requires-Dist: requests>=2.31; extra == 'imf'
 Requires-Dist: truststore>=0.10; extra == 'imf'
+Provides-Extra: interactive-plots
+Requires-Dist: plotly>=5.0; extra == 'interactive-plots'
 Provides-Extra: lseg
 Requires-Dist: lseg-data>=2.1; extra == 'lseg'

{tesorotools_python-0.0.50 → tesorotools_python-0.0.52}/pyproject.toml

@@ -29,6 +29,7 @@ bde = ["requests>=2.31"]
 ecb = ["requests>=2.31"]
 imf = ["requests>=2.31", "truststore>=0.10"]
 lseg = ["lseg-data>=2.1"]
+interactive_plots = ["plotly>=5.0"]
 
 [dependency-groups]
 dev = [
@@ -37,6 +38,9 @@ dev = [
     "pre-commit>=4.0",
     "pandas-stubs>=2.2",
     "coverage>=7.0",
+    # the interactive Plotly backend is an optional extra, but the test
+    # suite exercises it (and the 100% coverage gate requires it present).
+    "plotly>=5.0",
 ]
 
 [build-system]

{tesorotools_python-0.0.50 → tesorotools_python-0.0.52}/src/tesorotools/__init__.py

@@ -53,9 +53,12 @@ from tesorotools._registry import (
     register_tags,
 )
 from tesorotools.artists import (
+    BarLinePlot,
+    BoxPlot,
     Format,
     GroupedBarChart,
     HorizontalBarChart,
+    IntradayPlot,
     Legend,
     LinePlot,
     MatrixChart,
@@ -88,6 +91,8 @@ from tesorotools.render import (
 
 def _register_builtins() -> None:
     register_artist("line_plot", LinePlot)
+    register_artist("bar_line", BarLinePlot)
+    register_artist("box_plot", BoxPlot)
     register_artist("stacked_area", StackedAreaPlot)
     register_artist("stacked_bar", StackedBarPlot)
     register_artist("barh", HorizontalBarChart)
@@ -96,6 +101,7 @@ def _register_builtins() -> None:
     register_artist("vector_plot", VectorPlot)
     register_artist("matrix", MatrixChart)
     register_artist("shock_plot", ShockChart)
+    register_artist("intraday", IntradayPlot)
     register_artist("waterfall", Waterfall)
 
     register_tag("format", Format)
@@ -116,6 +122,8 @@ _register_builtins()
 __all__ = [
     "__version__",
     "Artist",
+    "BarLinePlot",
+    "BoxPlot",
     "BdeProvider",
     "BuildContext",
     "CompositeRegistry",
@@ -127,6 +135,7 @@ __all__ = [
     "HorizontalBarChart",
     "Image",
     "Images",
+    "IntradayPlot",
     "Legend",
     "LinePlot",
     "LSEGProvider",

{tesorotools_python-0.0.50 → tesorotools_python-0.0.52}/src/tesorotools/artists/__init__.py

@@ -26,7 +26,10 @@ strictly image output.
 """
 
 from tesorotools.artists._common import Artist, Format, Legend
+from tesorotools.artists.bar_line import BarLinePlot
 from tesorotools.artists.barh_plot import GroupedBarChart, HorizontalBarChart
+from tesorotools.artists.box_plot import BoxPlot
+from tesorotools.artists.intraday_plot import IntradayPlot
 from tesorotools.artists.line_plot import LinePlot
 from tesorotools.artists.matrix import MatrixChart
 from tesorotools.artists.shock_plot import ShockChart
@@ -37,9 +40,12 @@ from tesorotools.artists.waterfall import Waterfall
 
 __all__ = [
     "Artist",
+    "BarLinePlot",
+    "BoxPlot",
     "Format",
     "GroupedBarChart",
     "HorizontalBarChart",
+    "IntradayPlot",
     "Legend",
     "LinePlot",
     "MatrixChart",

{tesorotools_python-0.0.50 → tesorotools_python-0.0.52}/src/tesorotools/artists/_common.py

@@ -24,7 +24,7 @@ overrides only need to update ``plots.yaml``.
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Any, Protocol, Self, cast, runtime_checkable
+from typing import Any, Literal, Protocol, Self, cast, runtime_checkable
 
 import matplotlib.pyplot as plt
 import pandas as pd
@@ -58,10 +58,44 @@ 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", {})
+LINE_CONFIG: dict[str, Any] = PLOT_CONFIG.get("line", {})
 SAVE_CONFIG: dict[str, Any] = PLOT_CONFIG.get("save", {})
 
 CM_TO_IN: float = 1.0 / 2.54
 
+# Soft date-density levels -> AutoDateLocator maxticks. Fallbacks used when the
+# matching ``plots.yaml`` block (``compact.date_maxticks`` / ``line.date_maxticks``)
+# is missing a level; "default" reproduces the historical tick count of each mode
+# (4 for compact, 6 for non-compact).
+DATE_DENSITY_LEVELS: tuple[str, ...] = ("few", "default", "many")
+_DATE_MAXTICKS_FALLBACK_COMPACT: dict[str, int] = {
+    "few": 3,
+    "default": 4,
+    "many": 7,
+}
+_DATE_MAXTICKS_FALLBACK_LINE: dict[str, int] = {
+    "few": 3,
+    "default": 6,
+    "many": 10,
+}
+
+
+def date_maxticks(density: str, *, compact: bool) -> int:
+    """Resolve a soft ``date_density`` level to an ``AutoDateLocator`` maxticks.
+
+    Reads the per-mode ``date_maxticks`` table from ``plots.yaml``
+    (``compact.date_maxticks`` when *compact*, else ``line.date_maxticks``),
+    falling back to the built-in table when the config (or a level) is absent.
+    """
+    cfg = COMPACT_CONFIG if compact else LINE_CONFIG
+    fallback = (
+        _DATE_MAXTICKS_FALLBACK_COMPACT
+        if compact
+        else _DATE_MAXTICKS_FALLBACK_LINE
+    )
+    table: dict[str, Any] = cfg.get("date_maxticks", fallback)
+    return int(table.get(density, fallback[density]))
+
 
 def dynamic_dpi(fig: Figure) -> int:
     """Save DPI adapted to the figure's physical size.
@@ -96,9 +130,7 @@ def dynamic_dpi(fig: Figure) -> int:
 class Artist(Protocol):
     """Structural contract every image artist satisfies.
 
-    The five built-in artists (``LinePlot``,
-    ``StackedAreaPlot``, ``StackedBarPlot``, ``TypeCurve``,
-    ``HorizontalBarChart``) and any third-party artist
+    The built-in artists and any third-party artist
     registered via :func:`tesorotools.register_artist`
     expose the same three-piece surface:
 
@@ -260,6 +292,51 @@ def adjust_figure_for_plot_size(
     fig.set_size_inches(new_w, new_h)
 
 
+def grow_height_to_axes(
+    fig: Figure,
+    ax: Axes,
+    target_axes_h_in: float,
+    *,
+    max_iter: int = 3,
+    cap_factor: float = 2.0,
+) -> None:
+    """Grow the figure **height** (width fixed) until *ax* is *target* inches tall.
+
+    Under ``constrained`` layout an outside legend band and the x-tick label
+    strip keep a roughly **fixed absolute** height, so height added to the
+    figure flows almost entirely into the axes rectangle.  Growing to the axes
+    height measured *before* the legend was added therefore gives the plot area
+    back the vertical space the legend (and any rotated date labels) stole,
+    instead of squashing it inside a fixed figure.
+
+    A feedback loop (grow -> draw -> re-measure the deficit) converges in a few
+    passes because the reserved bands are non-linear only at the margin; total
+    growth is capped at ``cap_factor`` times the original height so a huge
+    legend cannot run the figure away.  Measures the axes rectangle via
+    ``get_window_extent`` (not ``get_tightbbox``, which includes the very tick
+    strip being budgeted for).
+    """
+    orig_w, orig_h = (float(v) for v in fig.get_size_inches())
+    max_h = orig_h * cap_factor
+    eps_in = 0.02
+    for _ in range(max_iter):
+        fig.canvas.draw()  # type: ignore[reportUnknownMemberType]
+        renderer = fig.canvas.get_renderer()  # type: ignore[reportUnknownMemberType]
+        ax_h_in = (
+            ax.get_window_extent(renderer).height  # type: ignore[reportUnknownArgumentType]
+            / fig.dpi
+        )
+        deficit = target_axes_h_in - ax_h_in
+        if deficit <= eps_in:
+            break
+        current_h = float(fig.get_size_inches()[1])
+        new_h = min(max_h, current_h + deficit)
+        if new_h <= current_h:  # capped out: no further progress possible
+            break
+        fig.set_size_inches(orig_w, new_h)
+    fig.canvas.draw()  # type: ignore[reportUnknownMemberType]
+
+
 def auto_ncol(
     ax: Axes,
     labels: list[str],
@@ -498,25 +575,62 @@ class _StartLabeledConcise(ConciseDateFormatter):
         return labels
 
 
+def _date_label_ha(
+    rotation: float | None,
+) -> Literal["left", "center", "right"]:
+    """Horizontal alignment for date tick labels at *rotation* degrees.
+
+    Horizontal labels centre under their tick; a positive (counter-clockwise,
+    up-to-the-right) slant reads best right-anchored so each label runs
+    down-left under its tick, and a negative slant left-anchored.
+    """
+    if rotation is None or rotation == 0:
+        return "center"
+    return "right" if rotation > 0 else "left"
+
+
 def compact_date_axis(
     ax: Axes,
     data_min: Any,
     data_max: Any,
     *,
     maxticks: int = 4,
+    rotation: float | None = None,
+    pin_start: bool | None = None,
+    auto_rotate: bool = False,
 ) -> None:
-    """Compact date x-axis: few horizontal ticks, anchored to the data span.
+    """Compact date x-axis: few 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.  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).
+    point as the tick step allows.  When the start is pinned (see
+    ``pin_start``) the first data point becomes the leading tick, so
+    the reader sees exactly when the series begins.  Requires the
+    series to have been plotted with ``x_compat=True`` (pandas' own
+    date plotting ignores this formatter).
+
+    ``rotation`` (degrees) tilts the tick labels so more dates fit;
+    ``None`` keeps them horizontal (the historical behaviour). The
+    rotation and its matching horizontal alignment are applied
+    **before** the a-priori de-overlap measures the label boxes, so
+    the collision sweep sees the real (slanted, anchored) geometry.
+
+    ``pin_start`` pins the first data point as the leading tick;
+    ``None`` (the default) reads ``compact.date_show_start``.  Pass
+    ``False`` to prefer a **clean equally spaced calendar grid** over
+    the (off-grid, wide) start label -- the caller does this when the
+    user asks for a non-default density or a rotation, where an
+    even cadence reads better than an anchored-but-ragged one.
+
+    ``auto_rotate`` makes the requested density **actually count**: it
+    tries increasing tilts (0, 30, 45, 60, 90 degrees) and keeps the
+    smallest one at which the most (ideally all) of the requested date
+    ticks survive the de-overlap -- so choosing a denser level packs
+    more dates by leaning the labels only as far as needed, instead of
+    silently collapsing to the same few. Ignored when ``rotation`` is
+    given (an explicit angle wins).
     """
     lo: float = float(cast(Any, date2num(data_min)))
     hi: float = float(cast(Any, date2num(data_max)))
@@ -524,8 +638,13 @@ def compact_date_axis(
     candidates: list[float] = cast(
         "list[float]", locator.tick_values(data_min, data_max)
     )
+    show_start: bool = (
+        bool(COMPACT_CONFIG.get("date_show_start", True))
+        if pin_start is None
+        else pin_start
+    )
     interior: list[float] = [t for t in candidates if lo < t <= hi]
-    if COMPACT_CONFIG.get("date_show_start", True):
+    if show_start:
         # 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).
@@ -535,7 +654,6 @@ def compact_date_axis(
         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)
@@ -546,18 +664,34 @@ def compact_date_axis(
             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:
+    def _style_labels(rot: float) -> None:
+        # rotation goes in the axis tick kwargs; ha / anchor rotation-mode are
+        # per-label Text properties reapplied after every draw or locator swap.
+        ha = _date_label_ha(None if rot == 0 else rot)
+        ax.tick_params(  # type: ignore[reportUnknownMemberType]
+            axis="x", rotation=rot
+        )
+        for label in ax.get_xticklabels():
+            label.set_horizontalalignment(ha)
+            if rot != 0:
+                label.set_rotation_mode("anchor")
+
+    def _decimate_at(rot: float) -> list[int]:
+        # Render all candidate ticks at this tilt, measure their label boxes,
+        # and thin to a UNIFORMLY spaced subset when they collide -- so the
+        # survivors stay equally spaced in time (a greedy left-to-right drop
+        # leaves ragged gaps). Returns the kept indices into ``ticks``.
+        _set_ticks(ticks)
+        chosen: list[int] = list(range(len(ticks)))
+        fig = ax.get_figure()
+        if fig is None or len(ticks) <= 1:
+            _style_labels(rot)
+            return chosen
         fig.canvas.draw()  # type: ignore[reportUnknownMemberType]
+        # set ha AFTER the draw (labels now exist) but BEFORE measuring:
+        # get_window_extent recomputes from the current Text properties, so the
+        # boxes reflect both the rotation (from the draw) and the anchor/ha.
+        _style_labels(rot)
         renderer = fig.canvas.get_renderer()  # type: ignore[reportUnknownMemberType]
         boxes = [
             lbl.get_window_extent(renderer)  # type: ignore[reportUnknownArgumentType]
@@ -565,18 +699,88 @@ def compact_date_axis(
         ]
         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)
+            n = len(ticks)
+
+            def _clears(idx: list[int]) -> bool:
+                return all(
+                    boxes[b].x0 > boxes[a].x1 + pad_px
+                    for a, b in zip(idx, idx[1:])
+                )
+
+            # decimate from the right (anchor the latest date) by a constant
+            # stride so the gaps are equal. Force-keep index 0 ONLY when it is
+            # the pinned start tick; otherwise the whole grid is uniform and
+            # forcing it would re-open a ragged left gap.
+            keep0: set[int] = {0} if show_start else set()
+            chosen = sorted(keep0 | {0, n - 1})
+            for stride in range(1, n):
+                idx = sorted(keep0 | set(range(n - 1, -1, -stride)))
+                if _clears(idx):
+                    chosen = idx
+                    break
+        return chosen
+
+    if auto_rotate and rotation is None:
+        # honour the requested density by leaning the labels only as far as
+        # needed: pick the smallest tilt keeping the most date ticks (ties ->
+        # flatter), stopping as soon as one keeps them all.
+        best_rot = 0.0
+        best_chosen = _decimate_at(0.0)
+        for cand in (30.0, 45.0, 60.0, 90.0):
+            if len(best_chosen) >= len(ticks):
+                break
+            cand_chosen = _decimate_at(cand)
+            if len(cand_chosen) > len(best_chosen):
+                best_rot, best_chosen = cand, cand_chosen
+        rot_final, chosen = best_rot, best_chosen
+    else:
+        rot_final = 0.0 if rotation is None else float(rotation)
+        chosen = _decimate_at(rot_final)
+
+    # apply the winning tick subset + tilt as the final state
+    if len(chosen) < len(ticks):
+        _set_ticks([ticks[i] for i in chosen])
+    fig = ax.get_figure()
+    if fig is not None:
+        fig.canvas.draw()  # type: ignore[reportUnknownMemberType]
+    _style_labels(rot_final)
+
 
+def apply_date_axis(
+    ax: Axes,
+    *,
+    maxticks: int,
+    rotation: float | None = None,
+) -> None:
+    """Native matplotlib date x-axis with a soft tick count and optional slant.
+
+    The non-compact counterpart to :func:`compact_date_axis`: it takes over the
+    x-axis (which must carry a **native** date axis, i.e. the series were
+    plotted with ``x_compat=True``) with an ``AutoDateLocator`` capped at
+    *maxticks* and a ``ConciseDateFormatter`` bound to the **same** locator
+    instance (the concise context logic misfires with a mismatched one).
+    ``rotation`` (degrees) tilts the labels; ``None`` keeps them horizontal.
+
+    Unlike the compact path this changes the label **text style** too (concise
+    hierarchical labels instead of pandas' own date formatting), so callers use
+    it only when the user explicitly asks for a non-default density or rotation.
+    """
+    locator = AutoDateLocator(minticks=2, maxticks=maxticks)
+    ax.xaxis.set_major_locator(locator)
+    ax.xaxis.set_major_formatter(ConciseDateFormatter(locator))
+    if rotation is None or rotation == 0:
+        return
+    rot = float(rotation)
+    ha = _date_label_ha(rotation)
+    ax.tick_params(  # type: ignore[reportUnknownMemberType]
+        axis="x", rotation=rot
+    )
+    fig = ax.get_figure()
+    if fig is not None:
+        fig.canvas.draw()  # type: ignore[reportUnknownMemberType]
     for label in ax.get_xticklabels():
-        label.set_horizontalalignment("center")
+        label.set_horizontalalignment(ha)
+        label.set_rotation_mode("anchor")
 
 
 def compact_y_axis(ax: Axes) -> None: