tesorotools-python 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

tesorotools/__init__.py

@@ -72,6 +72,7 @@ from tesorotools.artists import (
     TypeCurve,
     VectorPlot,
     Waterfall,
+    share_y_axes,
 )
 from tesorotools.orchestration import CompositeRegistry, iter_contexts
 from tesorotools.providers.base import (
@@ -177,6 +178,7 @@ __all__ = [
     "register_providers",
     "register_tag",
     "register_tags",
+    "share_y_axes",
 ]
 
 

tesorotools/artists/__init__.py

@@ -12,9 +12,16 @@ Each class follows the same shape:
   ``data_path`` (``.feather`` on disk), never both.
 * ``from_yaml(loader, node)`` -- builds the same instance
   from a ``!{name}`` YAML tag.
-* ``plot()`` -- renders the chart and writes the PNG; some
-  classes also expose ``build()`` / ``save()`` for
-  fine-grained control.
+* ``build()`` -- renders the chart in memory and returns
+  ``(Figure, Axes)``; ``save(fig, path=..., dpi=...)``
+  writes it; ``plot()`` does both and closes the figure.
+  Every artist exposes the three (see :class:`Artist`).
+* ``to_plotly()`` -- the same chart as an interactive
+  Plotly figure (all but ``IntradayPlot``);
+  :func:`plotly_unsupported` lists the keys it drops.
+
+:func:`share_y_axes` gives the charts that declare the same
+``y_group`` one common y scale.
 
 Shared layout, annotation and styling helpers (plus the
 ``Format`` and ``Legend`` config holders) live in
@@ -25,13 +32,20 @@ live under :mod:`tesorotools.render`; this package is
 strictly image output.
 """
 
-from tesorotools.artists._common import Artist, Format, Legend
+from tesorotools.artists._common import (
+    Artist,
+    FigureLifecycle,
+    Format,
+    Legend,
+    plotly_unsupported,
+)
 from tesorotools.artists.bar_line import BarLinePlot
 from tesorotools.artists.barh_plot import GroupedBarChart, HorizontalBarChart
 from tesorotools.artists.box_plot import BoxPlot
 from tesorotools.artists.intraday_plot import IntradayPlot
 from tesorotools.artists.line_plot import LinePlot
 from tesorotools.artists.matrix import MatrixChart
+from tesorotools.artists.sharing import share_y_axes
 from tesorotools.artists.shock_plot import ShockChart
 from tesorotools.artists.stacked import StackedAreaPlot, StackedBarPlot
 from tesorotools.artists.type_curve import TypeCurve
@@ -42,6 +56,7 @@ __all__ = [
     "Artist",
     "BarLinePlot",
     "BoxPlot",
+    "FigureLifecycle",
     "Format",
     "GroupedBarChart",
     "HorizontalBarChart",
@@ -55,4 +70,6 @@ __all__ = [
     "TypeCurve",
     "VectorPlot",
     "Waterfall",
+    "plotly_unsupported",
+    "share_y_axes",
 ]

tesorotools/artists/_common.py

@@ -23,13 +23,18 @@ overrides only need to update ``plots.yaml``.
 
 from __future__ import annotations
 
+from collections.abc import Sequence
 from pathlib import Path
 from typing import Any, Literal, Protocol, Self, cast, runtime_checkable
 
 import matplotlib.pyplot as plt
 import pandas as pd
 from matplotlib.axes import Axes
-from matplotlib.dates import AutoDateLocator, ConciseDateFormatter
+from matplotlib.dates import (
+    AutoDateLocator,
+    ConciseDateFormatter,
+    YearLocator,
+)
 from matplotlib.dates import (
     date2num,  # type: ignore[reportUnknownVariableType]
 )
@@ -126,6 +131,70 @@ def dynamic_dpi(fig: Figure) -> int:
     return int(round(min(max_dpi, max(min_dpi, target_px / long_in))))
 
 
+def plotly_unsupported(artist: object) -> frozenset[str]:
+    """Configuration keys *artist* accepts but ``to_plotly()`` drops.
+
+    *artist* is an artist class or instance.  The keys change the PNG
+    but not the interactive figure; nested ones are dotted
+    (``"legend.ncol"``, ``"fmt.signed"``).  A UI built on top can tell
+    the user why moving such a control leaves the figure as it is.
+    Needs no ``plotly``: it reads the class attribute
+    ``PLOTLY_UNSUPPORTED``, which the test suite checks against real
+    renders.
+    """
+    cls = artist if isinstance(artist, type) else type(artist)
+    if not hasattr(cls, "to_plotly"):
+        raise TypeError(f"{cls.__name__} has no to_plotly()")
+    declared: frozenset[str] | None = getattr(cls, "PLOTLY_UNSUPPORTED", None)
+    if declared is None:
+        raise TypeError(f"{cls.__name__} does not declare PLOTLY_UNSUPPORTED")
+    return frozenset(declared)
+
+
+class FigureLifecycle:
+    """``save()`` and ``plot()`` on top of a subclass's ``build()``.
+
+    Gives an artist the same three-step life cycle as the rest:
+    ``build()`` returns the figure in memory, ``save()`` writes it
+    and ``plot()`` does both and closes the figure.  A subclass only
+    implements ``build()``.
+    """
+
+    out_path: Path
+
+    def build(self) -> tuple[Figure, Axes]:
+        raise NotImplementedError
+
+    def save(
+        self,
+        fig: Figure,
+        *,
+        path: Path | None = None,
+        dpi: int | None = None,
+    ) -> Path:
+        """Persist *fig* as a PNG and return the path written.
+
+        Defaults to ``self.out_path``; pass ``path`` to redirect.
+        ``dpi`` overrides the save resolution; when omitted it is
+        derived from the figure size via :func:`dynamic_dpi`.
+        """
+        target: Path = path if path is not None else self.out_path
+        save_dpi: int = dpi if dpi is not None else dynamic_dpi(fig)
+        fig.savefig(  # type: ignore[reportUnknownMemberType]
+            target, dpi=save_dpi
+        )
+        return target
+
+    def plot(self) -> Axes:
+        """Build the chart, persist it to ``self.out_path`` and close it."""
+        fig, ax = self.build()
+        try:
+            self.save(fig)
+        finally:
+            plt.close(fig)
+        return ax
+
+
 # ----------------------------------------------------------------------
 # Structural contract for image artists
 # ----------------------------------------------------------------------
@@ -137,13 +206,21 @@ class Artist(Protocol):
 
     The built-in artists and any third-party artist
     registered via :func:`tesorotools.register_artist`
-    expose the same three-piece surface:
+    expose the same surface:
 
     * ``out_path: Path`` -- the ``.png`` destination.
     * ``from_yaml(loader, node) -> Self`` -- the YAML
       constructor bound to the ``!{name}`` tag.
-    * ``plot() -> Axes`` -- render the chart, persist it
-      to ``out_path``, and return the axes for inspection.
+    * ``build() -> (Figure, Axes)`` -- render the chart in
+      memory, without touching the disk.
+    * ``save(fig, *, path=None, dpi=None) -> Path`` -- write
+      a built figure (to ``out_path`` unless ``path`` says
+      otherwise).
+    * ``plot() -> Axes`` -- ``build()`` + ``save()``, close
+      the figure and return the axes for inspection.
+
+    :class:`FigureLifecycle` provides ``save()`` and ``plot()``
+    for an artist that only implements ``build()``.
 
     The Protocol is ``runtime_checkable`` so consumers can
     use ``isinstance(obj, Artist)`` to validate a candidate
@@ -156,6 +233,16 @@ class Artist(Protocol):
     @classmethod
     def from_yaml(cls, loader: Any, node: MappingNode) -> Self: ...
 
+    def build(self) -> tuple[Figure, Axes]: ...
+
+    def save(
+        self,
+        fig: Figure,
+        *,
+        path: Path | None = None,
+        dpi: int | None = None,
+    ) -> Path: ...
+
     def plot(self) -> Axes: ...
 
 
@@ -580,6 +667,12 @@ def date_span_ticks(
     10 % of the span is dropped so the two labels do not collide.  Without
     it the plain in-span candidates are returned (falling back to the two
     endpoints when the locator offers nothing inside).
+
+    When the locator steps by several years, the pinned grid is anchored to
+    the **start year** instead of to multiples of the step: a 2-year step
+    over 2023-2027 gives 2023, 2025, 2027 rather than the pinned 2023 plus
+    the calendar 2024, 2026, whose uneven gaps (and missing odd years) read
+    as if the axis skipped a year.
     """
     lo: float = float(cast(Any, date2num(data_min)))
     hi: float = float(cast(Any, date2num(data_max)))
@@ -589,6 +682,18 @@ def date_span_ticks(
     )
     if not pin_start:
         return [t for t in candidates if lo <= t <= hi] or [lo, hi]
+    chosen: Any = locator.get_locator(  # type: ignore[reportUnknownMemberType]
+        data_min, data_max
+    )
+    if isinstance(chosen, YearLocator):
+        step = int(cast(Any, chosen.base).step)
+        if step > 1:
+            first_year: int = num2date(lo).year
+            last_year: int = num2date(hi).year
+            candidates = [
+                float(cast(Any, date2num(pd.Timestamp(year=y, month=1, day=1))))
+                for y in range(first_year, last_year + 1, step)
+            ]
     min_gap: float = (hi - lo) * 0.10
     interior: list[float] = [
         t for t in candidates if lo < t <= hi and t - lo >= min_gap
@@ -1195,6 +1300,26 @@ def style_spines(
     )
 
 
+def check_y_limits(
+    limits: Sequence[float] | None,
+) -> tuple[float, float] | None:
+    """Validate a ``y_limits`` pair and return it as ``(bottom, top)``.
+
+    YAML hands the pair over as a list, so any two-item sequence is
+    accepted; ``None`` (no fixed range) passes through.  Raises
+    ``ValueError`` unless there are exactly two numbers with
+    ``bottom < top``.
+    """
+    if limits is None:
+        return None
+    if len(limits) != 2:
+        raise ValueError(f"y_limits must be (bottom, top): {limits!r}")
+    bottom, top = float(limits[0]), float(limits[1])
+    if not bottom < top:
+        raise ValueError(f"y_limits bottom must be below top: {limits!r}")
+    return bottom, top
+
+
 def style_baseline(
     ax: Axes,
     reference: float = 0,
@@ -1235,6 +1360,7 @@ def annotate_last_values(
     fontsize: float | None = None,
     right_pad_px: float = 10.0,
     headroom_pad_pt: float = 0.0,
+    grow_top: bool = True,
 ) -> None:
     """Label the last non-NaN value of each column on the right.
 
@@ -1261,7 +1387,8 @@ def annotate_last_values(
     y-limit, that limit grows enough to keep this many points
     free and the labels are re-packed at the new scale, so a
     tall stack never spills into a legend above the axes (nor
-    is clipped at the top).
+    is clipped at the top).  ``grow_top=False`` keeps the top
+    y-limit as it is (a fixed or shared y range must not move).
     """
     fig = ax.get_figure()
     if fig is None:
@@ -1333,7 +1460,7 @@ def annotate_last_values(
     pad_px = headroom_pad_pt * fig.dpi / 72.0
     top_axes_px: float = trans.transform((0, ymax))[1]  # type: ignore[reportUnknownArgumentType]
     needed_px = placements[-1] + text_height / 2 + pad_px
-    if needed_px > top_axes_px:
+    if grow_top and needed_px > top_axes_px:
         new_top: float = trans.inverted().transform(  # type: ignore[reportUnknownArgumentType]
             (0, needed_px)
         )[1]

tesorotools/artists/bar_line.py

@@ -28,7 +28,7 @@ from __future__ import annotations
 
 import locale
 from pathlib import Path
-from typing import Any, Self
+from typing import Any, ClassVar, Self
 
 import matplotlib.pyplot as plt
 import numpy as np
@@ -89,6 +89,23 @@ class BarLinePlot:
       (``None`` labels every slot).
     """
 
+    #: Keys that change the PNG but never the ``to_plotly()`` figure
+    #: (see :func:`plotly_unsupported`); checked against real renders
+    #: by ``tests/test_plotly_support.py``.
+    PLOTLY_UNSUPPORTED: ClassVar[frozenset[str]] = frozenset(
+        {
+            "bar_width",
+            "compact",
+            "figsize",
+            "fmt.decimals",
+            "font_pt",
+            "legend.ncol",
+            "max_xticks",
+            "plot_size",
+            "x_rotation",
+        }
+    )
+
     def __init__(
         self,
         out_path: Path,

tesorotools/artists/barh_plot.py

@@ -18,7 +18,7 @@ from __future__ import annotations
 
 from enum import Enum
 from pathlib import Path
-from typing import Any, Self
+from typing import Any, ClassVar, Self
 
 import matplotlib.patheffects as pe
 import matplotlib.pyplot as plt
@@ -32,6 +32,7 @@ from matplotlib.ticker import FuncFormatter
 from yaml.nodes import MappingNode
 
 from tesorotools.artists._common import (
+    FigureLifecycle,
     AX_CONFIG,
     Format,
     Legend,
@@ -39,7 +40,6 @@ from tesorotools.artists._common import (
     compact_barh_figsize,
     compact_figure_kwargs,
     compact_font_pt,
-    dynamic_dpi,
     legend_layout,
     place_legend,
     resolve_data,
@@ -447,7 +447,7 @@ def _place_in_or_out_labels(
     return outside
 
 
-class HorizontalBarChart:
+class HorizontalBarChart(FigureLifecycle):
     """Horizontal bar chart artist.
 
     Parameters
@@ -507,6 +507,19 @@ class HorizontalBarChart:
         outside; pragmatic but mixes the two looks).
     """
 
+    #: Keys that change the PNG but never the ``to_plotly()`` figure
+    #: (see :func:`plotly_unsupported`); checked against real renders
+    #: by ``tests/test_plotly_support.py``.
+    PLOTLY_UNSUPPORTED: ClassVar[frozenset[str]] = frozenset(
+        {
+            "color_value_labels",
+            "compact",
+            "figsize",
+            "font_pt",
+            "value_label_position",
+        }
+    )
+
     def __init__(
         self,
         out_path: Path,
@@ -641,7 +654,11 @@ class HorizontalBarChart:
             frame = frame.sort_values(by=_Col.VALUE.value)
         return frame
 
-    def plot(self) -> Axes:
+    def build(self) -> tuple[Figure, Axes]:
+        """Render the chart in memory; :meth:`save` writes it.
+
+        :meth:`plot` (from :class:`FigureLifecycle`) does both.
+        """
         """Render the chart and persist it to ``self.out_path``."""
         frame = self._build_frame()
 
@@ -689,14 +706,10 @@ class HorizontalBarChart:
                 axis="both", labelsize=font_pt
             )
 
-        fig.savefig(  # type: ignore[reportUnknownMemberType]
-            self.out_path, dpi=dynamic_dpi(fig)
-        )
-        plt.close(fig)
-        return ax
+        return fig, ax
 
 
-class GroupedBarChart:
+class GroupedBarChart(FigureLifecycle):
     """Grouped (clustered) horizontal bar chart artist.
 
     Compares two or more series side-by-side within each
@@ -764,6 +777,23 @@ class GroupedBarChart:
         see :class:`HorizontalBarChart`.
     """
 
+    #: Keys that change the PNG but never the ``to_plotly()`` figure
+    #: (see :func:`plotly_unsupported`); checked against real renders
+    #: by ``tests/test_plotly_support.py``.
+    PLOTLY_UNSUPPORTED: ClassVar[frozenset[str]] = frozenset(
+        {
+            "annotate",
+            "color_value_labels",
+            "compact",
+            "figsize",
+            "font_pt",
+            "group_width",
+            "legend.ncol",
+            "plot_size",
+            "value_label_position",
+        }
+    )
+
     def __init__(
         self,
         out_path: Path,
@@ -867,7 +897,11 @@ class GroupedBarChart:
 
         return grouped_bar_to_figure(self)
 
-    def plot(self) -> Axes:
+    def build(self) -> tuple[Figure, Axes]:
+        """Render the chart in memory; :meth:`save` writes it.
+
+        :meth:`plot` (from :class:`FigureLifecycle`) does both.
+        """
         """Render the chart and persist it to ``self.out_path``."""
         cat_ids = list(self.categories.keys())
         ser_ids = list(self.series.keys())
@@ -941,8 +975,4 @@ class GroupedBarChart:
         if self.plot_size is not None and not self.compact:
             adjust_figure_for_plot_size(fig, ax, self.plot_size)
 
-        fig.savefig(  # type: ignore[reportUnknownMemberType]
-            self.out_path, dpi=dynamic_dpi(fig)
-        )
-        plt.close(fig)
-        return ax
+        return fig, ax

tesorotools/artists/box_plot.py

@@ -32,7 +32,7 @@ The last-value marker is a circle by default and fully configurable
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Any, Self
+from typing import Any, ClassVar, Self
 
 import matplotlib.pyplot as plt
 import numpy as np
@@ -129,6 +129,21 @@ class BoxPlot:
     * ``legend_labels`` -- override the four proxy labels.
     """
 
+    #: Keys that change the PNG but never the ``to_plotly()`` figure
+    #: (see :func:`plotly_unsupported`); checked against real renders
+    #: by ``tests/test_plotly_support.py``.
+    PLOTLY_UNSUPPORTED: ClassVar[frozenset[str]] = frozenset(
+        {
+            "compact",
+            "figsize",
+            "fmt.decimals",
+            "font_pt",
+            "legend.ncol",
+            "plot_size",
+            "x_rotation",
+        }
+    )
+
     def __init__(
         self,
         out_path: Path,

tesorotools/artists/line_plot.py

@@ -11,8 +11,9 @@ from __future__ import annotations
 
 import datetime
 import locale
+from collections.abc import Sequence
 from pathlib import Path
-from typing import Any, Self
+from typing import Any, ClassVar, Self
 
 import matplotlib.pyplot as plt
 import pandas as pd
@@ -30,6 +31,7 @@ from tesorotools.artists._common import (
     adjust_figure_for_plot_size,
     annotate_last_values,
     apply_date_axis,
+    check_y_limits,
     compact_date_axis,
     compact_figure_kwargs,
     compact_font_pt,
@@ -160,12 +162,43 @@ class LinePlot:
       **height** (keeping the width) so the plot area is not
       squashed by a large legend or rotated date labels. Skipped
       when ``plot_size`` is set (that already fixes the axes size).
+    * ``y_limits`` -- fix the y-axis to ``(bottom, top)`` on both
+      backends. The range is strict: the baseline, the reference
+      lines and the end-of-series labels no longer widen it.
+    * ``y_group`` -- name of a group of charts that must share the
+      same y scale (e.g. US and European equities, both base 100,
+      in two separate charts). It does nothing on its own:
+      :func:`tesorotools.artists.share_y_axes` measures every chart
+      of each group and sets the union of their ranges as their
+      ``y_limits``. Mutually exclusive with ``y_limits``.
 
     Render lifecycle: ``build()`` returns ``(Figure, Axes)``
     in memory; ``save(fig)`` persists to ``out_path``;
     ``plot()`` is the thin convenience that does both.
     """
 
+    #: Keys that change the PNG but never the ``to_plotly()`` figure
+    #: (see :func:`plotly_unsupported`); checked against real renders
+    #: by ``tests/test_plotly_support.py``.
+    PLOTLY_UNSUPPORTED: ClassVar[frozenset[str]] = frozenset(
+        {
+            "adapt_height",
+            "axis_decimals",
+            "compact",
+            "date_density",
+            "date_rotation",
+            "date_show_start",
+            "figsize",
+            "font_pt",
+            "legend.ncol",
+            "means_window",
+            "plot_size",
+            "ref_lines",
+            "show_means",
+            "vlines",
+        }
+    )
+
     def __init__(
         self,
         out_path: Path,
@@ -201,9 +234,16 @@ class LinePlot:
         ref_lines: list[dict[str, Any]] | None = None,
         show_means: bool = False,
         means_window: tuple[Any, Any] | None = None,
+        y_limits: Sequence[float] | None = None,
+        y_group: str | None = None,
     ) -> None:
         if out_path.suffix != ".png":
             raise ValueError(f"out_path must be .png: {out_path}")
+        if y_limits is not None and y_group is not None:
+            raise ValueError(
+                "y_limits and y_group are mutually exclusive: a group "
+                "computes its shared y_limits (see share_y_axes)"
+            )
         if base_100 and base_0:
             raise ValueError(
                 "base_100 and base_0 are mutually exclusive: a series is "
@@ -247,6 +287,8 @@ class LinePlot:
         self.ref_lines = ref_lines or []
         self.show_means = show_means
         self.means_window = means_window
+        self.y_limits = check_y_limits(y_limits)
+        self.y_group = y_group
 
     @property
     def _pin_start_date(self) -> bool:
@@ -302,7 +344,8 @@ class LinePlot:
         ``axis_decimals``, ``axis_units``, ``annotate_units``,
         ``date_density``, ``date_rotation``, ``date_show_start``,
         ``adapt_height``,
-        ``ref_lines``, ``show_means``, ``means_window``.
+        ``ref_lines``, ``show_means``, ``means_window``,
+        ``y_limits``, ``y_group``.
 
         Example
         -------
@@ -440,6 +483,11 @@ class LinePlot:
             # data point. annotate_last_values reopens room on the right.
             ax.margins(x=0)
 
+        # a fixed (or group-shared) y range goes in BEFORE the annotations:
+        # they pack their labels at the final scale.
+        if self.y_limits is not None:
+            ax.set_ylim(*self.y_limits)
+
         if self.vlines:
             draw_vlines(ax, self.vlines)
 
@@ -472,6 +520,7 @@ class LinePlot:
                 headroom_pad_pt=(
                     compact_headroom_pad_pt() if self.compact else 0.0
                 ),
+                grow_top=self.y_limits is None,
             )
 
         style_spines(
@@ -514,6 +563,10 @@ class LinePlot:
             )
             lo, hi = ax.get_ylim()
             ax.set_ylim(min(ref_line["y"], lo), max(ref_line["y"], hi))
+        if self.y_limits is not None:
+            # the baseline and the reference lines widen the range to show
+            # themselves; a fixed range wins over them.
+            ax.set_ylim(*self.y_limits)
 
         # per-series historical mean as a dotted same-colour line (the old
         # `medias=True`): the mean is taken over means_window (or the whole

tesorotools/artists/matrix.py

@@ -27,7 +27,7 @@ Styling constants come from ``PLOT_CONFIG['matrix']``.
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Any, Self
+from typing import Any, ClassVar, Self
 
 import matplotlib as mpl
 import matplotlib.pyplot as plt
@@ -40,9 +40,9 @@ from matplotlib.patches import Rectangle
 from yaml.nodes import MappingNode
 
 from tesorotools.artists._common import (
+    FigureLifecycle,
     FIG_CONFIG,
     Format,
-    dynamic_dpi,
     resolve_data,
 )
 from tesorotools.utils.matplotlib import PLOT_CONFIG, format_annotation
@@ -66,7 +66,7 @@ def _text_color(rgba: tuple[float, float, float, float]) -> str:
     return MATRIX_CONFIG["dark_text"]
 
 
-class MatrixChart:
+class MatrixChart(FigureLifecycle):
     """Annotated heatmap-table artist (any ``n_rows x n_cols``).
 
     Parameters
@@ -102,6 +102,16 @@ class MatrixChart:
         cells read as tiles.
     """
 
+    #: Keys that change the PNG but never the ``to_plotly()`` figure
+    #: (see :func:`plotly_unsupported`); checked against real renders
+    #: by ``tests/test_plotly_support.py``.
+    PLOTLY_UNSUPPORTED: ClassVar[frozenset[str]] = frozenset(
+        {
+            "cmap",
+            "figsize",
+        }
+    )
+
     def __init__(
         self,
         out_path: Path,
@@ -199,7 +209,11 @@ class MatrixChart:
 
         return matrix_to_figure(self)
 
-    def plot(self) -> Axes:
+    def build(self) -> tuple[Figure, Axes]:
+        """Render the chart in memory; :meth:`save` writes it.
+
+        :meth:`plot` (from :class:`FigureLifecycle`) does both.
+        """
         """Render the chart and persist it to ``self.out_path``."""
         row_ids = list(self.rows)
         col_ids = list(self.cols)
@@ -260,11 +274,7 @@ class MatrixChart:
                     )
 
         self._style_axes(ax, row_ids, col_ids)
-        fig.savefig(  # type: ignore[reportUnknownMemberType]
-            self.out_path, dpi=dynamic_dpi(fig)
-        )
-        plt.close(fig)
-        return ax
+        return fig, ax
 
     def _annotate_cell(
         self,

tesorotools/artists/plotly_backend.py

@@ -35,9 +35,11 @@ backends, per the dual-backend research):
   ``adapt_height``) do nothing here.
 * Beyond those, a few per-artist knobs have no stable Plotly equivalent
   and a few others are simply not translated yet.  Both kinds are
-  accepted in silence, so which is which is written down parameter by
-  parameter in ``docs/plotly-backend.md`` (audited for ``LinePlot``).
-  Keep that table in sync when adding or translating a parameter.
+  accepted in silence; each artist lists them in ``PLOTLY_UNSUPPORTED``
+  (read with :func:`tesorotools.artists.plotly_unsupported`), which
+  ``tests/test_plotly_support.py`` checks against real renders.  When
+  translating a key, drop it from there and from the table in
+  ``docs/plotly-backend.md``.
 """
 
 from __future__ import annotations
@@ -300,6 +302,9 @@ def line_plot_to_figure(chart: LinePlot) -> go.Figure:
     # toggles (mirrors the matplotlib artist).
     if chart.fmt.units and chart.axis_units:
         fig.update_yaxes(ticksuffix=chart.fmt.units)
+    # fixed or group-shared y range (see share_y_axes)
+    if chart.y_limits is not None:
+        fig.update_yaxes(range=list(chart.y_limits))
     _legend_side(fig, chart.legend)
     return fig
 

tesorotools/artists/sharing.py

@@ -0,0 +1,59 @@
+"""One y scale shared by several separate charts.
+
+Two charts that are read side by side (US and European equities, both
+base 100) mislead when each picks its own y range: the same move looks
+bigger in the flatter one.  Charts that declare the same ``y_group``
+are measured together here and all get the union of their ranges as a
+fixed ``y_limits``, which both backends honour (``build()`` for the PNG,
+``to_plotly()`` for the interactive figure).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+import matplotlib.pyplot as plt
+
+__all__ = ["share_y_axes"]
+
+
+def share_y_axes(charts: Iterable[Any]) -> dict[str, tuple[float, float]]:
+    """Give every chart of each ``y_group`` the same ``y_limits``.
+
+    *charts* is any iterable of artists, typically the values of the
+    mapping loaded from a charts YAML; the ones without a ``y_group``
+    (or with ``None``) are left untouched.  Each grouped chart is built
+    once with its own natural range (the one it would draw alone,
+    including the room its end-of-series labels open), and the group
+    gets the lowest bottom and the highest top among its members.  Call
+    it before ``plot()`` / ``to_plotly()``; calling it again measures
+    afresh, so it is safe after the data change.
+
+    Returns the shared ``(bottom, top)`` per group name.
+    """
+    groups: dict[str, list[Any]] = {}
+    for chart in charts:
+        group: Any = getattr(chart, "y_group", None)
+        if group is not None:
+            groups.setdefault(str(group), []).append(chart)
+
+    shared: dict[str, tuple[float, float]] = {}
+    for name, members in groups.items():
+        bottoms: list[float] = []
+        tops: list[float] = []
+        for chart in members:
+            # measure the chart's own range, not one shared earlier
+            chart.y_limits = None
+            fig, ax = chart.build()
+            try:
+                bottom, top = ax.get_ylim()
+            finally:
+                plt.close(fig)
+            bottoms.append(float(bottom))
+            tops.append(float(top))
+        limits = (min(bottoms), max(tops))
+        for chart in members:
+            chart.y_limits = limits
+        shared[name] = limits
+    return shared

tesorotools/artists/shock_plot.py

@@ -30,7 +30,7 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Self, cast
+from typing import Any, ClassVar, Self, cast
 
 import matplotlib.pyplot as plt
 import pandas as pd
@@ -124,6 +124,18 @@ class ShockChart:
       value instead of each window's own anchor; must be a shock label.
     """
 
+    #: Keys that change the PNG but never the ``to_plotly()`` figure
+    #: (see :func:`plotly_unsupported`); checked against real renders
+    #: by ``tests/test_plotly_support.py``.
+    PLOTLY_UNSUPPORTED: ClassVar[frozenset[str]] = frozenset(
+        {
+            "compact",
+            "figsize",
+            "fmt.decimals",
+            "legend.ncol",
+        }
+    )
+
     def __init__(
         self,
         out_path: Path,

tesorotools/artists/stacked.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Any, Self
+from typing import Any, ClassVar, Self
 
 import matplotlib.pyplot as plt
 import numpy as np
@@ -11,6 +11,7 @@ from matplotlib.figure import Figure
 from yaml.nodes import MappingNode
 
 from tesorotools.artists._common import (
+    FigureLifecycle,
     AX_CONFIG,
     Format,
     Legend,
@@ -22,7 +23,6 @@ from tesorotools.artists._common import (
     compact_font_pt,
     date_maxticks,
     date_show_start_default,
-    dynamic_dpi,
     legend_layout,
     place_legend,
     style_baseline,
@@ -32,7 +32,7 @@ from tesorotools.artists._common import (
 from tesorotools.utils.template import TemplateLoader
 
 
-class StackedAreaPlot:
+class StackedAreaPlot(FigureLifecycle):
     """Stacked area chart with the tesorotools visual style.
 
     Parameters match ``LinePlot`` where applicable so chart
@@ -47,6 +47,21 @@ class StackedAreaPlot:
     the concise style.
     """
 
+    #: Keys that change the PNG but never the ``to_plotly()`` figure
+    #: (see :func:`plotly_unsupported`); checked against real renders
+    #: by ``tests/test_plotly_support.py``.
+    PLOTLY_UNSUPPORTED: ClassVar[frozenset[str]] = frozenset(
+        {
+            "compact",
+            "date_show_start",
+            "figsize",
+            "fmt.decimals",
+            "font_pt",
+            "legend.ncol",
+            "plot_size",
+        }
+    )
+
     def __init__(
         self,
         out_path: Path,
@@ -159,7 +174,11 @@ class StackedAreaPlot:
 
         return stacked_area_to_figure(self)
 
-    def plot(self) -> Axes:
+    def build(self) -> tuple[Figure, Axes]:
+        """Render the chart in memory; :meth:`save` writes it.
+
+        :meth:`plot` (from :class:`FigureLifecycle`) does both.
+        """
         plot_data = self._prepare_data()
 
         font_pt = compact_font_pt(self.font_pt) if self.compact else None
@@ -223,14 +242,10 @@ class StackedAreaPlot:
         if self.plot_size is not None and not self.compact:
             adjust_figure_for_plot_size(fig, ax, self.plot_size)
 
-        fig.savefig(  # type: ignore[reportUnknownMemberType]
-            self.out_path, dpi=dynamic_dpi(fig)
-        )
-        plt.close(fig)
-        return ax
+        return fig, ax
 
 
-class StackedBarPlot:
+class StackedBarPlot(FigureLifecycle):
     """Stacked bar chart with the tesorotools visual style.
 
     Positive and negative values are stacked separately so
@@ -240,6 +255,22 @@ class StackedBarPlot:
     reimplementing the full render pipeline.
     """
 
+    #: Keys that change the PNG but never the ``to_plotly()`` figure
+    #: (see :func:`plotly_unsupported`); checked against real renders
+    #: by ``tests/test_plotly_support.py``.
+    PLOTLY_UNSUPPORTED: ClassVar[frozenset[str]] = frozenset(
+        {
+            "bar_width",
+            "compact",
+            "figsize",
+            "fmt.decimals",
+            "font_pt",
+            "legend.ncol",
+            "plot_size",
+            "x_rotation",
+        }
+    )
+
     def __init__(
         self,
         out_path: Path,
@@ -391,7 +422,11 @@ class StackedBarPlot:
 
         return stacked_bar_to_figure(self)
 
-    def plot(self) -> Axes:
+    def build(self) -> tuple[Figure, Axes]:
+        """Render the chart in memory; :meth:`save` writes it.
+
+        :meth:`plot` (from :class:`FigureLifecycle`) does both.
+        """
         plot_data = self._prepare_data()
 
         font_pt = compact_font_pt(self.font_pt) if self.compact else None
@@ -478,8 +513,4 @@ class StackedBarPlot:
         if self.plot_size is not None and not self.compact:
             adjust_figure_for_plot_size(fig, ax, self.plot_size)
 
-        fig.savefig(  # type: ignore[reportUnknownMemberType]
-            self.out_path, dpi=dynamic_dpi(fig)
-        )
-        plt.close(fig)
-        return ax
+        return fig, ax

tesorotools/artists/type_curve.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Any, Self
+from typing import Any, ClassVar, Self
 
 import matplotlib.pyplot as plt
 import pandas as pd
@@ -11,13 +11,13 @@ from pandas import Timestamp
 from yaml.nodes import MappingNode
 
 from tesorotools.artists._common import (
+    FigureLifecycle,
     AX_CONFIG,
     Format,
     Legend,
     resolve_data,
     compact_figure_kwargs,
     compact_font_pt,
-    dynamic_dpi,
     legend_band,
     legend_layout,
     place_legend,
@@ -99,7 +99,7 @@ def _format_data(data: pd.DataFrame) -> dict[str, Any]:
     }
 
 
-class TypeCurve:
+class TypeCurve(FigureLifecycle):
     """Type-curve chart with the tesorotools visual style.
 
     Plots two ranges (last year and current year) as filled
@@ -111,6 +111,18 @@ class TypeCurve:
     width, marker) come from ``PLOT_CONFIG['type_curve']``.
     """
 
+    #: Keys that change the PNG but never the ``to_plotly()`` figure
+    #: (see :func:`plotly_unsupported`); checked against real renders
+    #: by ``tests/test_plotly_support.py``.
+    PLOTLY_UNSUPPORTED: ClassVar[frozenset[str]] = frozenset(
+        {
+            "compact",
+            "figsize",
+            "font_pt",
+            "legend.ncol",
+        }
+    )
+
     def __init__(
         self,
         out_path: Path,
@@ -215,7 +227,11 @@ class TypeCurve:
 
         return type_curve_to_figure(self)
 
-    def plot(self) -> Axes:
+    def build(self) -> tuple[Figure, Axes]:
+        """Render the chart in memory; :meth:`save` writes it.
+
+        :meth:`plot` (from :class:`FigureLifecycle`) does both.
+        """
         plot_data = self.data.loc[:, list(self.series.keys())]
         plot_data = plot_data.rename(columns=self.series)
         plot_data = plot_data * self.scale
@@ -327,8 +343,4 @@ class TypeCurve:
                     compact=False,
                 ),
             )
-        fig.savefig(  # type: ignore[reportUnknownMemberType]
-            self.out_path, dpi=dynamic_dpi(fig)
-        )
-        plt.close(fig)
-        return ax
+        return fig, ax

tesorotools/artists/vector_plot.py

@@ -26,7 +26,7 @@ constants come from ``PLOT_CONFIG['vector']``.
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Any, Self
+from typing import Any, ClassVar, Self
 
 import matplotlib.pyplot as plt
 import pandas as pd
@@ -36,10 +36,10 @@ from matplotlib.ticker import FuncFormatter
 from yaml.nodes import MappingNode
 
 from tesorotools.artists._common import (
+    FigureLifecycle,
     AX_CONFIG,
     FIG_CONFIG,
     Format,
-    dynamic_dpi,
     resolve_data,
 )
 from tesorotools.utils.matplotlib import PLOT_CONFIG, format_annotation
@@ -50,7 +50,7 @@ __all__ = ["VectorPlot"]
 VECTOR_CONFIG: dict[str, Any] = PLOT_CONFIG["vector"]
 
 
-class VectorPlot:
+class VectorPlot(FigureLifecycle):
     """Arrow chart showing the change in two variables.
 
     Each entity in ``series`` is rendered as an arrow from a
@@ -94,6 +94,17 @@ class VectorPlot:
         reproduces the dashed arrows used for outliers).
     """
 
+    #: Keys that change the PNG but never the ``to_plotly()`` figure
+    #: (see :func:`plotly_unsupported`); checked against real renders
+    #: by ``tests/test_plotly_support.py``.
+    PLOTLY_UNSUPPORTED: ClassVar[frozenset[str]] = frozenset(
+        {
+            "figsize",
+            "x_fmt.decimals",
+            "y_fmt.decimals",
+        }
+    )
+
     def __init__(
         self,
         out_path: Path,
@@ -205,7 +216,11 @@ class VectorPlot:
         y0 = float(row[self.y_start]) * self.y_scale if self.y_start else 0.0
         return x0, y0, x1, y1
 
-    def plot(self) -> Axes:
+    def build(self) -> tuple[Figure, Axes]:
+        """Render the chart in memory; :meth:`save` writes it.
+
+        :meth:`plot` (from :class:`FigureLifecycle`) does both.
+        """
         needed = [self.x, self.y]
         if self.x_start is not None:
             needed.append(self.x_start)
@@ -270,11 +285,7 @@ class VectorPlot:
             )
 
         self._style_axes(ax, xs, ys)
-        fig.savefig(  # type: ignore[reportUnknownMemberType]
-            self.out_path, dpi=dynamic_dpi(fig)
-        )
-        plt.close(fig)
-        return ax
+        return fig, ax
 
     def _style_axes(self, ax: Axes, xs: list[float], ys: list[float]) -> None:
         """Frame, origin cross-hairs, tick formatters and labels."""

tesorotools/artists/waterfall.py

@@ -17,7 +17,7 @@ row inside a Word table, reusing the shared compact helpers in
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Any, Self
+from typing import Any, ClassVar, Self
 
 import matplotlib.pyplot as plt
 import numpy as np
@@ -58,6 +58,18 @@ class Waterfall:
     last categories (opening and closing balance).
     """
 
+    #: Keys that change the PNG but never the ``to_plotly()`` figure
+    #: (see :func:`plotly_unsupported`); checked against real renders
+    #: by ``tests/test_plotly_support.py``.
+    PLOTLY_UNSUPPORTED: ClassVar[frozenset[str]] = frozenset(
+        {
+            "compact",
+            "figsize",
+            "font_pt",
+            "plot_size",
+        }
+    )
+
     def __init__(
         self,
         out_path: Path,

{tesorotools_python-0.1.0.dist-info → tesorotools_python-0.1.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tesorotools-python
-Version: 0.1.0
+Version: 0.1.2
 Requires-Python: >=3.13
 Requires-Dist: babel>=2.17
 Requires-Dist: matplotlib>=3.10

{tesorotools_python-0.1.0.dist-info → tesorotools_python-0.1.2.dist-info}/RECORD

@@ -1,4 +1,4 @@
-tesorotools/__init__.py,sha256=YQGi1L0Uo1B1ZFmjXFRSUFZI4kx7jeLFpdoi5GbRkJM,5296
+tesorotools/__init__.py,sha256=BV31YV_qabD4vdXzoKb89MxXO386YE0xFjXqpDZSXaE,5334
 tesorotools/_build_context.py,sha256=MH2AKjkwuubN__sBQoXbfTD1bh5RE6w9l5yUFxkJxy8,1982
 tesorotools/_registry.py,sha256=ZJOr7jACxykvzoepebZDiJdTcR37Q3X-DQ07lm9ZYB0,7975
 tesorotools/driver.py,sha256=qEVhLYanbG7VXe3WrCCD0RJV_0X4xzhalrfABPB1gSI,5016
@@ -7,21 +7,22 @@ tesorotools/orchestration.py,sha256=24C-LTM4uy7eckjXBjJbC2t92fg6yffl5H-E9Gm2W9M,
 tesorotools/palette.py,sha256=fkf1_AxweRzviwKLb5zSZnWwP_Cr4zEYoqJ4jqIfBoE,1944
 tesorotools/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tesorotools/scaffold.py,sha256=6mYNxLm_1CbEMjcYZ77m_2H1eTotbpatFJqhgyote0s,4578
-tesorotools/artists/__init__.py,sha256=bxzJfN_Id2fPqIFYTrqZNpV8Hge3rH5jBe9fsrrb5Ow,1972
-tesorotools/artists/_common.py,sha256=rqRa2fSUNtHCHoWOReLrzLBJA8Yrf5drOwUd5vkCCPk,54726
-tesorotools/artists/bar_line.py,sha256=CBNoQpHBjHnmNn_Kum7dZy6oD7RMRc9OsIh03YMZW9g,13969
-tesorotools/artists/barh_plot.py,sha256=OcucXrdbamvMRxW9jnGwuvpBR_0f9N5800GRSFTiDYM,36511
-tesorotools/artists/box_plot.py,sha256=UgaL23_I0VTGGRhffF3uGz1HPGM7FOjSq9szNf1EdwQ,19916
+tesorotools/artists/__init__.py,sha256=-w2IzVdT7iatJien_5JU9fHepx2kTcYcYgrjQXWZYRI,2492
+tesorotools/artists/_common.py,sha256=k59YvyxIlTSEUPU6-koGksOdEKvDcwjhsdPV0LxRCLo,59272
+tesorotools/artists/bar_line.py,sha256=4urcPuHEfohl4WI3pkb2I__1WZ2W73lDiGoqlwFA27w,14477
+tesorotools/artists/barh_plot.py,sha256=n8DjIX1APCVS7HW4zzfh6ehggdgBqb6sezQHov1k7us,37520
+tesorotools/artists/box_plot.py,sha256=KPQjbY2H5JWJWF_icApqpvE1f6sE4e56neIS_dRL6w8,20373
 tesorotools/artists/compact.py,sha256=e_0tqkRSIgyiyMSwirJzj2TYSKojMxUHzug5tE_7toc,3003
 tesorotools/artists/intraday_plot.py,sha256=TO-lKwwbIPxx4T-ObYHNuGGR3F_-GZ6XQGwrYU6tyL8,13259
-tesorotools/artists/line_plot.py,sha256=IpuZry0nljJa8pPQsjyCte5IhKHCmEZJwHeh7XsGzjo,28973
-tesorotools/artists/matrix.py,sha256=NRql8mmwEdH3XOJ6CsAm_PMI4YRGdz7qMOyTgQlJO_k,11421
-tesorotools/artists/plotly_backend.py,sha256=FpSpihjwaj3w9aye2w4aNLx1GHp6z3ta3pqxkB2QOgE,36828
-tesorotools/artists/shock_plot.py,sha256=A-X7Yr1vFHwyCk4qEEMLgqxTRPy2NBRo3fgRJPdpox4,13052
-tesorotools/artists/stacked.py,sha256=2jrEWh211m0NsLlWkKz22uyioxMfR2d5Qs6sBQnMciY,16431
-tesorotools/artists/type_curve.py,sha256=h48pFhOtNkS2nMq4e8sWUBFIxrlhlnfZto2xrciefGg,12153
-tesorotools/artists/vector_plot.py,sha256=XzBgFDWvAws_g6X8a_fm2tAe01zgMKwDNol0zLD6qCc,11807
-tesorotools/artists/waterfall.py,sha256=bFr7IW3vTf7ZN64SnxhbNm2AlGOh4b9IpWkXQEbzTPE,11972
+tesorotools/artists/line_plot.py,sha256=yqg7dHzzV_xfiwiWIlvNN6DVXQ9wjRBdOsiJYvG0iJY,31157
+tesorotools/artists/matrix.py,sha256=cOpj9ZO5RR0-RlIP55UmD70i-738ck8wZIqRiDO22Hw,11785
+tesorotools/artists/plotly_backend.py,sha256=yaRnZayxgTbNVuiJW1p5l10mo5UFMTslA_QK-nBkZsM,37067
+tesorotools/artists/sharing.py,sha256=Tg4AYtv0ileKQmzBSgmT1GzxA97tdU8ji_arE0oGEZ4,2236
+tesorotools/artists/shock_plot.py,sha256=Vx9RRvRaJZIXh8G7oJSRRc1XtPgGkqA6xaVk4h4oJuE,13435
+tesorotools/artists/stacked.py,sha256=MyItTb8NMOpR6jDclqjmofhAB-L9mD1vnzGQjXUTFBc,17439
+tesorotools/artists/type_curve.py,sha256=0j1LjfS4Zdz4_W7qp-nY8VP0H-fENV5adUg4syAOvig,12570
+tesorotools/artists/vector_plot.py,sha256=P7BtLCXRTWs3eepRFYvXzbJ9OkvB-Ya3kmXB6yJSkR0,12211
+tesorotools/artists/waterfall.py,sha256=S2w6LuMb9P71FA9aUygGd6KRAEQx8tfGps267YmLlSQ,12348
 tesorotools/assets/README.md,sha256=EjDuA4Xf-Omn0Khp8erNXdW-iyWBzSM2FQFexdrS6Eg,285
 tesorotools/assets/plots.yaml,sha256=shIDoQTYveZ7IWnG_5QAXESzq9trcRpkjtry2yXQsE0,11162
 tesorotools/assets/template.docx,sha256=QYilJmJ-ltGPH_GH22j6Kis7wmNaAgFQXr68d1KUSHY,94394
@@ -129,7 +130,7 @@ tesorotools/web/templates/src/$package/main.py.tmpl,sha256=GXG3AA87WOjk5nTKA5Ywm
 tesorotools/web/templates/src/$package/sections.py.tmpl,sha256=4MNZ85AW5ERG1SrkVAXIwdmAMeQEBARCYdAMqUr37mg,2084
 tesorotools/web/templates/tests/__init__.py.tmpl,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tesorotools/web/templates/tests/test_app.py.tmpl,sha256=ZGfV5GPN6WsS3a2gCNLPWejkHTX2H_N9XpurIADuUxI,615
-tesorotools_python-0.1.0.dist-info/METADATA,sha256=sbVZYK0lrHGJQ4VClTTOvYd3KEKpL1jXxoioHNyQHrg,993
-tesorotools_python-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-tesorotools_python-0.1.0.dist-info/entry_points.txt,sha256=PuNrObu4SVvajBHTASuWZPqwSsV7tPHwFJBzYk2nY5o,108
-tesorotools_python-0.1.0.dist-info/RECORD,,
+tesorotools_python-0.1.2.dist-info/METADATA,sha256=ARJoWsUX5H4GXfcoU7EH_sVTr5aUusS-9OpkhfTVm-A,993
+tesorotools_python-0.1.2.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+tesorotools_python-0.1.2.dist-info/entry_points.txt,sha256=PuNrObu4SVvajBHTASuWZPqwSsV7tPHwFJBzYk2nY5o,108
+tesorotools_python-0.1.2.dist-info/RECORD,,