remove arg 'shifting', rename arg 'label_type', improve docstring

Author: immaxchen

examples/lines_bars_and_markers/bar_label_demo.py

@@ -66,9 +66,9 @@
 ax.set_xticklabels(('G1', 'G2', 'G3', 'G4', 'G5'))
 ax.legend()
 
-# Label with position 'center' instead of the default 'edge'
-ax.bar_label(p1, position='center')
-ax.bar_label(p2, position='center')
+# Label with label_type 'center' instead of the default 'edge'
+ax.bar_label(p1, label_type='center')
+ax.bar_label(p2, label_type='center')
 ax.bar_label(p2)
 
 plt.show()
@@ -112,12 +112,10 @@
 ax.set_xlabel('Performance')
 ax.set_title('How fast do you want to go today?')
 
-# Label with given captions, custom padding, shifting and annotate option
-arrowprops = dict(color='b', arrowstyle="-|>",
-                  connectionstyle="angle,angleA=0,angleB=90,rad=20")
+# Label with given captions, custom padding and annotate options
 ax.bar_label(hbars, labels=['±%.2f' % e for e in error],
-             padding=30, shifting=20, arrowprops=arrowprops, color='b')
-ax.set_xlim(right=17)
+             padding=8, color='b', fontsize=14)
+ax.set_xlim(right=16)
 
 plt.show()
 

lib/matplotlib/axes/_axes.py

@@ -2498,8 +2498,8 @@ def barh(self, y, width, height=0.8, left=None, *, align="center",
                            align=align, **kwargs)
         return patches
 
-    def bar_label(self, container, labels=None, *, fmt="%g", position="edge",
-                  padding=0, shifting=0, **kwargs):
+    def bar_label(self, container, labels=None, *, fmt="%g", label_type="edge",
+                  padding=0, **kwargs):
         """
         Label a bar plot.
 
@@ -2518,18 +2518,18 @@ def bar_label(self, container, labels=None, *, fmt="%g", position="edge",
         fmt : str, default: '%g'
             A format string for the label.
 
-        position : {'edge', 'center'}, default: 'edge'
-            Position of the label relative to the bar:
+        label_type : {'edge', 'center'}, default: 'edge'
+            The label type, Possible values:
 
-            - 'edge': the value is the position of the edge.
-                      (cumulative for stacked bars)
-            - 'center': the value shown will be the length of the bar.
+            - 'edge': label placed at the end-point of the bar segment, and the
+              value displayed will be the position of that end-point.
+            - 'center': label placed in the center of the bar segment, and the
+              value displayed will be the length of that segment.
+              (useful for stacked bars, i.e.
+              :doc:`/gallery/lines_bars_and_markers/bar_label_demo`)
 
         padding : float, default: 0
-            Offset in points parallel to the direction of the bar.
-
-        shifting : float, default: 0
-            Offset in points perpendicular to the direction of the bar.
+            Distance of label from the end of the bar.
 
         **kwargs : passed through to `.Axes.annotate`.
 
@@ -2544,7 +2544,7 @@ def bar_label(self, container, labels=None, *, fmt="%g", position="edge",
         def sign(x):
             return 1 if x >= 0 else -1
 
-        cbook._check_in_list(['edge', 'center'], position=position)
+        cbook._check_in_list(['edge', 'center'], label_type=label_type)
 
         bars = container.patches
         errorbar = container.errorbar
@@ -2579,35 +2579,34 @@ def sign(x):
             elif orientation == "horizontal":
                 endpt = err[:, 0].max() if xc >= 0 else err[:, 0].min()
 
-            if position == "center":
+            if label_type == "center":
                 value = sign(extrema) * length
-            elif position == "edge":
+            elif label_type == "edge":
                 value = extrema
 
-            if position == "center":
+            if label_type == "center":
                 xy = xc, yc
-            elif position == "edge" and orientation == "vertical":
+            elif label_type == "edge" and orientation == "vertical":
                 xy = xc, endpt
-            elif position == "edge" and orientation == "horizontal":
+            elif label_type == "edge" and orientation == "horizontal":
                 xy = endpt, yc
 
             if orientation == "vertical":
-                xytext = shifting, sign(extrema) * padding
+                xytext = 0, sign(extrema) * padding
             else:
-                xytext = sign(extrema) * padding, shifting
+                xytext = sign(extrema) * padding, 0
 
-            if position == "center":
+            if label_type == "center":
                 ha, va = "center", "center"
-            elif position == "edge" and orientation == "vertical" and yc >= 0:
-                ha, va = "center", "bottom"
-            elif position == "edge" and orientation == "vertical" and yc < 0:
-                ha, va = "center", "top"
-            elif (
-                position == "edge" and orientation == "horizontal" and xc >= 0
-            ):
-                ha, va = "left", "center"
-            elif position == "edge" and orientation == "horizontal" and xc < 0:
-                ha, va = "right", "center"
+            elif label_type == "edge":
+                if orientation == "vertical" and yc >= 0:
+                    ha, va = "center", "bottom"
+                elif orientation == "vertical" and yc < 0:
+                    ha, va = "center", "top"
+                elif orientation == "horizontal" and xc >= 0:
+                    ha, va = "left", "center"
+                elif orientation == "horizontal" and xc < 0:
+                    ha, va = "right", "center"
 
             annotation = self.annotate(fmt % value if lbl is None else lbl,
                                        xy, xytext, textcoords="offset points",

lib/matplotlib/tests/test_axes.py

@@ -6814,7 +6814,7 @@ def test_bar_label_location_center():
     ax = plt.gca()
     ys, widths = [1, 2], [3, -4]
     rects = ax.barh(ys, widths)
-    labels = ax.bar_label(rects, position='center')
+    labels = ax.bar_label(rects, label_type='center')
     assert labels[0].xy == (widths[0] / 2, ys[0])
     assert labels[0].get_ha() == 'center'
     assert labels[0].get_va() == 'center'