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

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

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

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

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

tesorotools_python-0.0.36/src/tesorotools/__init__.py

@@ -0,0 +1,115 @@
+"""tesorotools public API.
+
+Importing ``tesorotools`` eagerly loads artist and render
+classes (their modules run matplotlib/locale setup as side
+effects) and registers their YAML tags via
+``_register_builtins``.
+
+Provider subclasses gated by optional extras
+(``BdeProvider`` requires ``[bde]``, ``EcbProvider``
+requires ``[ecb]``) are exposed lazily through
+``__getattr__``; importing this module does not require the
+extras to be installed.
+
+Third parties extend the package via ``register_artist``,
+``register_tag``, and ``register_provider``.
+"""
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from tesorotools.providers.bde import BdeProvider
+    from tesorotools.providers.ecb import EcbProvider
+
+from tesorotools._registry import (
+    Artist,
+    get_artist,
+    get_provider,
+    register_artist,
+    register_provider,
+    register_tag,
+)
+from tesorotools.artists import (
+    Format,
+    HorizontalBarChart,
+    Legend,
+    LinePlot,
+    StackedAreaPlot,
+    StackedBarPlot,
+    TypeCurve,
+)
+from tesorotools.providers.base import DataProvider
+from tesorotools.render import (
+    Content,
+    Image,
+    Images,
+    Report,
+    Section,
+    Subtitle,
+    Table,
+    Text,
+    Title,
+)
+
+
+def _register_builtins() -> None:
+    register_artist("line_plot", LinePlot)
+    register_artist("stacked_area", StackedAreaPlot)
+    register_artist("stacked_bar", StackedBarPlot)
+    register_artist("barh", HorizontalBarChart)
+    register_artist("type_curve", TypeCurve)
+
+    register_tag("format", Format)
+    register_tag("legend", Legend)
+    register_tag("report", Report)
+    register_tag("section", Section)
+    register_tag("image", Image)
+    register_tag("images", Images)
+    register_tag("table", Table)
+    register_tag("text", Text)
+    register_tag("title", Title)
+    register_tag("subtitle", Subtitle)
+
+
+_register_builtins()
+
+
+__all__ = [
+    "Artist",
+    "BdeProvider",
+    "Content",
+    "DataProvider",
+    "EcbProvider",
+    "Format",
+    "HorizontalBarChart",
+    "Image",
+    "Images",
+    "Legend",
+    "LinePlot",
+    "Report",
+    "Section",
+    "StackedAreaPlot",
+    "StackedBarPlot",
+    "Subtitle",
+    "Table",
+    "Text",
+    "Title",
+    "TypeCurve",
+    "get_artist",
+    "get_provider",
+    "register_artist",
+    "register_provider",
+    "register_tag",
+]
+
+
+def __getattr__(name: str) -> Any:
+    if name == "BdeProvider":
+        from tesorotools.providers.bde import BdeProvider
+
+        return BdeProvider
+    if name == "EcbProvider":
+        from tesorotools.providers.ecb import EcbProvider
+
+        return EcbProvider
+    raise AttributeError(f"module 'tesorotools' has no attribute {name!r}")

tesorotools_python-0.0.36/src/tesorotools/_registry.py

@@ -0,0 +1,117 @@
+"""Registries for artists, providers, and YAML tags.
+
+Single source of truth for "name -> class" lookups used both
+by the YAML loader (``TemplateLoader``) and by code that
+dispatches by string name.
+
+Three public entry points:
+
+``register_artist(name, cls)``
+    Adds ``cls`` to the artist registry **and** registers the
+    YAML tag ``!{name}`` via ``cls.from_yaml``.  Use for
+    chart/figure classes (LinePlot, StackedAreaPlot, etc.).
+
+``register_tag(name, constructor)``
+    Registers a YAML tag ``!{name}`` only.  Use for things
+    that exist as YAML constructors but are not artists or
+    providers (Format, Legend, Title, Subtitle, Section,
+    Image, Text, Table, Report).
+
+``register_provider(name, cls)``
+    Adds ``cls`` to the provider registry.  Programmatic
+    only -- providers do not appear in YAML today.
+
+Look up registered classes via ``get_artist`` / ``get_provider``;
+both raise ``KeyError`` listing the available names.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Protocol, cast
+
+from yaml.nodes import MappingNode
+
+from tesorotools.providers.base import DataProvider
+from tesorotools.utils.template import TemplateLoader
+
+
+class Artist(Protocol):
+    """Anything constructible from a YAML mapping node.
+
+    Concrete artists satisfy this Protocol structurally;
+    inheriting from it is not required.
+
+    The ``loader`` parameter is typed as ``Any`` because some
+    in-tree ``from_yaml`` classmethods are declared with
+    ``yaml.Loader`` (the base class) and others with
+    ``TemplateLoader``; both work at runtime since the loader
+    is always a ``TemplateLoader``.
+    """
+
+    @classmethod
+    def from_yaml(cls, loader: Any, node: MappingNode) -> Any: ...
+
+
+YamlConstructor = Callable[[Any, MappingNode], Any]
+
+
+_ARTIST_REGISTRY: dict[str, type[Artist]] = {}
+_PROVIDER_REGISTRY: dict[str, type[DataProvider]] = {}
+
+
+def register_artist(name: str, cls: type[Artist]) -> None:
+    """Register ``cls`` as the artist for ``name``.
+
+    Adds ``cls`` to the artist registry and binds the YAML
+    tag ``!{name}`` to ``cls.from_yaml``.  Re-registering the
+    same name overrides both bindings.
+    """
+    _ARTIST_REGISTRY[name] = cls
+    TemplateLoader.add_constructor(
+        f"!{name}", cast(YamlConstructor, cls.from_yaml)
+    )
+
+
+def get_artist(name: str) -> type[Artist]:
+    try:
+        return _ARTIST_REGISTRY[name]
+    except KeyError:
+        available = sorted(_ARTIST_REGISTRY)
+        raise KeyError(
+            f"No artist registered as {name!r}. Available: {available}"
+        ) from None
+
+
+def register_provider(name: str, cls: type[DataProvider]) -> None:
+    """Register ``cls`` as the provider for ``name``."""
+    _PROVIDER_REGISTRY[name] = cls
+
+
+def get_provider(name: str) -> type[DataProvider]:
+    try:
+        return _PROVIDER_REGISTRY[name]
+    except KeyError:
+        available = sorted(_PROVIDER_REGISTRY)
+        raise KeyError(
+            f"No provider registered as {name!r}. Available: {available}"
+        ) from None
+
+
+def register_tag(
+    name: str,
+    constructor: type[Artist] | YamlConstructor,
+) -> None:
+    """Register a YAML tag ``!{name}``.
+
+    Accepts either a class with a ``from_yaml`` classmethod
+    or a bare callable matching the loader signature.  Use
+    ``register_artist`` / ``register_provider`` instead when
+    the registered name should also be looked up by code.
+    """
+    if isinstance(constructor, type):
+        cls = cast(type[Artist], constructor)
+        TemplateLoader.add_constructor(
+            f"!{name}", cast(YamlConstructor, cls.from_yaml)
+        )
+    else:
+        TemplateLoader.add_constructor(f"!{name}", constructor)

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

@@ -0,0 +1,25 @@
+"""Public artist API.
+
+Importing this module applies the matplotlib stylesheet
+defined by ``tesorotools.utils.globals.STYLE_SHEET``.
+"""
+
+import matplotlib.style
+
+from tesorotools.artists.barh_plot import HorizontalBarChart
+from tesorotools.artists.line_plot import Format, Legend, LinePlot
+from tesorotools.artists.stacked import StackedAreaPlot, StackedBarPlot
+from tesorotools.artists.type_curve import TypeCurve
+from tesorotools.utils.globals import STYLE_SHEET
+
+matplotlib.style.use(STYLE_SHEET)
+
+__all__ = [
+    "Format",
+    "HorizontalBarChart",
+    "Legend",
+    "LinePlot",
+    "StackedAreaPlot",
+    "StackedBarPlot",
+    "TypeCurve",
+]

{tesorotools_python-0.0.34 → tesorotools_python-0.0.36}/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.36}/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,
         )