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

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

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

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

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

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

@@ -310,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(
@@ -333,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
@@ -349,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
@@ -407,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:
@@ -436,7 +435,7 @@ class LinePlot:
         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,
@@ -469,7 +468,7 @@ class LinePlot:
         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
@@ -545,13 +544,13 @@ class LinePlot:
         if self.vlines:
             draw_vlines(ax, self.vlines)
 
-        assert self.format is not None
+        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,
@@ -559,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:
@@ -569,25 +568,19 @@ 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)

{tesorotools_python-0.0.34 → 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,
         )
 

{tesorotools_python-0.0.34 → tesorotools_python-0.0.35}/src/tesorotools/artists/type_curve.py

@@ -167,9 +167,11 @@ def plot_type_curve(
     style_spines(ax, **merged_config["yaxis"], **AX_CONFIG["spines"])
     _rotate_xticks(ax)
     style_baseline(ax, 0, **AX_CONFIG["baseline"])
-    ax.legend(  # type: ignore[reportUnknownMemberType]
-        loc="upper center",
-        bbox_to_anchor=(0.5, merged_config["legend_sep"]),
+    handles, labels = ax.get_legend_handles_labels()
+    fig.legend(  # type: ignore[reportUnknownMemberType]
+        handles,
+        labels,
+        loc="outside lower center",
         ncol=3,
     )
     fig.savefig(  # type: ignore[reportUnknownMemberType]

{tesorotools_python-0.0.34 → tesorotools_python-0.0.35}/src/tesorotools/assets/plots.yaml

@@ -28,14 +28,12 @@ type_curve:
     linewidth: 2
     marker: D
     color: C0
-  legend_sep: -0.1
 
 barh:
   highlight_factor: 0.4
   padding: 5
 
 line:
-  legend_sep: -0.125
   ncol: 5
 
 table:

tesorotools_python-0.0.35/src/tesorotools/driver.py

@@ -0,0 +1,138 @@
+"""Schema-agnostic YAML → docx driver with a plug-in renderer registry.
+
+Each project that consumes tesorotools wraps its data sources in a
+small adapter, and then declares its charts/tables/text blocks in a
+YAML file. This module dispatches those declarations to the right
+renderer at runtime, so projects share the orchestration code instead
+of each one growing its own ``driver.py``.
+
+Typical usage::
+
+    from tesorotools import driver
+    from tesorotools.artists.line_plot import LinePlot
+
+    def render_line(document, cfg, ctx):
+        chart = LinePlot(out_path=Path(cfg["out_path"]), ...)
+        chart.plot()
+        # then embed the PNG into ``document``...
+
+    driver.register_renderer("line", render_line)
+    items = driver.load(yaml_path)["charts"]
+    driver.render(document, items, ctx={"year": 2026})
+
+Renderers are looked up by the ``type`` key on each item; selecting
+which items to render in a given pass is done with the ``section``
+and ``on_table`` filters, mirroring the diary/reports use case where
+some charts go before the tables and others embed inside them.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Callable, Mapping
+
+from docx.document import Document
+
+from tesorotools.utils.config import read_config
+
+Renderer = Callable[[Document, dict[str, Any], Mapping[str, Any]], None]
+
+_REGISTRY: dict[str, Renderer] = {}
+
+
+def register_renderer(type_name: str, renderer: Renderer) -> None:
+    """Register *renderer* for items declaring ``type: <type_name>``.
+
+    Calling twice with the same name overwrites the previous entry,
+    so projects can swap implementations in tests.
+    """
+    _REGISTRY[type_name] = renderer
+
+
+def unregister_renderer(type_name: str) -> None:
+    """Remove a previously registered renderer; no-op if absent."""
+    _REGISTRY.pop(type_name, None)
+
+
+def registered_types() -> list[str]:
+    """Names currently in the registry, sorted alphabetically."""
+    return sorted(_REGISTRY)
+
+
+def load(path: Path) -> dict[str, Any]:
+    """Read a driver YAML file. Pure I/O wrapper around ``read_config``."""
+    return read_config(path)
+
+
+def _substitute_tokens(value: Any, ctx: Mapping[str, Any]) -> Any:
+    """Recursively substitute ``{token}`` placeholders in strings.
+
+    Unknown tokens are left literal so partially-templated YAML is
+    still readable when ctx is incomplete (useful in tests). Lists
+    and dicts are walked; non-string leaves pass through untouched.
+    """
+    if isinstance(value, str):
+        try:
+            return value.format_map(_SafeMapping(ctx))
+        except (KeyError, IndexError, ValueError):
+            return value
+    if isinstance(value, list):
+        return [_substitute_tokens(v, ctx) for v in value]  # type: ignore[reportUnknownVariableType]
+    if isinstance(value, dict):
+        return {k: _substitute_tokens(v, ctx) for k, v in value.items()}  # type: ignore[reportUnknownVariableType]
+    return value
+
+
+class _SafeMapping(dict[str, Any]):
+    """``str.format_map`` mapping that leaves unknown keys literal."""
+
+    def __init__(self, base: Mapping[str, Any]) -> None:
+        super().__init__(base)
+
+    def __missing__(self, key: str) -> str:
+        return "{" + key + "}"
+
+
+def render(
+    document: Document,
+    items: Mapping[str, dict[str, Any]],
+    ctx: Mapping[str, Any] | None = None,
+    *,
+    section: str | None = None,
+    on_table: str | None = None,
+) -> None:
+    """Render every item in *items* whose filters match.
+
+    *items* maps item ids to configuration dicts; each dict must
+    declare a ``type`` key that resolves to a registered renderer.
+    String values inside the config (titles, labels, paths) are
+    formatted against *ctx*: ``"Bolsas {year}"`` with
+    ``ctx={"year": 2026}`` becomes ``"Bolsas 2026"``. Missing tokens
+    are left as literals.
+
+    Filters:
+
+    - ``section`` — only render items whose ``section`` field equals
+      this value (e.g. ``"pre_tables"`` vs ``"intro"``).
+    - ``on_table`` — only render items whose ``on_table`` field
+      equals this value, used to embed charts beside specific tables.
+
+    When both filters are ``None`` every item is rendered.
+    Items declaring an unknown ``type`` raise ``KeyError`` so the
+    misconfiguration surfaces immediately.
+    """
+    ctx_resolved: Mapping[str, Any] = ctx if ctx is not None else {}
+    for item_id, raw_cfg in items.items():
+        if section is not None and raw_cfg.get("section") != section:
+            continue
+        if on_table is not None and raw_cfg.get("on_table") != on_table:
+            continue
+        cfg: dict[str, Any] = _substitute_tokens(dict(raw_cfg), ctx_resolved)
+        cfg["id"] = item_id
+        type_name: str = cfg.get("type", "")
+        if type_name not in _REGISTRY:
+            raise KeyError(
+                f"No renderer registered for type {type_name!r} "
+                f"(item {item_id!r}). Available: {registered_types()}"
+            )
+        _REGISTRY[type_name](document, cfg, ctx_resolved)

{tesorotools_python-0.0.34 → tesorotools_python-0.0.35}/src/tesorotools/render/content/table.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 # pyright: reportPrivateUsage=false
+from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Self
 
@@ -22,6 +23,27 @@ from tesorotools.utils.template import TemplateLoader
 
 RENDER_CONFIG: dict[str, Any] = read_config(PLOT_CONFIG_FILE)["table"]
 
+
+@dataclass(frozen=True)
+class RenderConfig:
+    """Per-call rendering options for :func:`render_table`.
+
+    Attributes match the ``table`` section of the bundled
+    ``plots.yaml``; defaults are read from there. Pass an instance
+    explicitly to override the global config without monkey-patching.
+    """
+
+    style: str | None = None
+    autofit: bool = False
+
+    @classmethod
+    def from_global(cls) -> RenderConfig:
+        return cls(
+            style=RENDER_CONFIG.get("style"),
+            autofit=bool(RENDER_CONFIG["autofit"]),
+        )
+
+
 TEXTO_TABLAS: int = 9
 
 CENTER = WD_ALIGN_PARAGRAPH.CENTER
@@ -250,9 +272,9 @@ def _fill_content(
         _style_content(cell)
 
 
-def _style_table(table_docx: TableDocx) -> None:
-    table_docx.style = RENDER_CONFIG.get("style", None)
-    table_docx.autofit = RENDER_CONFIG["autofit"]
+def _style_table(table_docx: TableDocx, config: RenderConfig) -> None:
+    table_docx.style = config.style
+    table_docx.autofit = config.autofit
 
 
 def render_table(
@@ -261,16 +283,29 @@ def render_table(
     shade_table: pd.DataFrame | None,
     document: Document,
     block_sep: bool,
+    *,
+    config: RenderConfig | None = None,
     **kwargs: Any,
-) -> Document:
-
+) -> TableDocx:
+    """Append a styled table to *document* and return the ``Table``.
+
+    Returning the ``docx.table.Table`` mirrors python-docx's own
+    ``add_*`` helpers (``add_paragraph``, ``add_heading``) and lets
+    callers post-process the table (alignment overrides, custom
+    borders, references for navigation) without resorting to
+    ``document.tables[-1]``. Pass *config* to override the global
+    rendering style/autofit on a per-call basis.
+    """
+    cfg: RenderConfig = (
+        config if config is not None else RenderConfig.from_global()
+    )
     horizontal: bool = isinstance(table.columns, pd.MultiIndex)
     table_docx: TableDocx = document.add_table(
         rows=len(table.index) + table.columns.nlevels,
         cols=len(table.columns) + 1,
     )
 
-    _style_table(table_docx)
+    _style_table(table_docx, cfg)
     _fill_column_names(table, table_docx, horizontal)
     _fill_index_names(
         index=table.index,
@@ -282,7 +317,7 @@ def render_table(
         _separate_blocks(table.index, table_docx)
     _fill_content(table, color_table, shade_table, table_docx, horizontal)
     table_docx.alignment = WD_TABLE_ALIGNMENT.CENTER
-    return document
+    return table_docx
 
 
 class Table: