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

{tesorotools_python-0.0.25 → tesorotools_python-0.0.26}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tesorotools-python
-Version: 0.0.25
+Version: 0.0.26
 Requires-Python: >=3.13
 Requires-Dist: babel>=2.17
 Requires-Dist: eikon>=1.1

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

@@ -1,7 +1,7 @@
 [project]
 name = "tesorotools-python"
 requires-python = ">=3.13"
-version = "0.0.25"
+version = "0.0.26"
 dependencies = [
     # database and ORM
     "psycopg[binary]>=3.1",

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.25 → tesorotools_python-0.0.26}/src/tesorotools/artists/line_plot.py

@@ -26,6 +26,76 @@ AX_CONFIG: dict[str, Any] = PLOT_CONFIG["ax"]
 FIG_CONFIG: dict[str, Any] = PLOT_CONFIG["figure"]
 
 
+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,
@@ -62,6 +132,36 @@ def style_spines(
         tick.set_markeredgecolor(color)
 
 
+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,
@@ -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
 
@@ -190,6 +294,9 @@ class LinePlot:
         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":
@@ -221,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:
@@ -255,11 +365,19 @@ 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
@@ -276,19 +394,28 @@ class LinePlot:
             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.25 → tesorotools_python-0.0.26}/src/tesorotools/artists/stacked.py

@@ -15,12 +15,13 @@ from tesorotools.artists.line_plot import (
     FIG_CONFIG,
     Format,
     Legend,
+    adjust_figure_for_plot_size,
+    auto_ncol,
     style_baseline,
     style_spines,
 )
 from tesorotools.utils.config import TemplateLoader
 
-_DEFAULT_NCOL = 5
 _DEFAULT_SEP = -0.125
 
 
@@ -44,6 +45,8 @@ class StackedAreaPlot:
         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}")
@@ -56,6 +59,8 @@ class StackedAreaPlot:
         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:
@@ -82,8 +87,11 @@ class StackedAreaPlot:
         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_CONFIG
+            **fig_kw
         )
         ax: Axes = fig.add_subplot()
 
@@ -107,7 +115,8 @@ class StackedAreaPlot:
         if self.baseline:
             style_baseline(ax, 0, **AX_CONFIG["baseline"])
 
-        ncol = self.legend.ncol if self.legend else _DEFAULT_NCOL
+        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",
@@ -115,6 +124,9 @@ class StackedAreaPlot:
             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
         )
@@ -141,6 +153,9 @@ class StackedBarPlot:
         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}")
@@ -153,6 +168,9 @@ class StackedBarPlot:
         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:
@@ -176,11 +194,15 @@ class StackedBarPlot:
             else self.data.index.max()
         )
 
-        plot_data = self.data.loc[start:end, list(self.series.keys())].dropna()
+        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]
-            figsize=(12, 6), **FIG_CONFIG
+            **fig_kw
         )
         ax: Axes = fig.add_subplot()
 
@@ -229,6 +251,17 @@ class StackedBarPlot:
             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))
@@ -249,7 +282,15 @@ class StackedBarPlot:
         if self.baseline:
             style_baseline(ax, 0, **AX_CONFIG["baseline"])
 
-        ncol = self.legend.ncol if self.legend else _DEFAULT_NCOL
+        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",
@@ -257,6 +298,9 @@ class StackedBarPlot:
             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
         )

tesorotools_python-0.0.26/src/tesorotools/pipeline/diagnose.py

@@ -0,0 +1,54 @@
+"""Diagnostic utilities for pipeline configuration.
+
+Helps identify unused series in a catalog — series that
+are downloaded but never appear as a dependency of any
+rule or in any chart configuration.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from tesorotools.dependencies.resolution import (
+    collect_document_series,
+)
+from tesorotools.pipeline.engine import TransformationRule
+
+
+def unused_series(
+    catalog: dict[str, Any],
+    rules: list[TransformationRule],
+    charts: dict[str, Any] | list[dict[str, Any]] | None = None,
+) -> set[str]:
+    """Find catalog series not referenced by rules or charts.
+
+    Parameters
+    ----------
+    catalog
+        Instrument catalog (canonical_id -> metadata).
+    rules
+        All transformation rules for the project.
+    charts
+        Chart config dict(s).  Can be a single dict or a
+        list of dicts (barh, line, type_curve, tables).
+
+    Returns
+    -------
+    set[str]
+        Canonical IDs present in the catalog but not used
+        as a dependency of any rule nor referenced in any
+        chart config.
+    """
+    all_ids = set(catalog.keys())
+
+    used: set[str] = set()
+    for rule in rules:
+        used.add(rule.output_name)
+        used.update(rule.dependencies)
+
+    if charts is not None:
+        chart_list = charts if isinstance(charts, list) else [charts]
+        for name in collect_document_series(chart_list):
+            used.add(name)
+
+    return all_ids - used

{tesorotools_python-0.0.25 → tesorotools_python-0.0.26}/src/tesorotools/pipeline/rules.py

@@ -91,8 +91,10 @@ def inverse_rule(
     )
 
 
-def yoy_rule(output: str, source: str, periods: int = 12) -> TransformationRule:
-    """Year-over-year growth rate.
+def pct_change_rule(
+    output: str, source: str, periods: int = 12
+) -> TransformationRule:
+    """Periodic percentage change: source_t / source_{t-N} - 1.
 
     Drops NaN before shifting so that *periods* counts
     actual observations, not DataFrame rows.
@@ -137,6 +139,46 @@ def rolling_sum_rule(
     )
 
 
+def delta_rule(
+    output: str, source: str, periods: int = 1
+) -> TransformationRule:
+    """Level change: source_t - source_{t-periods}.
+
+    Drops NaN before shifting (mixed-frequency safe).
+    """
+
+    def _compute(
+        df: pd.DataFrame,
+        s: str = source,
+        p: int = periods,
+    ) -> pd.Series[float]:
+        clean: pd.Series[float] = df[s].dropna()
+        return clean - clean.shift(p)
+
+    return TransformationRule(
+        output_name=output,
+        dependencies=[source],
+        compute=_compute,
+    )
+
+
+def cumsum_rule(output: str, source: str) -> TransformationRule:
+    """Cumulative sum of a column.
+
+    Drops NaN before cumsum (mixed-frequency safe).
+    """
+
+    def _compute(df: pd.DataFrame, s: str = source) -> pd.Series[float]:
+        clean: pd.Series[float] = df[s].dropna()
+        return clean.cumsum()
+
+    return TransformationRule(
+        output_name=output,
+        dependencies=[source],
+        compute=_compute,
+    )
+
+
 #: Registry of factory functions, keyed by YAML function name.
 #: Projects can add custom factories at runtime.
 FACTORIES: dict[
@@ -148,6 +190,8 @@ FACTORIES: dict[
     "ratio": ratio_rule,
     "difference": difference_rule,
     "inverse": inverse_rule,
-    "yoy": yoy_rule,
+    "pct_change": pct_change_rule,
     "rolling_sum": rolling_sum_rule,
+    "delta": delta_rule,
+    "cumsum": cumsum_rule,
 }

tesorotools_python-0.0.26/src/tesorotools/utils/config.py

@@ -0,0 +1,98 @@
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from tesorotools.utils.template import TemplateLoader
+
+_tags_registered = False
+
+
+def _register_all_tags() -> None:
+    """Register every YAML tag on TemplateLoader.
+
+    Called once, lazily, the first time ``read_config`` is
+    invoked with ``loader=TemplateLoader``.  This removes
+    the need for consumers to import ``tesorotools.render``
+    or ``tesorotools.artists`` just for their side effects.
+    """
+    global _tags_registered  # noqa: PLW0603
+    if _tags_registered:
+        return
+    _tags_registered = True
+
+    # -- artists tags --
+    from tesorotools.artists.barh_plot import (
+        HorizontalBarChart,
+    )
+    from tesorotools.artists.line_plot import (
+        Format,
+        Legend,
+        LinePlot,
+    )
+    from tesorotools.artists.stacked import (
+        StackedAreaPlot,
+        StackedBarPlot,
+    )
+
+    TemplateLoader.add_constructor("!line_plot", LinePlot.from_yaml)
+    TemplateLoader.add_constructor("!format", Format.from_yaml)
+    TemplateLoader.add_constructor("!legend", Legend.from_yaml)
+    TemplateLoader.add_constructor("!stacked_area", StackedAreaPlot.from_yaml)
+    TemplateLoader.add_constructor("!stacked_bar", StackedBarPlot.from_yaml)
+    TemplateLoader.add_constructor("!barh", HorizontalBarChart.from_yaml)
+
+    # -- render tags --
+    from tesorotools.render.content.images import (
+        Image,
+        Images,
+    )
+    from tesorotools.render.content.section import Section
+    from tesorotools.render.content.subtitle import Subtitle
+    from tesorotools.render.content.table import Table
+    from tesorotools.render.content.text import Text
+    from tesorotools.render.content.title import Title
+    from tesorotools.render.report import Report
+
+    TemplateLoader.add_constructor("!report", Report.from_yaml)
+    TemplateLoader.add_constructor("!section", Section.from_yaml)
+    TemplateLoader.add_constructor("!image", Image.from_yaml)
+    TemplateLoader.add_constructor("!images", Images.from_yaml)
+    TemplateLoader.add_constructor("!table", Table.from_yaml)
+    TemplateLoader.add_constructor("!text", Text.from_yaml)
+    TemplateLoader.add_constructor("!title", Title.from_yaml)
+    TemplateLoader.add_constructor("!subtitle", Subtitle.from_yaml)
+
+
+def clean_config_dicts(
+    config_dicts: dict[str, Any],
+) -> dict[str, Any]:
+    return {k: v for k, v in config_dicts.items() if not k.startswith(".")}
+
+
+def read_config(
+    config_file: Path,
+    loader: type[yaml.FullLoader] | None = None,
+    clean: bool = True,
+) -> Any:
+    actual_loader: type[yaml.FullLoader] = (
+        yaml.FullLoader if loader is None else TemplateLoader
+    )
+    if actual_loader is TemplateLoader:
+        _register_all_tags()
+    with open(config_file, encoding="utf8") as file:
+        config_dict: Any = yaml.load(file, Loader=actual_loader)
+        if clean and isinstance(config_dict, dict):
+            config_dict = clean_config_dicts(config_dict)  # type: ignore[reportUnknownArgumentType]
+    return config_dict
+
+
+def merge(a: dict[str, Any], b: dict[str, Any]) -> dict[str, Any]:
+    # a overrides
+    for key in b:
+        if key in a:
+            if isinstance(a[key], dict) and isinstance(b[key], dict):
+                merge(a[key], b[key])
+        else:
+            a[key] = b[key]
+    return a

tesorotools_python-0.0.25/src/tesorotools/__init__.py

@@ -1,9 +0,0 @@
-from tesorotools.artists.line_plot import Format, Legend, LinePlot
-from tesorotools.artists.stacked import StackedAreaPlot, StackedBarPlot
-from tesorotools.utils.config import TemplateLoader
-
-TemplateLoader.add_constructor("!line_plot", LinePlot.from_yaml)
-TemplateLoader.add_constructor("!format", Format.from_yaml)
-TemplateLoader.add_constructor("!legend", Legend.from_yaml)
-TemplateLoader.add_constructor("!stacked_area", StackedAreaPlot.from_yaml)
-TemplateLoader.add_constructor("!stacked_bar", StackedBarPlot.from_yaml)

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

@@ -1,9 +0,0 @@
-import matplotlib.style
-
-from tesorotools.artists.barh_plot import HorizontalBarChart
-from tesorotools.utils.config import TemplateLoader
-
-from ..utils.globals import STYLE_SHEET
-
-matplotlib.style.use(STYLE_SHEET)
-TemplateLoader.add_constructor("!barh", HorizontalBarChart.from_yaml)

tesorotools_python-0.0.25/src/tesorotools/render/__init__.py

@@ -1,17 +0,0 @@
-from tesorotools.render.content.images import Image, Images
-from tesorotools.render.content.section import Section
-from tesorotools.render.content.subtitle import Subtitle
-from tesorotools.render.content.table import Table
-from tesorotools.render.content.text import Text
-from tesorotools.render.content.title import Title
-from tesorotools.render.report import Report
-from tesorotools.utils.template import TemplateLoader
-
-TemplateLoader.add_constructor("!report", Report.from_yaml)
-TemplateLoader.add_constructor("!section", Section.from_yaml)
-TemplateLoader.add_constructor("!image", Image.from_yaml)
-TemplateLoader.add_constructor("!images", Images.from_yaml)
-TemplateLoader.add_constructor("!table", Table.from_yaml)
-TemplateLoader.add_constructor("!text", Text.from_yaml)
-TemplateLoader.add_constructor("!title", Title.from_yaml)
-TemplateLoader.add_constructor("!subtitle", Subtitle.from_yaml)

tesorotools_python-0.0.25/src/tesorotools/utils/config.py

@@ -1,38 +0,0 @@
-from pathlib import Path
-from typing import Any
-
-import yaml
-
-from tesorotools.utils.template import TemplateLoader
-
-
-def clean_config_dicts(
-    config_dicts: dict[str, Any],
-) -> dict[str, Any]:
-    return {k: v for k, v in config_dicts.items() if not k.startswith(".")}
-
-
-def read_config(
-    config_file: Path,
-    loader: type[yaml.FullLoader] | None = None,
-    clean: bool = True,
-) -> Any:
-    actual_loader: type[yaml.FullLoader] = (
-        yaml.FullLoader if loader is None else TemplateLoader
-    )
-    with open(config_file, encoding="utf8") as file:
-        config_dict: Any = yaml.load(file, Loader=actual_loader)
-        if clean and isinstance(config_dict, dict):
-            config_dict = clean_config_dicts(config_dict)  # type: ignore[reportUnknownArgumentType]
-    return config_dict
-
-
-def merge(a: dict[str, Any], b: dict[str, Any]) -> dict[str, Any]:
-    # a overrides
-    for key in b:
-        if key in a:
-            if isinstance(a[key], dict) and isinstance(b[key], dict):
-                merge(a[key], b[key])
-        else:
-            a[key] = b[key]
-    return a