gsplot.legends#

legends(target, *, replace=False, props=None, **kwargs)#

Create legends for explicit axes with discoverable entries.

Parameters:

  • target (Figure | Sequence[Axes] | Mapping[object, Axes]) – Figure, Axes sequence, or string-keyed Axes mapping to inspect.

  • replace (bool) – Remove existing legends only when explicitly set to True.

  • props (Mapping[str, Any] | None) – Optional finite Matplotlib Legend constructor properties.

  • **kwargs (Any) – Optional direct Matplotlib Legend constructor properties. Direct keyword arguments are merged with and take precedence over props.

Returns:

Native legends created for axes that have discoverable entries.

Return type:

tuple[matplotlib.legend.Legend, ]

Raises:

LayoutError – If the target, replacement control, or properties are invalid.

Examples

>>> import gsplot as gs
>>> figure, axes = gs.subplots(ncols=2)
>>> for axis in axes:
...     gs.line(axis, [0, 1], [0, 1], props={"label": "signal"})
[<matplotlib.lines.Line2D object ...>]
[<matplotlib.lines.Line2D object ...>]
>>> items = gs.legends(figure)
>>> len(items)
2
>>> figure.clear()