tesorotools-python 0.0.24__tar.gz → 0.0.26__tar.gz

{tesorotools_python-0.0.24 → tesorotools_python-0.0.26}/.gitignore

@@ -21,4 +21,10 @@ dist/
 test/
 
 # font files
-*.otf
+*.otf
+
+# coverage
+.coverage
+
+# ruff
+.ruff_cache/

tesorotools_python-0.0.26/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.4
+Name: tesorotools-python
+Version: 0.0.26
+Requires-Python: >=3.13
+Requires-Dist: babel>=2.17
+Requires-Dist: eikon>=1.1
+Requires-Dist: lseg-data>=2.0
+Requires-Dist: matplotlib>=3.10
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: pandas>=2.2
+Requires-Dist: psycopg[binary]>=3.1
+Requires-Dist: pyarrow>=18.0
+Requires-Dist: python-docx>=1.1
+Requires-Dist: pywin32>=311; sys_platform == 'win32'
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: sqlalchemy>=2.0
+Provides-Extra: bde
+Requires-Dist: requests>=2.31; extra == 'bde'

{tesorotools_python-0.0.24 → tesorotools_python-0.0.26}/pyproject.toml

@@ -1,31 +1,34 @@
 [project]
 name = "tesorotools-python"
 requires-python = ">=3.13"
-version = "0.0.24"
+version = "0.0.26"
 dependencies = [
     # database and ORM
-    "psycopg[binary]",
+    "psycopg[binary]>=3.1",
     "SQLAlchemy>=2.0",
 
     # data analysis
-    "pandas",
-    "pyarrow",
-    "openpyxl",
+    "pandas>=2.2",
+    "pyarrow>=18.0",
+    "openpyxl>=3.1",
 
     # utils
-    "PyYAML",
-    "babel",
-    "eikon",
-    "lseg-data",
+    "PyYAML>=6.0",
+    "babel>=2.17",
+    "eikon>=1.1",
+    "lseg-data>=2.0",
 
     # data visualization
-    "matplotlib",
-    "python-docx",
+    "matplotlib>=3.10",
+    "python-docx>=1.1",
 
     # os dependencies
-    "pywin32>=311; sys_platform == 'win32'"
+    "pywin32>=311; sys_platform == 'win32'",
 ]
 
+[project.optional-dependencies]
+bde = ["requests>=2.31"]
+
 [dependency-groups]
 dev = [
     "ruff>=0.8",

tesorotools_python-0.0.26/src/tesorotools/artists/__init__.py

@@ -0,0 +1,5 @@
+import matplotlib.style
+
+from ..utils.globals import STYLE_SHEET
+
+matplotlib.style.use(STYLE_SHEET)

{tesorotools_python-0.0.24 → tesorotools_python-0.0.26}/src/tesorotools/artists/barh_plot.py

@@ -1,8 +1,5 @@
 from __future__ import annotations
 
-# Añadir anotaciones de tipos, el objetivo sería eliminar todos los diccionarios con anotaciones del tipo dict[str, Any] que dicen más bien poco
-# Tener cuidado para que nada de lo que está hecho con esta librería deje de funcionar
-
 from enum import Enum
 from pathlib import Path
 from typing import Any, Self

{tesorotools_python-0.0.24 → tesorotools_python-0.0.26}/src/tesorotools/artists/line_plot.py

@@ -26,7 +26,77 @@ AX_CONFIG: dict[str, Any] = PLOT_CONFIG["ax"]
 FIG_CONFIG: dict[str, Any] = PLOT_CONFIG["figure"]
 
 
-def _style_spines(
+def adjust_figure_for_plot_size(
+    fig: Figure,
+    ax: Axes,
+    plot_size: tuple[float, float],
+) -> None:
+    """Resize the figure so the axes area matches *plot_size*.
+
+    Call this **after** adding the legend.  The figure
+    height grows to accommodate the legend while keeping
+    the plot area at the requested size.
+
+    Parameters
+    ----------
+    fig
+        The figure to resize.
+    ax
+        The axes whose area should match *plot_size*.
+    plot_size
+        Desired ``(width, height)`` of the axes area in
+        inches.
+    """
+    fig.canvas.draw()  # type: ignore[reportUnknownMemberType]
+    renderer = fig.canvas.get_renderer()  # type: ignore[reportUnknownMemberType]
+    ax_bbox = ax.get_tightbbox(renderer)  # type: ignore[reportUnknownArgumentType]
+    fig_bbox = fig.get_tightbbox(renderer)  # type: ignore[reportUnknownArgumentType]
+    if ax_bbox is None or fig_bbox is None:  # type: ignore[reportUnnecessaryComparison]
+        return
+    fig_w, fig_h = fig.get_size_inches()
+    ax_w_in = ax_bbox.width / fig.dpi
+    ax_h_in = ax_bbox.height / fig.dpi
+    if ax_w_in <= 0 or ax_h_in <= 0:
+        return
+    new_w = fig_w * (plot_size[0] / ax_w_in)
+    new_h = fig_h * (plot_size[1] / ax_h_in)
+    fig.set_size_inches(new_w, new_h)
+
+
+def auto_ncol(ax: Axes, labels: list[str]) -> int:
+    """Choose the maximum legend ncol that fits the axes.
+
+    Renders each label as a temporary Text to measure its
+    width, then packs as many columns as the axes width
+    allows, with padding for the legend handle + spacing.
+    Falls back to ``len(labels)`` (single row) when all
+    labels are short enough.
+    """
+    fig = ax.get_figure()
+    if fig is None:
+        return len(labels)
+    renderer = fig.canvas.get_renderer()  # type: ignore[reportUnknownMemberType]
+    ax_width_px = ax.get_window_extent(renderer).width  # type: ignore[reportUnknownArgumentType]
+
+    # Measure widest label in pixels.
+    handle_pad_px = 40.0  # handle icon + spacing estimate
+    max_label_px = 0.0
+    for label in labels:
+        t = ax.text(  # type: ignore[reportUnknownMemberType]
+            0, 0, label
+        )
+        bbox = t.get_window_extent(renderer)  # type: ignore[reportUnknownArgumentType]
+        max_label_px = max(max_label_px, bbox.width)
+        t.remove()
+
+    col_width = max_label_px + handle_pad_px
+    if col_width <= 0:
+        return len(labels)
+    ncol = max(1, int(ax_width_px / col_width))
+    return min(ncol, len(labels))
+
+
+def style_spines(
     ax: Axes,
     decimals: int,
     units: str,
@@ -62,7 +132,37 @@ def _style_spines(
         tick.set_markeredgecolor(color)
 
 
-def _style_baseline(
+def export_legend(
+    ax: Axes,
+    out_path: Path,
+    *,
+    ncol: int = 5,
+    dpi: int = 500,
+) -> None:
+    """Save the legend of *ax* as a standalone PNG.
+
+    The plot's own legend is removed after export.
+    """
+    handles, labels = ax.get_legend_handles_labels()
+    fig_leg = plt.figure(  # type: ignore[reportUnknownMemberType]
+        figsize=(6, 0.5), dpi=dpi
+    )
+    fig_leg.legend(  # type: ignore[reportUnknownMemberType]
+        handles,
+        labels,
+        loc="center",
+        ncol=ncol,
+    )
+    fig_leg.savefig(  # type: ignore[reportUnknownMemberType]
+        out_path, bbox_inches="tight"
+    )
+    plt.close(fig_leg)
+    legend = ax.get_legend()
+    if legend is not None:
+        legend.remove()
+
+
+def style_baseline(
     ax: Axes,
     reference: float = 0,
     **baseline_config: Any,
@@ -106,8 +206,8 @@ def plot_line_chart(
         pass
 
     reference = 100 if base_100 else 0
-    _style_spines(ax, **format, **AX_CONFIG["spines"])
-    _style_baseline(ax, reference, **AX_CONFIG["baseline"])
+    style_spines(ax, **format, **AX_CONFIG["spines"])
+    style_baseline(ax, reference, **AX_CONFIG["baseline"])
     ax.legend(  # type: ignore[reportUnknownMemberType]
         loc="upper center",
         bbox_to_anchor=(0.5, LINE_PLOT_CONFIG["legend_sep"]),
@@ -161,7 +261,11 @@ class Format:
 
 
 class Legend:
-    def __init__(self, ncol: int = 5, sep: float = -0.125) -> None:
+    def __init__(
+        self,
+        ncol: int | None = None,
+        sep: float = -0.125,
+    ) -> None:
         self.ncol = ncol
         self.sep = sep
 
@@ -179,8 +283,8 @@ class LinePlot:
     def __init__(
         self,
         out_path: Path,
-        data_path: Path,
-        series: dict[str, str],
+        data_path: Path | None = None,
+        series: dict[str, str] | None = None,
         scale: float = 1,
         start_date: datetime.datetime | None = None,
         end_date: datetime.datetime | None = None,
@@ -189,17 +293,31 @@ class LinePlot:
         baseline: bool = False,
         format: Format | None = None,
         legend: Legend | None = None,
+        data: pd.DataFrame | None = None,
+        figsize: tuple[float, float] | None = None,
+        series_styles: dict[str, dict[str, Any]] | None = None,
+        plot_size: tuple[float, float] | None = None,
     ) -> None:
 
         if out_path.suffix != ".png":
             raise ValueError(f"The out file {out_path} should be a .png file")
         self.out_path = out_path
 
-        if data_path.suffix != ".feather":
-            raise ValueError(
-                f"The data file {data_path} must be a .feather file"
-            )
-        self.data = pd.read_feather(data_path)
+        if data is not None and data_path is not None:
+            raise ValueError("Provide data or data_path, not both")
+        if data is not None:
+            self.data = data
+        elif data_path is not None:
+            if data_path.suffix != ".feather":
+                raise ValueError(
+                    f"The data file {data_path} must be a .feather file"
+                )
+            self.data = pd.read_feather(data_path)
+        else:
+            raise ValueError("Provide data or data_path")
+
+        if series is None:
+            raise ValueError("series is required")
 
         self.base_100 = base_100
         self.annotate = annotate  # unused for the moment
@@ -210,6 +328,9 @@ class LinePlot:
         self.legend = legend
         self.baseline = baseline
         self.scale = scale
+        self.figsize = figsize
+        self.series_styles = series_styles or {}
+        self.plot_size = plot_size
 
     @classmethod
     def from_yaml(cls, loader: TemplateLoader, node: MappingNode) -> Self:
@@ -244,17 +365,25 @@ class LinePlot:
         if self.base_100:  # maybe more flexible in the future
             plot_data = plot_data / plot_data.iloc[0, :] * 100
 
+        fig_kw = dict(FIG_CONFIG)
+        if self.figsize is not None:
+            fig_kw["figsize"] = self.figsize
         fig: Figure = plt.figure(  # type: ignore[reportUnknownMemberType]
-            **FIG_CONFIG
+            **fig_kw
         )
         ax = fig.add_subplot()
-        plot_data.plot(ax=ax)
+        if self.series_styles:
+            for col in plot_data.columns:
+                style = self.series_styles.get(col, {})
+                plot_data[col].plot(ax=ax, label=col, **style)
+        else:
+            plot_data.plot(ax=ax)
 
         if self.annotate:  # not implemented yet
             pass
 
         assert self.format is not None
-        _style_spines(  # maybe make this function accept a Format object
+        style_spines(  # maybe make this function accept a Format object
             ax,
             decimals=self.format.decimals,
             units=self.format.units,
@@ -262,22 +391,31 @@ class LinePlot:
         )
         if self.baseline:
             reference = 100 if self.base_100 else 0
-            _style_baseline(ax, reference, **AX_CONFIG["baseline"])
+            style_baseline(ax, reference, **AX_CONFIG["baseline"])
 
         if self.legend is not None:
+            labels = list(plot_data.columns)
+            ncol = (
+                self.legend.ncol
+                if self.legend.ncol is not None
+                else auto_ncol(ax, labels)
+            )
             ax.legend(  # type: ignore[reportUnknownMemberType]
                 loc="upper center",
                 bbox_to_anchor=(
                     0.5,
                     LINE_PLOT_CONFIG["legend_sep"],
                 ),
-                ncol=self.legend.ncol,
+                ncol=ncol,
             )
         else:
             ax.legend().set_visible(  # type: ignore[reportUnknownMemberType]
                 False
             )
 
+        if self.plot_size is not None:
+            adjust_figure_for_plot_size(fig, ax, self.plot_size)
+
         fig.savefig(  # type: ignore[reportUnknownMemberType]
             self.out_path
         )

tesorotools_python-0.0.26/src/tesorotools/artists/stacked.py

@@ -0,0 +1,308 @@
+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.figure import Figure
+from yaml.nodes import MappingNode
+
+from tesorotools.artists.line_plot import (
+    AX_CONFIG,
+    FIG_CONFIG,
+    Format,
+    Legend,
+    adjust_figure_for_plot_size,
+    auto_ncol,
+    style_baseline,
+    style_spines,
+)
+from tesorotools.utils.config import TemplateLoader
+
+_DEFAULT_SEP = -0.125
+
+
+class StackedAreaPlot:
+    """Stacked area chart with the tesorotools visual style.
+
+    Parameters match ``LinePlot`` where applicable so that
+    chart configs can switch between types by changing a
+    single field.
+    """
+
+    def __init__(
+        self,
+        out_path: Path,
+        data: pd.DataFrame,
+        series: dict[str, str],
+        *,
+        scale: float = 1,
+        start_date: str | None = None,
+        end_date: str | None = None,
+        baseline: bool = False,
+        format: Format | None = None,
+        legend: Legend | None = None,
+        figsize: tuple[float, float] | None = None,
+        plot_size: tuple[float, float] | None = None,
+    ) -> None:
+        if out_path.suffix != ".png":
+            raise ValueError(f"out_path must be .png: {out_path}")
+        self.out_path = out_path
+        self.data = data
+        self.series = series
+        self.scale = scale
+        self.start_date = start_date
+        self.end_date = end_date
+        self.baseline = baseline
+        self.format = format or Format()
+        self.legend = legend
+        self.figsize = figsize
+        self.plot_size = plot_size
+
+    @classmethod
+    def from_yaml(cls, loader: TemplateLoader, node: MappingNode) -> Self:
+        cfg: dict[str, Any] = loader.construct_mapping(  # type: ignore[assignment]
+            node, deep=True
+        )
+        cfg.pop("id")
+        cfg["out_path"] = Path(cfg["out_path"])
+        cfg["data"] = pd.read_feather(cfg.pop("data_path"))
+        return cls(**cfg)
+
+    def plot(self) -> Axes:
+        start = (
+            pd.Timestamp(self.start_date)
+            if self.start_date
+            else self.data.index.min()
+        )
+        end = (
+            pd.Timestamp(self.end_date)
+            if self.end_date
+            else self.data.index.max()
+        )
+
+        plot_data = self.data.loc[start:end, list(self.series.keys())].dropna()
+        plot_data = plot_data * self.scale
+
+        fig_kw = dict(FIG_CONFIG)
+        if self.figsize is not None:
+            fig_kw["figsize"] = self.figsize
+        fig: Figure = plt.figure(  # type: ignore[reportUnknownMemberType]
+            **fig_kw
+        )
+        ax: Axes = fig.add_subplot()
+
+        labels = list(self.series.values())
+        arrays: list[np.ndarray[tuple[int], np.dtype[np.float64]]] = [
+            plot_data[col].to_numpy(dtype=np.float64) for col in self.series
+        ]
+        ax.stackplot(  # type: ignore[reportUnknownMemberType]
+            plot_data.index,
+            *arrays,
+            labels=labels,
+            alpha=0.85,
+        )
+
+        style_spines(
+            ax,
+            decimals=self.format.decimals,
+            units=self.format.units,
+            **AX_CONFIG["spines"],
+        )
+        if self.baseline:
+            style_baseline(ax, 0, **AX_CONFIG["baseline"])
+
+        legend_ncol = self.legend.ncol if self.legend else None
+        ncol = legend_ncol if legend_ncol is not None else auto_ncol(ax, labels)
+        sep = self.legend.sep if self.legend else _DEFAULT_SEP
+        ax.legend(  # type: ignore[reportUnknownMemberType]
+            loc="upper center",
+            bbox_to_anchor=(0.5, sep),
+            ncol=ncol,
+        )
+
+        if self.plot_size is not None:
+            adjust_figure_for_plot_size(fig, ax, self.plot_size)
+
+        fig.savefig(  # type: ignore[reportUnknownMemberType]
+            self.out_path
+        )
+        plt.close(fig)
+        return ax
+
+
+class StackedBarPlot:
+    """Stacked bar chart with the tesorotools visual style.
+
+    Positive and negative values are stacked separately so
+    that bars extend in both directions from the baseline.
+    """
+
+    def __init__(
+        self,
+        out_path: Path,
+        data: pd.DataFrame,
+        series: dict[str, str],
+        *,
+        scale: float = 1,
+        start_date: str | None = None,
+        end_date: str | None = None,
+        baseline: bool = True,
+        format: Format | None = None,
+        legend: Legend | None = None,
+        figsize: tuple[float, float] | None = None,
+        overlay_series: dict[str, str] | None = None,
+        plot_size: tuple[float, float] | None = None,
+    ) -> None:
+        if out_path.suffix != ".png":
+            raise ValueError(f"out_path must be .png: {out_path}")
+        self.out_path = out_path
+        self.data = data
+        self.series = series
+        self.scale = scale
+        self.start_date = start_date
+        self.end_date = end_date
+        self.baseline = baseline
+        self.format = format or Format()
+        self.legend = legend
+        self.plot_size = plot_size
+        self.figsize = figsize
+        self.overlay_series = overlay_series or {}
+
+    @classmethod
+    def from_yaml(cls, loader: TemplateLoader, node: MappingNode) -> Self:
+        cfg: dict[str, Any] = loader.construct_mapping(  # type: ignore[assignment]
+            node, deep=True
+        )
+        cfg.pop("id")
+        cfg["out_path"] = Path(cfg["out_path"])
+        cfg["data"] = pd.read_feather(cfg.pop("data_path"))
+        return cls(**cfg)
+
+    def plot(self) -> Axes:
+        start = (
+            pd.Timestamp(self.start_date)
+            if self.start_date
+            else self.data.index.min()
+        )
+        end = (
+            pd.Timestamp(self.end_date)
+            if self.end_date
+            else self.data.index.max()
+        )
+
+        all_cols = list(self.series.keys()) + list(self.overlay_series.keys())
+        plot_data = self.data.loc[start:end, all_cols].dropna()
+        plot_data = plot_data * self.scale
+
+        fig_kw = dict(FIG_CONFIG)
+        if self.figsize is not None:
+            fig_kw["figsize"] = self.figsize
+        fig: Figure = plt.figure(  # type: ignore[reportUnknownMemberType]
+            **fig_kw
+        )
+        ax: Axes = fig.add_subplot()
+
+        cols = list(self.series.keys())
+        labels = list(self.series.values())
+
+        x = np.arange(len(plot_data))
+        bar_width = 0.7
+
+        pos_bottom: np.ndarray[tuple[int], np.dtype[np.float64]] = np.zeros(
+            len(plot_data)
+        )
+        neg_bottom: np.ndarray[tuple[int], np.dtype[np.float64]] = np.zeros(
+            len(plot_data)
+        )
+
+        for col, label in zip(cols, labels):
+            values: np.ndarray[tuple[int], np.dtype[np.float64]] = plot_data[
+                col
+            ].to_numpy(dtype=np.float64)
+            pos: np.ndarray[tuple[int], np.dtype[np.float64]] = np.where(
+                values >= 0, values, 0.0
+            )
+            neg: np.ndarray[tuple[int], np.dtype[np.float64]] = np.where(
+                values < 0, values, 0.0
+            )
+
+            color = (
+                ax.bar(  # type: ignore[reportUnknownMemberType]
+                    x,
+                    pos,
+                    bottom=pos_bottom,
+                    width=bar_width,
+                    label=label,
+                )
+                .patches[0]
+                .get_facecolor()
+            )
+            ax.bar(  # type: ignore[reportUnknownMemberType]
+                x,
+                neg,
+                bottom=neg_bottom,
+                width=bar_width,
+                color=color,
+            )
+            pos_bottom = pos_bottom + pos
+            neg_bottom = neg_bottom + neg
+
+        for o_col, o_label in self.overlay_series.items():
+            o_vals = plot_data[o_col].to_numpy(dtype=np.float64)
+            ax.plot(  # type: ignore[reportUnknownMemberType]
+                x,
+                o_vals,
+                color="black",
+                linewidth=1.5,
+                label=o_label,
+                zorder=10,
+            )
+
+        dates = plot_data.index
+        step = max(1, len(dates) // 12)
+        tick_pos = list(range(0, len(dates), step))
+        tick_labels = [dates[i].strftime("%Y") for i in tick_pos]
+        ax.set_xticks(  # type: ignore[reportUnknownMemberType]
+            tick_pos
+        )
+        ax.set_xticklabels(  # type: ignore[reportUnknownMemberType]
+            tick_labels
+        )
+
+        style_spines(
+            ax,
+            decimals=self.format.decimals,
+            units=self.format.units,
+            **AX_CONFIG["spines"],
+        )
+        if self.baseline:
+            style_baseline(ax, 0, **AX_CONFIG["baseline"])
+
+        all_labels = list(self.series.values()) + list(
+            self.overlay_series.values()
+        )
+        legend_ncol = self.legend.ncol if self.legend else None
+        ncol = (
+            legend_ncol
+            if legend_ncol is not None
+            else auto_ncol(ax, all_labels)
+        )
+        sep = self.legend.sep if self.legend else _DEFAULT_SEP
+        ax.legend(  # type: ignore[reportUnknownMemberType]
+            loc="upper center",
+            bbox_to_anchor=(0.5, sep),
+            ncol=ncol,
+        )
+
+        if self.plot_size is not None:
+            adjust_figure_for_plot_size(fig, ax, self.plot_size)
+
+        fig.savefig(  # type: ignore[reportUnknownMemberType]
+            self.out_path
+        )
+        plt.close(fig)
+        return ax