Return a list of BarContainer

Author: timhoffm

lib/matplotlib/axes/_axes.py

@@ -3140,6 +3140,10 @@ def grouped_bar(self, x, heights, *, group_spacing=1.5, bar_spacing=0,
 
             %(Rectangle:kwdoc)s
 
+        Returns
+        -------
+            A list of `.BarContainer` instances, one for each dataset.
+
         """
         if hasattr(heights, 'keys'):
             if labels is not None:
@@ -3196,24 +3200,26 @@ def grouped_bar(self, x, heights, *, group_spacing=1.5, bar_spacing=0,
 
         # place the bars, but only use numerical positions, categorical tick labels
         # are handled separately below
+        result = []
         for i, (hs, label, color) in enumerate(
                 zip(heights, labels, colors)):
             lefts = (group_centers - 0.5 * group_distance + margin_abs
                      + i * (bar_width + bar_spacing_abs))
             if orientation == "vertical":
-                self.bar(lefts, hs, width=bar_width, align="edge",
-                         label=label, color=color, **kwargs)
+                bc = self.bar(lefts, hs, width=bar_width, align="edge",
+                              label=label, color=color, **kwargs)
             else:
-                self.barh(lefts, hs, height=bar_width, align="edge",
-                          label=label, color=color, **kwargs)
+                bc = self.barh(lefts, hs, height=bar_width, align="edge",
+                               label=label, color=color, **kwargs)
+            result.append(bc)
 
         if tick_labels is not None:
             if orientation == "vertical":
                 self.xaxis.set_ticks(group_centers, labels=tick_labels)
             else:
                 self.yaxis.set_ticks(group_centers, labels=tick_labels)
 
-        # TODO: does not return anything for now
+        return result
 
     @_preprocess_data()
     def stem(self, *args, linefmt=None, markerfmt=None, basefmt=None, bottom=0,

lib/matplotlib/axes/_axes.pyi

@@ -290,7 +290,7 @@ class Axes(_AxesBase):
         orientation: Literal["vertical", "horizontal"] = ...,
         colors: Iterable[ColorType] | None = ...,
         **kwargs
-    ) -> None: ...
+    ) -> list[BarContainer]: ...
     def stem(
         self,
         *args: ArrayLike | str,

lib/matplotlib/pyplot.py

@@ -3400,8 +3400,8 @@ def grouped_bar(
     orientation: Literal["vertical", "horizontal"] = "vertical",
     colors: Iterable[ColorType] | None = None,
     **kwargs,
-) -> None:
-    gca().grouped_bar(
+) -> list[BarContainer]:
+    return gca().grouped_bar(
         x,
         heights,
         group_spacing=group_spacing,