TYP: Accept tuples in Legend handles list

Fixes matplotlib#26639

Author: QuLogic

lib/matplotlib/axes/_axes.py

@@ -280,7 +280,7 @@ def legend(self, *args, **kwargs):
 
         Parameters
         ----------
-        handles : sequence of `.Artist`, optional
+        handles : sequence of (`.Artist` or tuple of `.Artist`), optional
             A list of Artists (lines, patches) to be added to the legend.
             Use this together with *labels*, if you need full control on what
             is shown in the legend and the automatic mechanism described above
@@ -289,6 +289,9 @@ def legend(self, *args, **kwargs):
             The length of handles and labels should be the same in this
             case. If they are not, they are truncated to the smaller length.
 
+            If an entry contains a tuple, then the legend handler for all Artists in the
+            tuple will be placed alongside a single label.
+
         labels : list of str, optional
             A list of labels to show next to the artists.
             Use this together with *handles*, if you need full control on what

lib/matplotlib/axes/_axes.pyi

@@ -57,9 +57,9 @@ class Axes(_AxesBase):
     @overload
     def legend(self) -> Legend: ...
     @overload
-    def legend(self, handles: Sequence[Artist], labels: Sequence[str], **kwargs) -> Legend: ...
+    def legend(self, handles: Sequence[Artist | tuple[Artist, ...]], labels: Sequence[str], **kwargs) -> Legend: ...
     @overload
-    def legend(self, *, handles: Sequence[Artist], **kwargs) -> Legend: ...
+    def legend(self, *, handles: Sequence[Artist | tuple[Artist, ...]], **kwargs) -> Legend: ...
     @overload
     def legend(self, labels: Sequence[str], **kwargs) -> Legend: ...
     @overload

lib/matplotlib/legend.py

@@ -401,7 +401,7 @@ def __init__(
         parent : `~matplotlib.axes.Axes` or `.Figure`
             The artist that contains the legend.
 
-        handles : list of `.Artist`
+        handles : list of (`.Artist` or tuple of `.Artist`)
             A list of Artists (lines, patches) to be added to the legend.
 
         labels : list of str
@@ -1322,7 +1322,7 @@ def _parse_legend_args(axs, *args, handles=None, labels=None, **kwargs):
 
     Returns
     -------
-    handles : list of `.Artist`
+    handles : list of (`.Artist` or tuple of `.Artist`)
         The legend handles.
     labels : list of str
         The legend labels.

lib/matplotlib/legend.pyi

@@ -52,7 +52,7 @@ class Legend(Artist):
     def __init__(
         self,
         parent: Axes | Figure,
-        handles: Iterable[Artist],
+        handles: Iterable[Artist | tuple[Artist, ...]],
         labels: Iterable[str],
         *,
         loc: str | tuple[float, float] | int | None = ...,