tesorotools-python 0.0.48__tar.gz → 0.0.50__tar.gz

tesorotools_python-0.0.50/.gitignore

@@ -0,0 +1,35 @@
+.venv/
+.build1/
+
+__pycache__
+
+.vscode/
+
+data/
+config/
+debug/
+tablas/
+
+dist/
+
+*.png
+*.feather
+*.csv
+*.docx
+*.docx#
+# ...but the bundled base template must ship in the package/wheel.
+!src/tesorotools/assets/template.docx
+
+test/
+
+# coverage
+.coverage
+
+# ruff
+.ruff_cache/
+
+# uv cache (CI restores it into the repo root)
+.uv-cache/
+
+demo_compacto/
+demo/

{tesorotools_python-0.0.48 → tesorotools_python-0.0.50}/PKG-INFO

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

{tesorotools_python-0.0.48 → tesorotools_python-0.0.50}/pyproject.toml

@@ -48,11 +48,17 @@ source = "vcs"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/tesorotools"]
-artifacts = ["src/tesorotools/assets/fonts/*.otf"]
+artifacts = [
+    "src/tesorotools/assets/fonts/*.otf",
+    "src/tesorotools/assets/template.docx",
+]
 
 [tool.hatch.build.targets.sdist]
 include = ["src/tesorotools"]
-artifacts = ["src/tesorotools/assets/fonts/*.otf"]
+artifacts = [
+    "src/tesorotools/assets/fonts/*.otf",
+    "src/tesorotools/assets/template.docx",
+]
 
 [tool.coverage.run]
 source = ["tesorotools"]

{tesorotools_python-0.0.48 → tesorotools_python-0.0.50}/src/tesorotools/__init__.py

@@ -17,8 +17,17 @@ plural variants).  See ``docs/extending.md`` for the
 recommended idioms.
 """
 
+from importlib.metadata import PackageNotFoundError, version
 from typing import TYPE_CHECKING, Any
 
+try:
+    #: Installed distribution version (set by hatch-vcs from the git tag).
+    #: Falls back to ``"0.0.0"`` when the package is not installed (e.g.
+    #: running straight from a source checkout with no metadata).
+    __version__ = version("tesorotools-python")
+except PackageNotFoundError:  # pragma: no cover - source-only checkout
+    __version__ = "0.0.0"
+
 if TYPE_CHECKING:
     from tesorotools.providers.bde import BdeProvider
     from tesorotools.providers.ecb import EcbProvider
@@ -50,6 +59,7 @@ from tesorotools.artists import (
     Legend,
     LinePlot,
     MatrixChart,
+    ShockChart,
     StackedAreaPlot,
     StackedBarPlot,
     TypeCurve,
@@ -72,6 +82,7 @@ from tesorotools.render import (
     Table,
     Text,
     Title,
+    new_document,
 )
 
 
@@ -84,6 +95,7 @@ def _register_builtins() -> None:
     register_artist("type_curve", TypeCurve)
     register_artist("vector_plot", VectorPlot)
     register_artist("matrix", MatrixChart)
+    register_artist("shock_plot", ShockChart)
     register_artist("waterfall", Waterfall)
 
     register_tag("format", Format)
@@ -102,6 +114,7 @@ _register_builtins()
 
 
 __all__ = [
+    "__version__",
     "Artist",
     "BdeProvider",
     "BuildContext",
@@ -121,6 +134,7 @@ __all__ = [
     "RegistryProtocol",
     "Report",
     "Section",
+    "ShockChart",
     "StackedAreaPlot",
     "StackedBarPlot",
     "Subtitle",
@@ -141,6 +155,7 @@ __all__ = [
     "iter_contexts",
     "iter_providers",
     "iter_tags",
+    "new_document",
     "register_artist",
     "register_artists",
     "register_provider",

{tesorotools_python-0.0.48 → tesorotools_python-0.0.50}/src/tesorotools/artists/__init__.py

@@ -29,6 +29,7 @@ from tesorotools.artists._common import Artist, Format, Legend
 from tesorotools.artists.barh_plot import GroupedBarChart, HorizontalBarChart
 from tesorotools.artists.line_plot import LinePlot
 from tesorotools.artists.matrix import MatrixChart
+from tesorotools.artists.shock_plot import ShockChart
 from tesorotools.artists.stacked import StackedAreaPlot, StackedBarPlot
 from tesorotools.artists.type_curve import TypeCurve
 from tesorotools.artists.vector_plot import VectorPlot
@@ -42,6 +43,7 @@ __all__ = [
     "Legend",
     "LinePlot",
     "MatrixChart",
+    "ShockChart",
     "StackedAreaPlot",
     "StackedBarPlot",
     "TypeCurve",

{tesorotools_python-0.0.48 → tesorotools_python-0.0.50}/src/tesorotools/artists/_common.py

@@ -156,12 +156,20 @@ class Format:
 
     Used by every artist as ``fmt`` and by tick formatters /
     annotations.  ``decimals`` is forwarded to ``round`` and
-    ``units`` is appended to the formatted number.
+    ``units`` is appended to the formatted number.  ``signed``
+    prefixes a ``+`` to positive numbers (negatives already
+    carry ``-``); useful for a variation/change annotation so
+    its direction reads at a glance.  It is opt-in and ignored
+    by axis-tick formatting (a row of ``+`` on the axis is
+    noise) -- set it on the ``annot_fmt`` that labels the bars.
     """
 
-    def __init__(self, units: str = "", decimals: int = 0) -> None:
+    def __init__(
+        self, units: str = "", decimals: int = 0, signed: bool = False
+    ) -> None:
         self.units = units
         self.decimals = decimals
+        self.signed = signed
 
     @classmethod
     def from_yaml(cls, loader: TemplateLoader, node: MappingNode) -> Self:
@@ -381,7 +389,7 @@ def compact_figsize() -> tuple[float, float]:
     return (width_cm * CM_TO_IN, height_cm * CM_TO_IN)
 
 
-def compact_font_pt() -> float | None:
+def compact_font_pt(override: float | None = None) -> float | None:
     """Font size (points) for compact charts, or ``None`` to keep the style.
 
     Because the compact figure is rendered at its true
@@ -389,7 +397,17 @@ def compact_font_pt() -> float | None:
     these points equal the points the reader sees in Word --
     set ``compact.font_pt`` in ``plots.yaml`` to the document
     body-text size so chart text matches running text.
+
+    ``override`` lets a single chart pick its own size, taking
+    precedence over the config: a chart that sits inside a Word
+    table wants the **table** content size (often smaller than
+    body text), and a denser chart -- many long-named bars -- may
+    need a smaller size so the value labels and category names
+    stop colliding.  ``None`` (the default) falls back to
+    ``compact.font_pt``.
     """
+    if override is not None:
+        return float(override)
     raw: Any = COMPACT_CONFIG.get("font_pt")
     return None if raw is None else float(raw)
 
@@ -620,17 +638,132 @@ def legend_above(
     )
 
 
-def declutter_spines(ax: Axes) -> None:
-    """Hide the spines that carry no ticks (top and right).
+# ----------------------------------------------------------------------
+# Shared compact toolkit
+# ----------------------------------------------------------------------
+#
+# The three helpers below pack the policy ``LinePlot`` / ``Waterfall``
+# had inline so *every* image artist can opt into compact uniformly --
+# fixed physical size, body-size ticks, the spine side and the
+# above-the-axes legend -- instead of copy-pasting from this module's
+# internals.  They are re-exported publicly from
+# :mod:`tesorotools.artists.compact`.
+
+
+def compact_figure_kwargs(
+    compact: bool, figsize: tuple[float, float] | None = None
+) -> dict[str, Any]:
+    """``FIG_CONFIG`` with the compact figure size wired in.
+
+    An explicit ``figsize`` always wins; otherwise a compact chart with no
+    ``figsize`` gets :func:`compact_figsize` (the fixed 7.4 cm x 5.5 cm box
+    read from ``plots.yaml``).  Mirrors the ``fig_kw`` block every artist
+    opened by hand.
+    """
+    fig_kw = dict(FIG_CONFIG)
+    if figsize is not None:
+        fig_kw["figsize"] = figsize
+    elif compact:
+        fig_kw["figsize"] = compact_figsize()
+    return fig_kw
+
+
+def compact_barh_figsize(n_bars: int) -> tuple[float, float]:
+    """Compact figure size for a horizontal-bar chart: width fixed, height grows.
+
+    The fixed compact height crushes the y-labels of a many-category barh,
+    so compact bar charts keep the compact **width** but scale **height**
+    with the bar count: ``margin + per_bar * n_bars`` centimetres
+    (``compact.barh_margin_cm`` / ``compact.barh_per_bar_cm``), floored at
+    the compact height so a one- or two-bar chart is not absurdly short.
+    """
+    width_in, height_in = compact_figsize()
+    per_bar_cm: float = float(COMPACT_CONFIG.get("barh_per_bar_cm", 0.55))
+    margin_cm: float = float(COMPACT_CONFIG.get("barh_margin_cm", 1.6))
+    h_cm = margin_cm + per_bar_cm * max(1, n_bars)
+    return (width_in, max(height_in, h_cm * CM_TO_IN))
+
+
+def style_compact_axes(
+    ax: Axes, font_pt: float | None, *, side: str = "right"
+) -> None:
+    """Body-size ticks plus the compact spine policy for *ax*.
+
+    The stylesheet pins ``xtick.labelsize`` / ``ytick.labelsize`` to 12, so
+    setting ``font.size`` alone does **not** resize the ticks -- this calls
+    ``tick_params(labelsize=font_pt)`` explicitly (when ``font_pt`` is set).
+    It then puts the y-ticks on ``side`` (``"right"`` -- the house side, the
+    default -- or ``"left"``, which frees the right edge for end-of-series
+    value labels) and drops the now-tickless top and opposite spines via
+    :func:`declutter_spines`.
+    """
+    if font_pt is not None:
+        ax.tick_params(  # type: ignore[reportUnknownMemberType]
+            axis="both", labelsize=font_pt
+        )
+    if side == "right":
+        ax.yaxis.tick_right()
+    else:
+        ax.yaxis.tick_left()
+    declutter_spines(ax, side=side)
+
+
+def place_legend(
+    fig: Figure,
+    ax: Axes,
+    *,
+    compact: bool,
+    ncol: int | None = None,
+) -> MplLegend | None:
+    """Place the figure legend, compact-aware, from the labelled artists.
+
+    Compact charts get the band **above** the axes spanning the figure
+    width (:func:`legend_above`) with the compact legend metrics; ``ncol``
+    is auto-fitted to the full figure width and hard-capped by
+    :func:`compact_legend_max_ncol` unless the caller passes an explicit
+    ``ncol``.  Non-compact charts get the house ``outside lower center``
+    band.  Returns ``None`` (drawing nothing) when there are no labels.
+    """
+    handles, labels = ax.get_legend_handles_labels()
+    if not labels:
+        return None
+    fig_w_px: float = fig.get_size_inches()[0] * fig.dpi
+    if compact:
+        legend_kw = compact_legend_kwargs()
+        if ncol is None:
+            ncol = auto_ncol(
+                ax, labels, available_width_px=fig_w_px, **legend_kw
+            )
+            max_ncol = compact_legend_max_ncol()
+            if max_ncol is not None:
+                ncol = min(ncol, max_ncol)
+        return legend_above(ax, handles, labels, ncol=ncol, **legend_kw)
+    if ncol is None:
+        ncol = auto_ncol(ax, labels, available_width_px=fig_w_px)
+    return fig.legend(  # type: ignore[reportUnknownMemberType]
+        handles,
+        labels,
+        loc="outside lower center",
+        ncol=ncol,
+    )
+
+
+def declutter_spines(ax: Axes, side: str = "left") -> None:
+    """Hide the spines that carry no ticks (top, plus the untickled side).
+
+    Compact charts keep x-ticks on the bottom and the y-ticks on a single
+    side, leaving the top spine and the *opposite* vertical spine as pure
+    clutter -- drop them to free space and reduce visual noise.
 
-    Compact line charts move the y-ticks to the **left** (so
-    the right edge is free for the end-of-series value labels)
-    and keep x-ticks on the bottom, leaving the top and right
-    spines as pure clutter -- drop them to free space and
-    reduce visual noise.
+    ``side`` is the side the y-ticks live on: ``"left"`` (the historic
+    default, used by the annotating line chart and the bar/waterfall
+    charts) drops top+right; ``"right"`` (the house side every non-compact
+    chart keeps) drops top+left.  The side became a choice with the compact
+    y-axis-side knob, so the dropped spine has to follow it -- otherwise a
+    right-ticked compact chart would lose the spine its ticks sit on.
     """
     ax.spines["top"].set_visible(False)
-    ax.spines["right"].set_visible(False)
+    ax.spines["right" if side == "left" else "left"].set_visible(False)
 
 
 # ----------------------------------------------------------------------