tesorotools-python 0.0.53__tar.gz → 0.0.55__tar.gz

{tesorotools_python-0.0.53 → tesorotools_python-0.0.55}/.gitignore

@@ -36,4 +36,6 @@ test/
 .uv-cache/
 
 demo_compacto/
-demo/
+demo/
+
+*.env

{tesorotools_python-0.0.53 → tesorotools_python-0.0.55}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: tesorotools-python
-Version: 0.0.53
+Version: 0.0.55
 Requires-Python: >=3.13
 Requires-Dist: babel>=2.17
 Requires-Dist: matplotlib>=3.10
@@ -16,6 +16,8 @@ Provides-Extra: bde
 Requires-Dist: requests>=2.31; extra == 'bde'
 Provides-Extra: ecb
 Requires-Dist: requests>=2.31; extra == 'ecb'
+Provides-Extra: fred
+Requires-Dist: requests>=2.31; extra == 'fred'
 Provides-Extra: imf
 Requires-Dist: requests>=2.31; extra == 'imf'
 Requires-Dist: truststore>=0.10; extra == 'imf'

{tesorotools_python-0.0.53 → tesorotools_python-0.0.55}/pyproject.toml

@@ -27,6 +27,7 @@ dependencies = [
 [project.optional-dependencies]
 bde = ["requests>=2.31"]
 ecb = ["requests>=2.31"]
+fred = ["requests>=2.31"]
 imf = ["requests>=2.31", "truststore>=0.10"]
 lseg = ["lseg-data>=2.1"]
 interactive_plots = ["plotly>=5.0"]

{tesorotools_python-0.0.53 → tesorotools_python-0.0.55}/src/tesorotools/__init__.py

@@ -7,9 +7,11 @@ effects) and registers their YAML tags via
 
 Provider subclasses gated by optional extras
 (``BdeProvider`` requires ``[bde]``, ``EcbProvider``
-requires ``[ecb]``, ``LSEGProvider`` requires ``[lseg]``)
-are exposed lazily through ``__getattr__``; importing this
-module does not require the extras to be installed.
+requires ``[ecb]``, ``FredProvider`` requires ``[fred]``,
+``ImfIrfclProvider`` requires ``[imf]``, ``LSEGProvider``
+requires ``[lseg]``) 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`` (and their
@@ -31,6 +33,8 @@ except PackageNotFoundError:  # pragma: no cover - source-only checkout
 if TYPE_CHECKING:
     from tesorotools.providers.bde import BdeProvider
     from tesorotools.providers.ecb import EcbProvider
+    from tesorotools.providers.fred import FredProvider
+    from tesorotools.providers.imf_irfcl import ImfIrfclProvider
     from tesorotools.providers.lseg import LSEGProvider
 
 from tesorotools._build_context import BuildContext
@@ -131,10 +135,12 @@ __all__ = [
     "DataProvider",
     "EcbProvider",
     "Format",
+    "FredProvider",
     "GroupedBarChart",
     "HorizontalBarChart",
     "Image",
     "Images",
+    "ImfIrfclProvider",
     "IntradayPlot",
     "Legend",
     "LinePlot",
@@ -183,6 +189,14 @@ def __getattr__(name: str) -> Any:
         from tesorotools.providers.ecb import EcbProvider
 
         return EcbProvider
+    if name == "FredProvider":
+        from tesorotools.providers.fred import FredProvider
+
+        return FredProvider
+    if name == "ImfIrfclProvider":
+        from tesorotools.providers.imf_irfcl import ImfIrfclProvider
+
+        return ImfIrfclProvider
     if name == "LSEGProvider":
         from tesorotools.providers.lseg import LSEGProvider
 

{tesorotools_python-0.0.53 → tesorotools_python-0.0.55}/src/tesorotools/artists/_common.py

@@ -68,6 +68,11 @@ CM_TO_IN: float = 1.0 / 2.54
 # is missing a level; "default" reproduces the historical tick count of each mode
 # (4 for compact, 6 for non-compact).
 DATE_DENSITY_LEVELS: tuple[str, ...] = ("few", "default", "many")
+
+# Legend bands a chart may ask for. ``auto`` defers to the mode default:
+# ``compact.legend_position`` in ``plots.yaml`` for a compact chart (shipped
+# as "above"), ``below`` for a full-size one.
+LEGEND_POSITIONS: tuple[str, ...] = ("auto", "above", "below")
 _DATE_MAXTICKS_FALLBACK_COMPACT: dict[str, int] = {
     "few": 3,
     "default": 4,
@@ -229,28 +234,45 @@ class Format:
 class Legend:
     """Legend layout knobs carried in YAML.
 
-    Currently exposes ``ncol``; absent (None) means "let the
-    artist auto-fit using ``auto_ncol``".
+    ``ncol`` absent (None) means "let the artist auto-fit
+    using ``auto_ncol``".  ``position`` picks the band the
+    legend lives in: ``"above"`` the plot or ``"below"`` it;
+    ``"auto"`` (the default) keeps each mode's house default,
+    which for compact charts is read from
+    ``compact.legend_position`` in ``plots.yaml``.  Both
+    values work in compact and in full-size charts, so a
+    compact chart in a Word table can carry its labels under
+    the plot when the text above it already reads as a title.
     """
 
-    def __init__(self, ncol: int | None = None) -> None:
+    def __init__(self, ncol: int | None = None, position: str = "auto") -> None:
+        if position not in LEGEND_POSITIONS:
+            raise ValueError(
+                f"legend position must be one of {LEGEND_POSITIONS}: "
+                f"{position!r}"
+            )
         self.ncol = ncol
+        self.position = position
 
     @classmethod
     def from_yaml(cls, loader: TemplateLoader, node: MappingNode) -> Self:
         """Build a :class:`Legend` from a ``!legend`` YAML tag.
 
-        ``ncol`` is optional; omitting it (or passing
-        ``null``) lets the artist auto-fit using
-        :func:`auto_ncol`.  An empty ``!legend {}`` enables
-        the legend with auto-fitted columns.
+        Both keys are optional.  Omitting ``ncol`` (or
+        passing ``null``) lets the artist auto-fit using
+        :func:`auto_ncol`; omitting ``position`` keeps the
+        mode default (``compact.legend_position`` for a
+        compact chart, below the plot for a full-size one).
+        An empty ``!legend {}`` enables the legend with
+        auto-fitted columns in its default band.
 
         Example
         -------
         .. code-block:: yaml
 
-            legend: !legend {ncol: 3}      # explicit
-            legend: !legend {}             # auto-fit
+            legend: !legend {ncol: 3}            # explicit
+            legend: !legend {position: below}    # under the plot
+            legend: !legend {}                   # auto-fit
         """
         legend_cfg: dict[str, Any] = loader.construct_mapping(  # type: ignore[assignment]
             node, deep=True
@@ -526,6 +548,65 @@ def compact_legend_max_ncol() -> int | None:
     return None if raw is None else int(raw)
 
 
+def date_show_start_default(*, compact: bool) -> bool:
+    """House default for pinning the first datum as the leading x tick.
+
+    Reads ``compact.date_show_start`` / ``line.date_show_start`` from
+    ``plots.yaml`` (both shipped ``true``), so "does the chart say when the
+    series starts?" stays a data decision.  A per-chart
+    ``date_show_start: false`` overrides it.
+    """
+    cfg = COMPACT_CONFIG if compact else LINE_CONFIG
+    return bool(cfg.get("date_show_start", True))
+
+
+def date_span_ticks(
+    data_min: Any,
+    data_max: Any,
+    *,
+    maxticks: int,
+    pin_start: bool,
+) -> list[float]:
+    """Date ticks (as date numbers) computed over the **data span**.
+
+    ``AutoDateLocator`` candidates clipped to ``[data_min, data_max]``, so no
+    tick floats outside the plotted data: off-span ticks are what leave the
+    blank labels at both ends of pandas' own date axis, and in compact (where
+    ``margins(x=0)``) they get clipped by the figure edge.
+
+    With ``pin_start`` the first datum becomes the leading tick -- the only
+    way the reader can tell *when the series starts*, since the natural
+    calendar tick usually falls before it -- and any candidate closer than
+    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).
+    """
+    lo: float = float(cast(Any, date2num(data_min)))
+    hi: float = float(cast(Any, date2num(data_max)))
+    locator = AutoDateLocator(minticks=2, maxticks=maxticks)
+    candidates: list[float] = cast(
+        "list[float]", locator.tick_values(data_min, data_max)
+    )
+    if not pin_start:
+        return [t for t in candidates if lo <= t <= hi] or [lo, hi]
+    min_gap: float = (hi - lo) * 0.10
+    interior: list[float] = [
+        t for t in candidates if lo < t <= hi and t - lo >= min_gap
+    ]
+    return [lo, *interior]
+
+
+def compact_legend_position() -> str:
+    """Default legend band for compact charts (``compact.legend_position``).
+
+    ``"above"`` unless ``plots.yaml`` says otherwise: on a 7.4 cm figure the
+    bottom edge already carries the date ticks, so the top band is the
+    cheaper place to spend vertical space.  A per-chart
+    ``legend: !legend {position: below}`` always wins over this default.
+    """
+    return str(COMPACT_CONFIG.get("legend_position", "above"))
+
+
 def compact_headroom_pad_pt() -> float:
     """Points of clearance to leave above the top value label (0 if unset)."""
     return float(COMPACT_CONFIG.get("annotate_headroom_pad_pt", 0))
@@ -633,27 +714,16 @@ def compact_date_axis(
     given (an explicit angle wins).
     """
     lo: float = float(cast(Any, date2num(data_min)))
-    hi: float = float(cast(Any, date2num(data_max)))
-    locator = AutoDateLocator(minticks=2, maxticks=maxticks)
-    candidates: list[float] = cast(
-        "list[float]", locator.tick_values(data_min, data_max)
-    )
     show_start: bool = (
-        bool(COMPACT_CONFIG.get("date_show_start", True))
+        date_show_start_default(compact=True)
         if pin_start is None
         else pin_start
     )
-    interior: list[float] = [t for t in candidates if lo < t <= hi]
-    if show_start:
-        # pin the first data point as the leading tick so the reader sees
-        # exactly when the series starts (the natural calendar tick often
-        # falls just *before* the first datum and is clipped by margins=0).
-        # Drop any auto tick that would crowd the start label.
-        min_gap: float = (hi - lo) * 0.10
-        interior = [t for t in interior if t - lo >= min_gap]
-        ticks: list[float] = [lo, *interior]
-    else:
-        ticks = [t for t in candidates if lo <= t <= hi] or [lo, hi]
+    # same span-clipped ticks (and same pinned start) the non-compact axis
+    # uses, so both modes answer "when does this start?" identically
+    ticks: list[float] = date_span_ticks(
+        data_min, data_max, maxticks=maxticks, pin_start=show_start
+    )
 
     def _set_ticks(values: list[float]) -> None:
         loc = FixedLocator(values)
@@ -751,6 +821,9 @@ def apply_date_axis(
     *,
     maxticks: int,
     rotation: float | None = None,
+    data_min: Any = None,
+    data_max: Any = None,
+    pin_start: bool = False,
 ) -> None:
     """Native matplotlib date x-axis with a soft tick count and optional slant.
 
@@ -761,17 +834,35 @@ def apply_date_axis(
     instance (the concise context logic misfires with a mismatched one).
     ``rotation`` (degrees) tilts the labels; ``None`` keeps them horizontal.
 
-    Unlike the compact path this changes the label **text style** too (concise
-    hierarchical labels instead of pandas' own date formatting), so callers use
-    it only when the user explicitly asks for a non-default density or rotation.
+    ``pin_start`` (with the ``data_min`` / ``data_max`` span) switches to the
+    span-clipped :func:`date_span_ticks` with the first datum pinned as the
+    leading tick and :class:`_StartLabeledConcise` to spell that date out --
+    the same treatment the compact axis gives it.  Pandas' own date axis
+    cannot do this: its formatter only labels the positions its own locator
+    produced, so a pinned tick comes out blank; that is why pinning the start
+    means taking the axis over here.
+
+    Taking over changes the label **text style** too (concise hierarchical
+    labels instead of pandas' own date formatting).
+
+    The tilt is always set explicitly, never inherited: pandas leaves the
+    x labels rotated 30 degrees on the ``x_compat`` path this axis needs, so
+    ``rotation=None`` has to *actively* flatten them to keep the documented
+    "horizontal unless asked" behaviour.
     """
-    locator = AutoDateLocator(minticks=2, maxticks=maxticks)
-    ax.xaxis.set_major_locator(locator)
-    ax.xaxis.set_major_formatter(ConciseDateFormatter(locator))
-    if rotation is None or rotation == 0:
-        return
-    rot = float(rotation)
-    ha = _date_label_ha(rotation)
+    if pin_start and data_min is not None and data_max is not None:
+        ticks = date_span_ticks(
+            data_min, data_max, maxticks=maxticks, pin_start=True
+        )
+        fixed = FixedLocator(ticks)
+        ax.xaxis.set_major_locator(fixed)
+        ax.xaxis.set_major_formatter(_StartLabeledConcise(fixed, ticks[0]))
+    else:
+        locator = AutoDateLocator(minticks=2, maxticks=maxticks)
+        ax.xaxis.set_major_locator(locator)
+        ax.xaxis.set_major_formatter(ConciseDateFormatter(locator))
+    rot = 0.0 if rotation is None else float(rotation)
+    ha = _date_label_ha(None if rot == 0 else rot)
     ax.tick_params(  # type: ignore[reportUnknownMemberType]
         axis="x", rotation=rot
     )
@@ -780,7 +871,8 @@ def apply_date_axis(
         fig.canvas.draw()  # type: ignore[reportUnknownMemberType]
     for label in ax.get_xticklabels():
         label.set_horizontalalignment(ha)
-        label.set_rotation_mode("anchor")
+        if rot != 0:
+            label.set_rotation_mode("anchor")
 
 
 def compact_y_axis(ax: Axes) -> None:
@@ -802,42 +894,100 @@ def compact_y_axis(ax: Axes) -> None:
     )
 
 
-def legend_above(
+def resolve_legend_position(position: str, *, compact: bool) -> str:
+    """Resolve a :class:`Legend` ``position`` to the band to draw in.
+
+    ``"above"`` / ``"below"`` are honoured as given, in **both** modes.
+    ``"auto"`` keeps the house default of each mode: the compact band read
+    from ``compact.legend_position`` (see :func:`compact_legend_position`)
+    and ``"below"`` for a full-size chart, which is where every non-compact
+    chart has always put it.  Returns ``"above"`` or ``"below"``.
+    """
+    if position != "auto":
+        return position
+    return compact_legend_position() if compact else "below"
+
+
+def legend_band(
     ax: Axes,
     handles: list[Any],
     labels: list[str],
     *,
     ncol: int,
+    position: str = "above",
     fontsize: float | None = None,
     handlelength: float | None = None,
     handletextpad: float | None = None,
     columnspacing: float | None = None,
+    frameon: bool | None = None,
 ) -> MplLegend:
-    """Place the legend in a band **above the axes, spanning the figure**.
-
-    Uses ``loc="outside upper center"`` so constrained layout reserves a
-    strip at the top of the *figure* and the legend may use the whole
-    figure width -- wider than the narrow compact axes, whose left edge
-    is eaten by the y-tick numbers and whose right edge is eaten by the
-    end-of-series value labels.  Spanning the figure lets the maximum
-    number of columns share one row, which **minimises the vertical
-    space the legend steals from the plot** (fewer rows = taller chart).
-
-    ``fontsize`` / ``handlelength`` / ``handletextpad`` /
-    ``columnspacing`` style the legend (``None`` keeps the
-    ``rcParams`` default); the compact mode passes a smaller
-    font and shorter handles so more labels fit per row.
+    """Place the legend in a band **outside the axes, spanning the figure**.
+
+    ``position`` picks the edge: ``"above"`` (``loc="outside upper
+    center"``) or ``"below"`` (``loc="outside lower center"``).  Either way
+    constrained layout reserves a full-width strip on that side of the
+    *figure*, so the legend may use the whole figure width -- wider than the
+    narrow compact axes, whose left edge is eaten by the y-tick numbers and
+    whose right edge is eaten by the end-of-series value labels.  Spanning
+    the figure lets the maximum number of columns share one row, which
+    **minimises the vertical space the legend steals from the plot** (fewer
+    rows = taller chart), whichever side it sits on.
+
+    Above is the compact default (the bottom edge already spends space on
+    the date ticks); below is the classic report look and the default of the
+    full-size charts.  ``fontsize`` / ``handlelength`` / ``handletextpad`` /
+    ``columnspacing`` / ``frameon`` style the legend (``None`` keeps the
+    ``rcParams`` default); the compact mode passes a smaller font, shorter
+    handles and no box so more labels fit per row.
     """
     fig = ax.get_figure()
+    loc = (
+        "outside upper center"
+        if position == "above"
+        else "outside lower center"
+    )
     return fig.legend(  # type: ignore[reportUnknownMemberType, reportOptionalMemberAccess]
         handles,
         labels,
-        loc="outside upper center",
+        loc=loc,
         ncol=ncol,
         fontsize=fontsize,
         handlelength=handlelength,
         handletextpad=handletextpad,
         columnspacing=columnspacing,
+        frameon=frameon,
+    )
+
+
+def legend_above(
+    ax: Axes,
+    handles: list[Any],
+    labels: list[str],
+    *,
+    ncol: int,
+    fontsize: float | None = None,
+    handlelength: float | None = None,
+    handletextpad: float | None = None,
+    columnspacing: float | None = None,
+) -> MplLegend:
+    """Frameless legend band above the axes.
+
+    Thin shortcut for ``legend_band(..., position="above",
+    frameon=False)``, kept because it is the call the compact toolkit has
+    always exported for third-party artists.  New code should call
+    :func:`legend_band` (or better :func:`place_legend`) so the band side
+    stays configurable.
+    """
+    return legend_band(
+        ax,
+        handles,
+        labels,
+        ncol=ncol,
+        position="above",
+        fontsize=fontsize,
+        handlelength=handlelength,
+        handletextpad=handletextpad,
+        columnspacing=columnspacing,
         frameon=False,  # no box: less clutter in the tight compact figure
     )
 
@@ -918,19 +1068,23 @@ def place_legend(
     *,
     compact: bool,
     ncol: int | None = None,
+    position: str = "auto",
 ) -> 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.
+    Compact charts get a frameless band spanning the figure width with the
+    compact legend metrics; ``ncol`` is auto-fitted to that width and
+    hard-capped by :func:`compact_legend_max_ncol` unless the caller passes
+    an explicit ``ncol``.  Non-compact charts get the same band with the
+    ``rcParams`` metrics.  ``position`` (``"above"`` / ``"below"`` /
+    ``"auto"``) chooses the side through :func:`resolve_legend_position`, so
+    a compact chart can carry its legend under the plot instead of over it.
+    Returns ``None`` (drawing nothing) when there are no labels.
     """
     handles, labels = ax.get_legend_handles_labels()
     if not labels:
         return None
+    side = resolve_legend_position(position, compact=compact)
     fig_w_px: float = fig.get_size_inches()[0] * fig.dpi
     if compact:
         legend_kw = compact_legend_kwargs()
@@ -941,15 +1095,37 @@ def place_legend(
             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)
+        return legend_band(
+            ax,
+            handles,
+            labels,
+            ncol=ncol,
+            position=side,
+            frameon=False,
+            **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,
-    )
+    return legend_band(ax, handles, labels, ncol=ncol, position=side)
+
+
+def legend_layout(legend: Legend | None) -> dict[str, Any]:
+    """``place_legend`` layout kwargs from an optional :class:`Legend` holder.
+
+    Every artist carries a ``legend: Legend | None`` (absent means "house
+    defaults"), so this maps the holder to the ``ncol`` / ``position`` pair
+    in one place instead of each artist repeating a
+    ``self.legend.x if self.legend else <default>`` per knob -- and a new
+    knob then reaches every artist at once::
+
+        place_legend(
+            fig, ax, compact=self.compact, **legend_layout(self.legend)
+        )
+    """
+    return {
+        "ncol": legend.ncol if legend is not None else None,
+        "position": legend.position if legend is not None else "auto",
+    }
 
 
 def declutter_spines(ax: Axes, side: str = "left") -> None:

{tesorotools_python-0.0.53 → tesorotools_python-0.0.55}/src/tesorotools/artists/bar_line.py

@@ -45,6 +45,7 @@ from tesorotools.artists._common import (
     compact_figure_kwargs,
     compact_font_pt,
     dynamic_dpi,
+    legend_layout,
     place_legend,
     resolve_data,
     style_baseline,
@@ -323,9 +324,10 @@ class BarLinePlot:
         if self.compact:
             style_compact_axes(ax, font_pt, side="right")
 
-        legend_ncol = self.legend.ncol if self.legend else None
         if self.legend is not None:
-            place_legend(fig, ax, compact=self.compact, ncol=legend_ncol)
+            place_legend(
+                fig, ax, compact=self.compact, **legend_layout(self.legend)
+            )
 
         if self.plot_size is not None and not self.compact:
             adjust_figure_for_plot_size(fig, ax, self.plot_size)

{tesorotools_python-0.0.53 → tesorotools_python-0.0.55}/src/tesorotools/artists/barh_plot.py

@@ -40,6 +40,7 @@ from tesorotools.artists._common import (
     compact_figure_kwargs,
     compact_font_pt,
     dynamic_dpi,
+    legend_layout,
     place_legend,
     resolve_data,
 )
@@ -928,11 +929,12 @@ class GroupedBarChart:
                 axis="both", labelsize=font_pt
             )
 
-        # compact gets the legend in a band above the axes (spanning the
-        # figure width, columns auto-fitted and capped); non-compact gets
-        # the house lower-centre band.
-        legend_ncol = self.legend.ncol if self.legend else None
-        place_legend(fig, ax, compact=self.compact, ncol=legend_ncol)
+        # the legend lives in a band spanning the figure width: above the
+        # axes in compact (columns auto-fitted and capped), below it at full
+        # size. !legend {position} overrides the side.
+        place_legend(
+            fig, ax, compact=self.compact, **legend_layout(self.legend)
+        )
 
         # compact fixes the figure size, so the axes-sizing pass would fight
         # it; skip it there (mirrors LinePlot).

{tesorotools_python-0.0.53 → tesorotools_python-0.0.55}/src/tesorotools/artists/box_plot.py

@@ -53,8 +53,9 @@ from tesorotools.artists._common import (
     compact_font_pt,
     compact_legend_kwargs,
     dynamic_dpi,
-    legend_above,
+    legend_band,
     resolve_data,
+    resolve_legend_position,
     style_compact_axes,
     style_spines,
 )
@@ -478,19 +479,28 @@ class BoxPlot:
         if not draw_last:
             handles, labels = handles[:-1], labels[:-1]
         fig_w_px: float = fig.get_size_inches()[0] * fig.dpi
+        position = resolve_legend_position(
+            self.legend.position, compact=self.compact
+        )
         if self.compact:
             kw = compact_legend_kwargs()
             ncol = self.legend.ncol or auto_ncol(
                 ax, labels, available_width_px=fig_w_px, **kw
             )
-            legend_above(ax, handles, labels, ncol=ncol, **kw)
+            legend_band(
+                ax,
+                handles,
+                labels,
+                ncol=ncol,
+                position=position,
+                frameon=False,
+                **kw,
+            )
         else:
             ncol = self.legend.ncol or auto_ncol(
                 ax, labels, available_width_px=fig_w_px
             )
-            fig.legend(  # type: ignore[reportUnknownMemberType]
-                handles, labels, loc="outside lower center", ncol=ncol
-            )
+            legend_band(ax, handles, labels, ncol=ncol, position=position)
 
     def save(
         self,

{tesorotools_python-0.0.53 → tesorotools_python-0.0.55}/src/tesorotools/artists/compact.py

@@ -18,11 +18,19 @@ into :mod:`tesorotools.artists._common`.  The recipe is:
    point size (equal to what the reader sees in Word).
 3. Draw the chart, then ``style_compact_axes(ax, font_pt, side=...)`` to
    pin the tick label size and the y-axis side / spines.
-4. ``place_legend(fig, ax, compact=compact)`` -- the above-the-axes band
-   with auto-fitted, capped columns.
+4. ``place_legend(fig, ax, compact=compact, **legend_layout(legend))``
+   -- the full-figure-width legend band with auto-fitted, capped columns,
+   above the axes by default and below them when the chart's
+   ``!legend {position: below}`` (or ``compact.legend_position``) asks for
+   it.
 5. For a date x-axis, ``compact_date_axis(ax, lo, hi)`` thins the ticks to
    a few concise labels.
 
+Legend side: the band sits above the axes by default (the bottom edge
+already spends space on the date ticks).  ``compact.legend_position`` in
+``plots.yaml`` flips that default for every compact chart and
+``legend: !legend {position: above|below}`` decides it per chart.
+
 Legends note: a compact figure is only ~7.4 cm wide, so a few long labels
 (e.g. ``"Pre-conflicto 2026-02-27"``) collapse the column fit to a single
 tall column that eats the chart.  Shorten labels for compact charts and
@@ -41,10 +49,14 @@ from tesorotools.artists._common import (
     compact_legend_font_pt,
     compact_legend_kwargs,
     compact_legend_max_ncol,
+    compact_legend_position,
     compact_y_axis,
     declutter_spines,
     legend_above,
+    legend_band,
+    legend_layout,
     place_legend,
+    resolve_legend_position,
     style_compact_axes,
 )
 
@@ -58,9 +70,13 @@ __all__ = [
     "compact_legend_font_pt",
     "compact_legend_kwargs",
     "compact_legend_max_ncol",
+    "compact_legend_position",
     "compact_y_axis",
     "declutter_spines",
     "legend_above",
+    "legend_band",
+    "legend_layout",
     "place_legend",
+    "resolve_legend_position",
     "style_compact_axes",
 ]