From 07effe59b0c219955f8e5677e5eb5f84399bc3fb Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Mon, 16 Sep 2024 11:40:12 +0200
Subject: [PATCH] Change return type

---
 lib/matplotlib/axes/_axes.py  | 32 +++++++++++++++++++++++++++-----
 lib/matplotlib/axes/_axes.pyi |  5 +++++
 2 files changed, 32 insertions(+), 5 deletions(-)

diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
index f7a1358f8e4f..9e94177ca692 100644
--- a/lib/matplotlib/axes/_axes.py
+++ b/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'):
diff --git a/lib/matplotlib/axes/_axes.pyi b/lib/matplotlib/axes/_axes.pyi
index ccc972465ea1..6b33492e02f5 100644
--- a/lib/matplotlib/axes/_axes.pyi
+++ b/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(