ENH: Add properties position_centers and tops to BarContainer

timhoffm · timhoffm · commit df22b8ae87f8 · 2025-06-30T16:37:19.000+02:00
diff --git a/doc/users/next_whats_new/barcontainer_properties.rst b/doc/users/next_whats_new/barcontainer_properties.rst
@@ -0,0 +1,4 @@
+``BarContainer`` properties
+---------------------------
+`.BarContainer` gained two properties: `~.BarContainer.position_centers`
+and `~.BarContainer.tops`.
diff --git a/lib/matplotlib/container.py b/lib/matplotlib/container.py
@@ -73,6 +73,34 @@ def __init__(self, patches, errorbar=None, *, datavalues=None,
         self.orientation = orientation
         super().__init__(patches, **kwargs)
 
+    @property
+    def tops(self):
+        """
+        Return the values at the upper end of the bars.
+
+        .. versionadded:: 3.11
+        """
+        if self.orientation == 'vertical':
+            return [p.get_y() + p.get_height() for p in self.patches]
+        elif self.orientation == 'horizontal':
+            return [p.get_x() + p.get_width() for p in self.patches]
+        else:
+            raise ValueError("Orientation must be 'vertical' or 'horizontal'.")
+
+    @property
+    def position_centers(self):
+        """
+        Return the centers of bar positions.
+
+        .. versionadded:: 3.11
+        """
+        if self.orientation == 'vertical':
+            return [p.get_x() + p.get_width() / 2 for p in self.patches]
+        elif self.orientation == 'horizontal':
+            return [p.get_y() + p.get_height() / 2 for p in self.patches]
+        else:
+            raise ValueError("Orientation must be 'vertical' or 'horizontal'.")
+
 
 class ErrorbarContainer(Container):
     """
diff --git a/lib/matplotlib/container.pyi b/lib/matplotlib/container.pyi
@@ -32,6 +32,10 @@ class BarContainer(Container):
         orientation: Literal["vertical", "horizontal"] | None = ...,
         **kwargs
     ) -> None: ...
+    @property
+    def position_centers(self) -> list[float]: ...
+    @property
+    def tops(self) -> list[float]: ...
 
 class ErrorbarContainer(Container):
     lines: tuple[Line2D, tuple[Line2D, ...], tuple[LineCollection, ...]]
diff --git a/lib/matplotlib/tests/test_container.py b/lib/matplotlib/tests/test_container.py
@@ -1,4 +1,5 @@
 import numpy as np
+from numpy.testing import assert_array_equal
 import matplotlib.pyplot as plt
 
 
@@ -35,3 +36,18 @@ def test_nonstring_label():
     # Test for #26824
     plt.bar(np.arange(10), np.random.rand(10), label=1)
     plt.legend()
+
+
+def test_barcontainer_position_centers_and_tops():
+    fig, ax = plt.subplots()
+    pos = [1, 2, 4]
+    bottoms = np.array([1, 5, 3])
+    heights = np.array([2, 3, 4])
+
+    container = ax.bar(pos, heights, bottom=bottoms)
+    assert_array_equal(container.position_centers, pos)
+    assert_array_equal(container.tops, bottoms + heights)
+
+    container = ax.barh(pos, heights, left=bottoms)
+    assert_array_equal(container.position_centers, pos)
+    assert_array_equal(container.tops, bottoms + heights)
