named bar_label, add arg-validation, tests and whats_new

Author: immaxchen

doc/users/next_whats_new/2019-11-06_auto-labeling-for-bar-charts.rst

@@ -0,0 +1,7 @@
+:orphan:
+
+Bar charts auto-labeling
+------------------------
+A new `.Axes.bar_label` method has been added for auto-labeling bar charts.
+See :doc:`/gallery/lines_bars_and_markers/bar_label_demo` for examples.
+

examples/lines_bars_and_markers/bar_label_demo.py

@@ -3,12 +3,12 @@
 Bar Label Demo
 ==============
 
-This example shows how to use `blabel` helper function
+This example shows how to use `bar_label` helper function
 to create bar chart labels.
 
-See also the :doc:`grouped bar chart
+See also the :doc:`grouped bar
 </gallery/lines_bars_and_markers/barchart>`,
-:doc:`stacked bar graph
+:doc:`stacked bar
 </gallery/lines_bars_and_markers/bar_stacked>` and
 :doc:`horizontal bar chart
 </gallery/lines_bars_and_markers/barh>` examples.
@@ -44,8 +44,8 @@
 ax1.legend()
 
 # Basic labels
-ax1.blabel(rects1)
-ax1.blabel(rects2)
+ax1.bar_label(rects1)
+ax1.bar_label(rects2)
 
 plt.show()
 
@@ -65,9 +65,9 @@
 ax2.legend()
 
 # Label with 'center' mode instead of the default 'edge' mode
-ax2.blabel(p1, mode='center')
-ax2.blabel(p2, mode='center')
-ax2.blabel(p2)
+ax2.bar_label(p1, mode='center')
+ax2.bar_label(p2, mode='center')
+ax2.bar_label(p2)
 
 plt.show()
 
@@ -93,7 +93,7 @@
 ax3.set_title('How fast do you want to go today?')
 
 # Label with specially formatted floats
-ax3.blabel(hbars1, fmt='%.2f')
+ax3.bar_label(hbars1, fmt='%.2f')
 
 plt.show()
 
@@ -113,8 +113,8 @@
 arrowprops = dict(color='b', arrowstyle="-|>",
                   connectionstyle="angle,angleA=0,angleB=90,rad=20")
 
-ax4.blabel(hbars2, captions=['±%.2f' % e for e in error],
-           padding=30, shifting=20, arrowprops=arrowprops, color='b')
+ax4.bar_label(hbars2, captions=['±%.2f' % e for e in error],
+              padding=30, shifting=20, arrowprops=arrowprops, color='b')
 
 plt.show()
 
@@ -132,5 +132,5 @@
 matplotlib.pyplot.bar
 matplotlib.axes.Axes.barh
 matplotlib.pyplot.barh
-matplotlib.axes.Axes.blabel
-matplotlib.pyplot.blabel
+matplotlib.axes.Axes.bar_label
+matplotlib.pyplot.bar_label

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 blabel(self, container, captions=[], fmt="%g", mode="edge",
-               padding=None, shifting=0, autoscale=True, **kwargs):
+    def bar_label(self, container, captions=[], fmt="%g", mode="edge",
+                  padding=None, shifting=0, autoscale=True, **kwargs):
         """
         Label a bar plot.
 
@@ -2543,6 +2543,7 @@ def nonefill(a, n):
         def sign(x):
             return 1 if x >= 0 else -1
 
+        cbook._check_in_list(['edge', 'center'], mode=mode)
         if mode == "edge":
             padding = padding or 3
         elif mode == "center":

lib/matplotlib/tests/test_axes.py

@@ -6782,3 +6782,58 @@ def test_ylabel_ha_with_position(ha):
     ax.set_ylabel("test", y=1, ha=ha)
     ax.yaxis.set_label_position("right")
     assert ax.yaxis.get_label().get_ha() == ha
+
+
+def test_bar_label_location_vertical():
+    ax = plt.gca()
+    xs, heights = [1, 2], [3, -4]
+    rects = ax.bar(xs, heights)
+    labels = ax.bar_label(rects)
+    assert labels[0].xy == (xs[0], heights[0])
+    assert labels[0].get_ha() == 'center'
+    assert labels[0].get_va() == 'bottom'
+    assert labels[1].xy == (xs[1], heights[1])
+    assert labels[1].get_ha() == 'center'
+    assert labels[1].get_va() == 'top'
+
+
+def test_bar_label_location_horizontal():
+    ax = plt.gca()
+    ys, widths = [1, 2], [3, -4]
+    rects = ax.barh(ys, widths)
+    labels = ax.bar_label(rects)
+    assert labels[0].xy == (widths[0], ys[0])
+    assert labels[0].get_ha() == 'left'
+    assert labels[0].get_va() == 'center'
+    assert labels[1].xy == (widths[1], ys[1])
+    assert labels[1].get_ha() == 'right'
+    assert labels[1].get_va() == 'center'
+
+
+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, mode='center')
+    assert labels[0].xy == (widths[0] / 2, ys[0])
+    assert labels[0].get_ha() == 'center'
+    assert labels[0].get_va() == 'center'
+    assert labels[1].xy == (widths[1] / 2, ys[1])
+    assert labels[1].get_ha() == 'center'
+    assert labels[1].get_va() == 'center'
+
+
+def test_bar_label_fmt():
+    ax = plt.gca()
+    rects = ax.bar([1, 2], [3, -4])
+    labels = ax.bar_label(rects, fmt='%.2f')
+    assert labels[0].get_text() == '3.00'
+    assert labels[1].get_text() == '-4.00'
+
+
+def test_bar_label_captions():
+    ax = plt.gca()
+    rects = ax.bar([1, 2], [3, -4])
+    labels = ax.bar_label(rects, captions=['A', 'B'])
+    assert labels[0].get_text() == 'A'
+    assert labels[1].get_text() == 'B'

tools/boilerplate.py

@@ -199,7 +199,7 @@ def boilerplate_gen():
         'bar',
         'barbs',
         'barh',
-        'blabel',
+        'bar_label',
         'boxplot',
         'broken_barh',
         'cla',