tesorotools-python 0.0.33__tar.gz → 0.0.35__tar.gz

{tesorotools_python-0.0.33 → tesorotools_python-0.0.35}/PKG-INFO

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

{tesorotools_python-0.0.33 → tesorotools_python-0.0.35}/pyproject.toml

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

{tesorotools_python-0.0.33 → tesorotools_python-0.0.35}/src/tesorotools/artists/line_plot.py

@@ -1,7 +1,7 @@
 import datetime
 import locale
 from pathlib import Path
-from typing import Any, Self
+from typing import Any, Self, cast
 
 import matplotlib.pyplot as plt
 import pandas as pd
@@ -218,6 +218,27 @@ def annotate_last_values(
     ax.set_xlim(xmin, xmax + (x1 - x0))
 
 
+def draw_vlines(ax: Axes, vlines: list[dict[str, Any]]) -> None:
+    """Draw labelled vertical event markers on *ax*.
+
+    Each entry must provide ``x`` (date-like). Optional keys
+    (``label``, ``color``, ``linestyle``, ``linewidth``, ...) are
+    forwarded to ``ax.axvline``. ``linestyle`` defaults to
+    ``"dashed"`` so markers are visually distinct from data lines.
+    """
+    for vline in vlines:
+        kwargs: dict[str, Any] = dict(vline)
+        x_raw: Any = kwargs.pop("x")
+        # matplotlib's stub types axvline's x as float, but at runtime
+        # it accepts any date-like recognised by the date converter.
+        x_dt = cast(Any, pd.to_datetime(x_raw))  # type: ignore[reportUnknownMemberType]
+        kwargs.setdefault("linestyle", "dashed")
+        ax.axvline(  # type: ignore[reportUnknownMemberType]
+            x=x_dt,
+            **kwargs,
+        )
+
+
 def style_spines(
     ax: Axes,
     decimals: int,
@@ -289,21 +310,20 @@ def style_baseline(
     reference: float = 0,
     **baseline_config: Any,
 ) -> None:
-    color: str = baseline_config["color"]
+    """Draw a horizontal baseline at *reference*.
+
+    Always uses ``axhline`` (with high zorder) so callers that
+    later restyle the spines do not silently erase the baseline.
+    """
     bottom_lim, top_lim = ax.get_ylim()
     ax.set_ylim(
         bottom=min(reference, bottom_lim),
         top=max(reference, top_lim),
     )
-    bottom_lim, top_lim = ax.get_ylim()
-    if bottom_lim == reference:
-        ax.spines["bottom"].set_edgecolor(color)
-    elif top_lim == reference:
-        ax.spines["top"].set_edgecolor(color)
-    else:
-        ax.axhline(  # type: ignore[reportUnknownMemberType]
-            y=reference, **baseline_config
-        )
+    baseline_config.setdefault("zorder", 2.5)
+    ax.axhline(  # type: ignore[reportUnknownMemberType]
+        y=reference, **baseline_config
+    )
 
 
 def plot_line_chart(
@@ -312,12 +332,12 @@ def plot_line_chart(
     *,
     base_100: bool,
     annotate: bool,
-    format: dict[str, Any],
+    fmt: dict[str, Any],
     **kwargs: Any,
 ) -> None:
     if base_100:
         data = data / data.iloc[0, :] * 100
-    if format["units"] == "p.b.":
+    if fmt["units"] == "p.b.":
         data = data * 100
     fig: Figure = plt.figure(  # type: ignore[reportUnknownMemberType]
         **FIG_CONFIG
@@ -328,11 +348,13 @@ def plot_line_chart(
         pass
 
     reference = 100 if base_100 else 0
-    style_spines(ax, **format, **AX_CONFIG["spines"])
+    style_spines(ax, **fmt, **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"]),
+    handles, label_strs = ax.get_legend_handles_labels()
+    fig.legend(  # type: ignore[reportUnknownMemberType]
+        handles,
+        label_strs,
+        loc="outside lower center",
         ncol=(
             kwargs["legend"]["ncol"]
             if kwargs.get("legend", None) is not None
@@ -386,10 +408,8 @@ class Legend:
     def __init__(
         self,
         ncol: int | None = None,
-        sep: float | None = None,
     ) -> None:
         self.ncol = ncol
-        self.sep = sep
 
     @classmethod
     def from_yaml(cls, loader: TemplateLoader, node: MappingNode) -> Self:
@@ -411,15 +431,17 @@ class LinePlot:
         start_date: datetime.datetime | None = None,
         end_date: datetime.datetime | None = None,
         base_100: bool = False,
+        base_100_date: datetime.datetime | str | None = None,
         annotate: bool = False,
         annotate_color: str | None = None,
         baseline: bool = False,
-        format: Format | None = None,
+        fmt: 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,
+        vlines: list[dict[str, Any]] | None = None,
     ) -> None:
 
         if out_path.suffix != ".png":
@@ -443,9 +465,10 @@ class LinePlot:
             raise ValueError("series is required")
 
         self.base_100 = base_100
+        self.base_100_date = base_100_date
         self.annotate = annotate
         self.annotate_color = annotate_color
-        self.format = format
+        self.fmt = fmt
         self.start_date = start_date
         self.end_date = end_date
         self.series = series
@@ -455,6 +478,7 @@ class LinePlot:
         self.figsize = figsize
         self.series_styles = series_styles or {}
         self.plot_size = plot_size
+        self.vlines = vlines or []
 
     @classmethod
     def from_yaml(cls, loader: TemplateLoader, node: MappingNode) -> Self:
@@ -466,7 +490,13 @@ class LinePlot:
         line_plot_cfg["data_path"] = Path(line_plot_cfg["data_path"])
         return cls(**line_plot_cfg)
 
-    def plot(self) -> Axes:
+    def build(self) -> tuple[Figure, Axes]:
+        """Render the chart in memory without writing to disk.
+
+        Returns the ``(Figure, Axes)`` so callers can post-process
+        before saving (extra annotations, override DPI, embed in a
+        composite figure). Pair with :meth:`save` to persist.
+        """
         start_date: pd.Timestamp = (
             self.data.index.min()
             if self.start_date is None
@@ -485,8 +515,19 @@ class LinePlot:
 
         plot_data = plot_data * self.scale
 
-        if self.base_100:  # maybe more flexible in the future
-            plot_data = plot_data / plot_data.iloc[0, :] * 100
+        if self.base_100:
+            if self.base_100_date is None:
+                anchor: pd.Series[float] = plot_data.iloc[0, :]
+            else:
+                anchor_ts: pd.Timestamp = pd.to_datetime(self.base_100_date)
+                idx_pos: int = self.data.index.get_indexer(
+                    pd.Index([anchor_ts]), method="nearest"
+                )[0]
+                anchor = (
+                    self.data.iloc[idx_pos, :].loc[list(self.series.keys())]
+                    * self.scale
+                )
+            plot_data = plot_data / anchor * 100
 
         fig_kw = dict(FIG_CONFIG)
         if self.figsize is not None:
@@ -500,13 +541,16 @@ class LinePlot:
             style = styles.get(col, {}) if styles else {}
             plot_data[col].plot(ax=ax, label=self.series[col], **style)
 
-        assert self.format is not None
+        if self.vlines:
+            draw_vlines(ax, self.vlines)
+
+        assert self.fmt is not None
         if self.annotate:
             annotate_last_values(
                 ax,
                 plot_data,
-                decimals=self.format.decimals,
-                units=self.format.units,
+                decimals=self.fmt.decimals,
+                units=self.fmt.units,
                 labels=self.series,
                 series_styles=self.series_styles,
                 annotate_color=self.annotate_color,
@@ -514,8 +558,8 @@ class LinePlot:
 
         style_spines(  # maybe make this function accept a Format object
             ax,
-            decimals=self.format.decimals,
-            units=self.format.units,
+            decimals=self.fmt.decimals,
+            units=self.fmt.units,
             **AX_CONFIG["spines"],
         )
         if self.baseline:
@@ -524,30 +568,54 @@ class LinePlot:
 
         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)
-            )
-            sep = (
-                self.legend.sep
-                if self.legend.sep is not None
-                else LINE_PLOT_CONFIG["legend_sep"]
+                else auto_ncol(ax, labels, available_width_px=fig_width_px)
             )
-            ax.legend(  # type: ignore[reportUnknownMemberType]
-                loc="upper center",
-                bbox_to_anchor=(0.5, sep),
+            fig.legend(  # type: ignore[reportUnknownMemberType]
+                handles,
+                label_strs,
+                loc="outside lower center",
                 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)
 
+        return fig, ax
+
+    def save(
+        self,
+        fig: Figure,
+        *,
+        path: Path | None = None,
+        dpi: int | None = None,
+    ) -> Path:
+        """Persist *fig* as a PNG. Returns the path written.
+
+        Defaults to ``self.out_path``; pass ``path`` to redirect or
+        ``dpi`` to override the figure DPI for the saved file
+        (useful when embedding in Word at fixed widths, where the
+        default 500 dpi balloons file sizes).
+        """
+        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]
-            self.out_path
+            target, **save_kwargs
         )
+        return target
+
+    def plot(self) -> Axes:
+        """Build the chart and persist it to ``self.out_path``.
+
+        Kept for backwards compatibility; new callers should prefer
+        :meth:`build` + :meth:`save` for finer control.
+        """
+        fig, ax = self.build()
+        self.save(fig)
         return ax

{tesorotools_python-0.0.33 → tesorotools_python-0.0.35}/src/tesorotools/artists/stacked.py

@@ -22,8 +22,6 @@ from tesorotools.artists.line_plot import (
 )
 from tesorotools.utils.config import TemplateLoader
 
-_DEFAULT_SEP = -0.125
-
 
 class StackedAreaPlot:
     """Stacked area chart with the tesorotools visual style.
@@ -43,7 +41,7 @@ class StackedAreaPlot:
         start_date: str | None = None,
         end_date: str | None = None,
         baseline: bool = False,
-        format: Format | None = None,
+        fmt: Format | None = None,
         legend: Legend | None = None,
         figsize: tuple[float, float] | None = None,
         plot_size: tuple[float, float] | None = None,
@@ -57,7 +55,7 @@ class StackedAreaPlot:
         self.start_date = start_date
         self.end_date = end_date
         self.baseline = baseline
-        self.format = format or Format()
+        self.fmt = fmt or Format()
         self.legend = legend
         self.figsize = figsize
         self.plot_size = plot_size
@@ -109,23 +107,25 @@ class StackedAreaPlot:
 
         style_spines(
             ax,
-            decimals=self.format.decimals,
-            units=self.format.units,
+            decimals=self.fmt.decimals,
+            units=self.fmt.units,
             **AX_CONFIG["spines"],
         )
         if self.baseline:
             style_baseline(ax, 0, **AX_CONFIG["baseline"])
 
+        fig_width_px: float = fig.get_size_inches()[0] * fig.dpi
         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 and self.legend.sep is not None
-            else _DEFAULT_SEP
+        ncol = (
+            legend_ncol
+            if legend_ncol is not None
+            else auto_ncol(ax, labels, available_width_px=fig_width_px)
         )
-        ax.legend(  # type: ignore[reportUnknownMemberType]
-            loc="upper center",
-            bbox_to_anchor=(0.5, sep),
+        handles, label_strs = ax.get_legend_handles_labels()
+        fig.legend(  # type: ignore[reportUnknownMemberType]
+            handles,
+            label_strs,
+            loc="outside lower center",
             ncol=ncol,
         )
 
@@ -163,7 +163,7 @@ class StackedBarPlot:
         start_date: str | None = None,
         end_date: str | None = None,
         baseline: bool = True,
-        format: Format | None = None,
+        fmt: Format | None = None,
         legend: Legend | None = None,
         figsize: tuple[float, float] | None = None,
         overlay_series: dict[str, str] | None = None,
@@ -180,7 +180,7 @@ class StackedBarPlot:
         self.start_date = start_date
         self.end_date = end_date
         self.baseline = baseline
-        self.format = format or Format()
+        self.fmt = fmt or Format()
         self.legend = legend
         self.plot_size = plot_size
         self.figsize = figsize
@@ -313,8 +313,8 @@ class StackedBarPlot:
 
         style_spines(
             ax,
-            decimals=self.format.decimals,
-            units=self.format.units,
+            decimals=self.fmt.decimals,
+            units=self.fmt.units,
             **AX_CONFIG["spines"],
         )
         if self.baseline:
@@ -323,20 +323,18 @@ class StackedBarPlot:
         all_labels = list(self.series.values()) + list(
             self.overlay_series.values()
         )
+        fig_width_px: float = fig.get_size_inches()[0] * fig.dpi
         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 and self.legend.sep is not None
-            else _DEFAULT_SEP
+            else auto_ncol(ax, all_labels, available_width_px=fig_width_px)
         )
-        ax.legend(  # type: ignore[reportUnknownMemberType]
-            loc="upper center",
-            bbox_to_anchor=(0.5, sep),
+        handles, label_strs = ax.get_legend_handles_labels()
+        fig.legend(  # type: ignore[reportUnknownMemberType]
+            handles,
+            label_strs,
+            loc="outside lower center",
             ncol=ncol,
         )