publiplots.legend

publiplots.legend(axes=None, collect=None, *, side=<object object>, anchor=None, figure=None, orientation='auto', align='auto', x_offset=None, y_offset=None, gap=2, column_spacing=5, vpad=None, max_width=None, rows=None, cols=None, span=None, ax=None, inside=False, clear_anchor=<object object>)[source]

Create a publication-ready legend for one axes, a subset, or the full figure.

Unified replacement for the legacy pp.legend_group API (pre-0.10). The first positional is the scope — which axes to collect legend entries from — and the anchor is derived automatically.

Parameters:

  • axes (Axes, sequence of Axes, or None) –

    Scope of the legend.

    • A single Axes: per-axes legend pinned to that axes (lives inside the axes tightbbox).

    • A list/array of Axes: shared band over the scope’s bounding rect (lives outside the axes, measured as an overhang by SubplotsAutoLayout).

    • None (default): full-figure band over the whole subplot grid.

  • collect (sequence of str, optional) – Names of entries to collect from the scope’s stashed LegendEntry objects. None collects everything; an empty list [] skips auto-collection entirely (equivalent to the old pp.legend(ax, auto=False) idiom — use it when adding manual handles via add_legend(...)).

  • side ({"right", "bottom", "left", "top"}, default "right") – Which edge of the scope the band grows outward from.

  • anchor (Axes, optional) – Advanced override: pin the band’s geometry to a specific axes’ edge, while still collecting entries from the axes scope. Rarely needed — defaults to the scope’s bounding rect.

  • figure (Figure, optional) – Figure to attach a full-figure band to. Defaults to plt.gcf().

  • orientation (str) – Same meaning as on MultiAxesLegendGroup.

  • align (str) – Same meaning as on MultiAxesLegendGroup.

  • x_offset (float | None) – Same meaning as on MultiAxesLegendGroup.

  • y_offset (float | None) – Same meaning as on MultiAxesLegendGroup.

  • gap (float) – Same meaning as on MultiAxesLegendGroup.

  • column_spacing (float) – Same meaning as on MultiAxesLegendGroup.

  • vpad (float | None) – Same meaning as on MultiAxesLegendGroup.

  • max_width (float | None) – Same meaning as on MultiAxesLegendGroup.

Examples

>>> pp.legend(ax)                          # per-axes legend
>>> pp.legend(axes[0])                     # row 0 band
>>> pp.legend(axes[:, 0], side='left')     # column-0 band
>>> pp.legend(side='right')                # full-figure right band
>>> pp.legend(side='bottom', collect=['group'])
Returns:

The constructed group. Can be further customized via group.add_legend(...) / group.add_colorbar(...).

Return type:

MultiAxesLegendGroup

Notes

Positional vs. keyword asymmetry on a single axes. There is a deliberate semantic split between the two spellings of “legend for one axes”:

  • pp.legend(ax) (positional) — internal per-axes legend; the legend counts against ax.get_tightbbox() and the axes reserves its own space (like pre-0.10 pp.legend(ax)).

  • pp.legend(anchor=ax) (keyword) — external band pinned to that axes’ edge; the legend is measured as an overhang by SubplotsAutoLayout and grows the figure’s per-cell reservation (like pre-0.10 pp.legend_group(anchor=ax)).

Both render the same visually for a single isolated axes. They differ under pp.subplots where the distinction controls which reservation the layout reactor grows.