Fixing boilerplate and the suggested modifications in pie function

raphacosta27 · timhoffm · commit f5d869a85050 · 2020-04-17T01:17:52.000+02:00
diff --git a/doc/api/api_changes_3.3/behaviour.rst b/doc/api/api_changes_3.3/behaviour.rst
@@ -172,6 +172,12 @@ values are displayed with an appropriate number of significant digits even if
 they are much smaller or much bigger than 1.  To restore the old behavior,
 explicitly pass a "%1.2f" as the *valfmt* parameter to `.Slider`.
 
+Add *normalize*  keyword argument to ``Axes.pie``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+``pie()`` used to draw a partial pie if the sum of the values was < 1. This behavior 
+is deprecated and will change to always normalizing the values to a full pie by default. 
+If you want to draw a partial pie, please pass ``normalize=False`` explicitly.
+
 ``table.CustomCell`` is now an alias for `.table.Cell`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 All the functionality of ``CustomCell`` has been moved to its base class
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -2901,7 +2901,7 @@ def pie(self, x, explode=None, labels=None, colors=None,
             autopct=None, pctdistance=0.6, shadow=False, labeldistance=1.1,
             startangle=None, radius=None, counterclock=True,
             wedgeprops=None, textprops=None, center=(0, 0),
-            frame=False, rotatelabels=False):
+            frame=False, rotatelabels=False, *, normalize=None):
         """
         Plot a pie chart.
 
@@ -2942,6 +2942,17 @@ def pie(self, x, explode=None, labels=None, colors=None,
         shadow : bool, default: False
             Draw a shadow beneath the pie.
 
+        normalize: None or bool, default: None
+            ``pie()`` used to draw a partial pie if ``sum(x) < 1``. This
+            behavior is deprecated and will change to always normalizing the
+            values to a full pie by default. If you want to draw a partial pie,
+            please pass ``normalize=False`` explicitly.
+            When *True*, always make a full pie by normalizing x so that
+            ``sum(x) == 1``. When *False*, make a partial pie.
+            When *None*, gives the current behavior and warns if
+            ``sum(x) < 1``. Please note that passing None to this parameter is
+            deprecated.
+
         labeldistance : float or None, default: 1.1
             The radial distance at which the pie labels are drawn.
             If set to ``None``, label are not drawn, but are stored for use in
@@ -3010,9 +3021,20 @@ def pie(self, x, explode=None, labels=None, colors=None,
             raise ValueError("Wedge sizes 'x' must be non negative values")
 
         sx = x.sum()
-        if sx > 1:
-            x = x / sx
 
+        if normalize is None:
+            if sx < 1:
+                cbook.warn_deprecated(
+                    "3.1", message="normalize=None does not normalize if "
+                    "the sum is less than 1 "
+                    "but this behavior is deprecated "
+                    "since %(since)s. After the deprecation period "
+                    "the default value will be normalize=True. "
+                    "To prevent normalization pass normalize=False ")
+            else:
+                normalize = True
+        if normalize:
+            x = x / sx
         if labels is None:
             labels = [''] * len(x)
         if explode is None:
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -2650,14 +2650,14 @@ def pie(
         pctdistance=0.6, shadow=False, labeldistance=1.1,
         startangle=None, radius=None, counterclock=True,
         wedgeprops=None, textprops=None, center=(0, 0), frame=False,
-        rotatelabels=False, *, data=None):
+        rotatelabels=False, *, normalize=None, data=None):
     return gca().pie(
         x, explode=explode, labels=labels, colors=colors,
         autopct=autopct, pctdistance=pctdistance, shadow=shadow,
         labeldistance=labeldistance, startangle=startangle,
         radius=radius, counterclock=counterclock,
         wedgeprops=wedgeprops, textprops=textprops, center=center,
-        frame=frame, rotatelabels=rotatelabels,
+        frame=frame, rotatelabels=rotatelabels, normalize=normalize,
         **({"data": data} if data is not None else {}))
 
 
diff --git a/lib/matplotlib/tests/test_axes.py b/lib/matplotlib/tests/test_axes.py
@@ -6454,3 +6454,18 @@ def test_polar_interpolation_steps_variable_r(fig_test, fig_ref):
     l.get_path()._interpolation_steps = 100
     fig_ref.add_subplot(projection="polar").plot(
         np.linspace(0, np.pi/2, 101), np.linspace(1, 2, 101))
+
+
+def test_normalize_kwarg_warn_pie():
+    fig, ax = plt.subplots()
+    with pytest.warns(MatplotlibDeprecationWarning):
+        ax.pie(x=[0], normalize=None)
+
+
+def test_normalize_kwarg_pie():
+    fig, ax = plt.subplots()
+    x = [0.3, 0.3, 0.1]
+    t1 = ax.pie(x=x, normalize=True)
+    assert abs(t1[0][-1].theta2 - 360.) < 1e-3
+    t2 = ax.pie(x=x, normalize=False)
+    assert abs(t2[0][-1].theta2 - 360.) > 1e-3
