Merge pull request matplotlib#23690 from stefmolin/bar-label-fmt

Add new-style string formatting option and callable option to `fmt` in `Axes.bar_label()`.

Author: jklymak

doc/users/next_whats_new/bar_label_formatting.rst

@@ -0,0 +1,31 @@
+Additional format string options in `~matplotlib.axes.Axes.bar_label`
+---------------------------------------------------------------------
+
+The ``fmt`` argument of `~matplotlib.axes.Axes.bar_label` now accepts
+{}-style format strings:
+
+.. code-block:: python
+
+    import matplotlib.pyplot as plt
+
+    fruit_names = ['Coffee', 'Salted Caramel', 'Pistachio']
+    fruit_counts = [4000, 2000, 7000]
+
+    fig, ax = plt.subplots()
+    bar_container = ax.bar(fruit_names, fruit_counts)
+    ax.set(ylabel='pints sold', title='Gelato sales by flavor', ylim=(0, 8000))
+    ax.bar_label(bar_container, fmt='{:,.0f}')
+
+It also accepts callables:
+
+.. code-block:: python
+
+    animal_names = ['Lion', 'Gazelle', 'Cheetah']
+    mph_speed = [50, 60, 75]
+
+    fig, ax = plt.subplots()
+    bar_container = ax.bar(animal_names, mph_speed)
+    ax.set(ylabel='speed in MPH', title='Running speeds', ylim=(0, 80))
+    ax.bar_label(
+        bar_container, fmt=lambda x: '{:.1f} km/h'.format(x * 1.61)
+    )

examples/lines_bars_and_markers/bar_label_demo.py

@@ -94,6 +94,30 @@
 
 plt.show()
 
+###############################################################################
+# Bar labels using {}-style format string
+
+fruit_names = ['Coffee', 'Salted Caramel', 'Pistachio']
+fruit_counts = [4000, 2000, 7000]
+
+fig, ax = plt.subplots()
+bar_container = ax.bar(fruit_names, fruit_counts)
+ax.set(ylabel='pints sold', title='Gelato sales by flavor', ylim=(0, 8000))
+ax.bar_label(bar_container, fmt='{:,.0f}')
+
+###############################################################################
+# Bar labels using a callable
+
+animal_names = ['Lion', 'Gazelle', 'Cheetah']
+mph_speed = [50, 60, 75]
+
+fig, ax = plt.subplots()
+bar_container = ax.bar(animal_names, mph_speed)
+ax.set(ylabel='speed in MPH', title='Running speeds', ylim=(0, 80))
+ax.bar_label(
+    bar_container, fmt=lambda x: '{:.1f} km/h'.format(x * 1.61)
+)
+
 #############################################################################
 #
 # .. admonition:: References

lib/matplotlib/axes/_axes.py

@@ -2622,8 +2622,11 @@ def bar_label(self, container, labels=None, *, fmt="%g", label_type="edge",
             A list of label texts, that should be displayed. If not given, the
             label texts will be the data values formatted with *fmt*.
 
-        fmt : str, default: '%g'
-            A format string for the label.
+        fmt : str or callable, default: '%g'
+            An unnamed %-style or {}-style format string for the label or a
+            function to call with the value as the first argument.
+            When *fmt* is a string and can be interpreted in both formats,
+            %-style takes precedence over {}-style.
 
         label_type : {'edge', 'center'}, default: 'edge'
             The label type. Possible values:
@@ -2745,7 +2748,14 @@ def sign(x):
             if np.isnan(dat):
                 lbl = ''
 
-            annotation = self.annotate(fmt % value if lbl is None else lbl,
+            if lbl is None:
+                if isinstance(fmt, str):
+                    lbl = cbook._auto_format_str(fmt, value)
+                elif callable(fmt):
+                    lbl = fmt(value)
+                else:
+                    raise TypeError("fmt must be a str or callable")
+            annotation = self.annotate(lbl,
                                        xy, xytext, textcoords="offset points",
                                        ha=ha, va=va, **kwargs)
             annotations.append(annotation)

lib/matplotlib/cbook/__init__.py

@@ -2325,3 +2325,30 @@ def _unpack_to_numpy(x):
         if isinstance(xtmp, np.ndarray):
             return xtmp
     return x
+
+
+def _auto_format_str(fmt, value):
+    """
+    Apply *value* to the format string *fmt*.
+
+    This works both with unnamed %-style formatting and
+    unnamed {}-style formatting. %-style formatting has priority.
+    If *fmt* is %-style formattable that will be used. Otherwise,
+    {}-formatting is applied. Strings without formatting placeholders
+    are passed through as is.
+
+    Examples
+    --------
+    >>> _auto_format_str('%.2f m', 0.2)
+    '0.20 m'
+    >>> _auto_format_str('{} m', 0.2)
+    '0.2 m'
+    >>> _auto_format_str('const', 0.2)
+    'const'
+    >>> _auto_format_str('%d or {}', 0.2)
+    '0 or {}'
+    """
+    try:
+        return fmt % (value,)
+    except (TypeError, ValueError):
+        return fmt.format(value)

lib/matplotlib/tests/test_axes.py

@@ -7813,14 +7813,24 @@ def test_bar_label_location_errorbars():
     assert labels[1].get_va() == 'top'
 
 
-def test_bar_label_fmt():
+@pytest.mark.parametrize('fmt', [
+    '%.2f', '{:.2f}', '{:.2f}'.format
+])
+def test_bar_label_fmt(fmt):
     ax = plt.gca()
     rects = ax.bar([1, 2], [3, -4])
-    labels = ax.bar_label(rects, fmt='%.2f')
+    labels = ax.bar_label(rects, fmt=fmt)
     assert labels[0].get_text() == '3.00'
     assert labels[1].get_text() == '-4.00'
 
 
+def test_bar_label_fmt_error():
+    ax = plt.gca()
+    rects = ax.bar([1, 2], [3, -4])
+    with pytest.raises(TypeError, match='str or callable'):
+        _ = ax.bar_label(rects, fmt=10)
+
+
 def test_bar_label_labels():
     ax = plt.gca()
     rects = ax.bar([1, 2], [3, -4])

lib/matplotlib/tests/test_cbook.py

@@ -895,3 +895,19 @@ def test_safe_first_element_with_none():
     datetime_lst[0] = None
     actual = cbook._safe_first_non_none(datetime_lst)
     assert actual is not None and actual == datetime_lst[1]
+
+
+@pytest.mark.parametrize('fmt, value, result', [
+    ('%.2f m', 0.2, '0.20 m'),
+    ('{:.2f} m', 0.2, '0.20 m'),
+    ('{} m', 0.2, '0.2 m'),
+    ('const', 0.2, 'const'),
+    ('%d or {}', 0.2, '0 or {}'),
+    ('{{{:,.0f}}}', 2e5, '{200,000}'),
+    ('{:.2%}', 2/3, '66.67%'),
+    ('$%g', 2.54, '$2.54'),
+])
+def test_auto_format_str(fmt, value, result):
+    """Apply *value* to the format string *fmt*."""
+    assert cbook._auto_format_str(fmt, value) == result
+    assert cbook._auto_format_str(fmt, np.float64(value)) == result