Change return type

Author: timhoffm

lib/matplotlib/axes/_axes.py

@@ -64,6 +64,23 @@ def _make_axes_method(func):
     return func
 
 
+class _GroupedBarReturn:
+    """
+    A provisional result object for `.Axes.grouped_bar`.
+
+    This is a placeholder for a future better return type. We try to build in
+    backward compatibility / migration possibilities.
+
+    The only public interfaces are the ``bar_containers`` attribute and the
+    ``remove()`` method.
+    """
+    def __init__(self, bar_containers):
+        self.bar_containers = bar_containers
+
+    def remove(self):
+        [b.remove() for b in self.bars]
+
+
 @_docstring.interpd
 class Axes(_AxesBase):
     """
@@ -3161,12 +3178,17 @@ def grouped_bar(self, x, heights, *, group_spacing=1.5, bar_spacing=0,
 
         Returns
         -------
-            list of `.BarContainer`
-                The results of the individual `~.Axes.bar` calls for each dataset.
+            _GroupedBarReturn
+
+                A provisional result object. This will be refined in the future.
+                For now, the API is limited to
+
+                - the attribute ``bar_containers``, which is a list of
+                  `.BarContainer`, i.e. the results of the individual `~.Axes.bar`
+                  calls for each dataset.
 
-                .. warning::
-                    The return type is provisional and will likely be replaced
-                    by a more convenient object.
+                - a ``remove()`` method, that remove all bars from the Axes.
+                  See also `.Artist.remove()`.
 
         """
         if hasattr(heights, 'keys'):

lib/matplotlib/axes/_axes.pyi

@@ -40,6 +40,11 @@ import numpy as np
 from numpy.typing import ArrayLike
 from matplotlib.typing import ColorType, MarkerType, LineStyleType
 
+
+class _GroupedBarReturn:
+    def __init__(self, bar_containers: list[BarContainer]) -> None: ...
+    def remove(self) -> None: ...
+
 class Axes(_AxesBase):
     def get_title(self, loc: Literal["left", "center", "right"] = ...) -> str: ...
     def set_title(