Unremove the normed kwarg to hist().

anntzer · anntzer · commit ec34056bb0bc · 2018-11-13T14:13:07.000+01:00
diff --git a/doc/api/next_api_changes/2018-09-18-AL-removals.rst b/doc/api/next_api_changes/2018-09-18-AL-removals.rst
@@ -20,7 +20,6 @@ Classes and methods
 
 Arguments
 ---------
-- The ``normed`` kwarg to ``Axes.hist``
 - The ``fig`` kwarg to ``GridSpec.get_subplot_params`` and
   ``GridSpecFromSubplotSpec.get_subplot_params``
 - Passing 'box-forced' to `axes.Axes.set_adjustable`
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -6324,7 +6324,8 @@ def table(self, **kwargs):
     def hist(self, x, bins=None, range=None, density=None, weights=None,
              cumulative=False, bottom=None, histtype='bar', align='mid',
              orientation='vertical', rwidth=None, log=False,
-             color=None, label=None, stacked=False, **kwargs):
+             color=None, label=None, stacked=False, normed=None,
+             **kwargs):
         """
         Plot a histogram.
 
@@ -6392,26 +6393,30 @@ def hist(self, x, bins=None, range=None, density=None, weights=None,
             number of observations. If *stacked* is also ``True``, the sum of
             the histograms is normalized to 1.
 
-            Default is ``False``.
+            Default is ``None`` for both *normed* and *density*. If either is
+            set, then that value will be used. If neither are set, then the
+            args will be treated as ``False``.
+
+            If both *density* and *normed* are set an error is raised.
 
         weights : (n, ) array_like or None, optional
-            An array of weights, of the same shape as *x*.  Each value in
-            *x* only contributes its associated weight towards the bin count
-            (instead of 1).  If *density* is ``True``, the weights are
-            normalized, so that the integral of the density over the range
-            remains 1.
+            An array of weights, of the same shape as *x*.  Each value in *x*
+            only contributes its associated weight towards the bin count
+            (instead of 1).  If *normed* or *density* is ``True``,
+            the weights are normalized, so that the integral of the density
+            over the range remains 1.
 
             Default is ``None``
 
         cumulative : bool, optional
-            If ``True``, then a histogram is computed where each bin gives
-            the counts in that bin plus all bins for smaller values. The last
-            bin gives the total number of datapoints. If *density* is also
-            ``True`` then the histogram is normalized such that the last bin
-            equals 1. If *cumulative* evaluates to less than 0 (e.g., -1), the
-            direction of accumulation is reversed.  In this case, if *density*
-            is also ``True``, then the histogram is normalized such that the
-            first bin equals 1.
+            If ``True``, then a histogram is computed where each bin gives the
+            counts in that bin plus all bins for smaller values. The last bin
+            gives the total number of datapoints. If *normed* or *density*
+            is also ``True`` then the histogram is normalized such that the
+            last bin equals 1. If *cumulative* evaluates to less than 0
+            (e.g., -1), the direction of accumulation is reversed.
+            In this case, if *normed* and/or *density* is also ``True``, then
+            the histogram is normalized such that the first bin equals 1.
 
             Default is ``False``
 
@@ -6491,15 +6496,19 @@ def hist(self, x, bins=None, range=None, density=None, weights=None,
 
             Default is ``False``
 
+        normed : bool, optional
+            Deprecated; use the density keyword argument instead.
+
         Returns
         -------
         n : array or list of arrays
-            The values of the histogram bins. See *density* and *weights* for a
-            description of the possible semantics.  If input *x* is an array,
-            then this is an array of length *nbins*. If input is a sequence of
-            arrays ``[data1, data2,..]``, then this is a list of arrays with
-            the values of the histograms for each of the arrays in the same
-            order.
+            The values of the histogram bins. See *normed* or *density*
+            and *weights* for a description of the possible semantics.
+            If input *x* is an array, then this is an array of length
+            *nbins*. If input is a sequence of arrays
+            ``[data1, data2,..]``, then this is a list of arrays with
+            the values of the histograms for each of the arrays in the
+            same order.
 
         bins : array
             The edges of the bins. Length nbins + 1 (nbins left edges and right
@@ -6548,6 +6557,15 @@ def hist(self, x, bins=None, range=None, density=None, weights=None,
         if histtype == 'barstacked' and not stacked:
             stacked = True
 
+        if density is not None and normed is not None:
+            raise ValueError("kwargs 'density' and 'normed' cannot be used "
+                             "simultaneously. "
+                             "Please only use 'density', since 'normed'"
+                             "is deprecated.")
+        if normed is not None:
+            cbook.warn_deprecated("2.1", name="'normed'", obj_type="kwarg",
+                                  alternative="'density'", removal="3.1")
+
         # basic input validation
         input_empty = np.size(x) == 0
         # Massage 'x' for processing.
@@ -6603,6 +6621,7 @@ def hist(self, x, bins=None, range=None, density=None, weights=None,
                     xmin = min(xmin, np.nanmin(xi))
                     xmax = max(xmax, np.nanmax(xi))
             bin_range = (xmin, xmax)
+        density = bool(density) or bool(normed)
         if density and not stacked:
             hist_kwargs = dict(range=bin_range, density=density)
         else:
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -2618,13 +2618,14 @@ def hist(
         x, bins=None, range=None, density=None, weights=None,
         cumulative=False, bottom=None, histtype='bar', align='mid',
         orientation='vertical', rwidth=None, log=False, color=None,
-        label=None, stacked=False, *, data=None, **kwargs):
+        label=None, stacked=False, normed=None, *, data=None,
+        **kwargs):
     return gca().hist(
         x, bins=bins, range=range, density=density, weights=weights,
         cumulative=cumulative, bottom=bottom, histtype=histtype,
         align=align, orientation=orientation, rwidth=rwidth, log=log,
-        color=color, label=label, stacked=stacked, **({"data": data} if data is
-        not None else {}), **kwargs)
+        color=color, label=label, stacked=stacked, normed=normed,
+        **({"data": data} if data is not None else {}), **kwargs)
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
diff --git a/lib/matplotlib/tests/test_axes.py b/lib/matplotlib/tests/test_axes.py
@@ -3070,7 +3070,8 @@ def test_hist_stacked_step():
     ax.hist((d1, d2), histtype="step", stacked=True)
 
 
-@image_comparison(baseline_images=['hist_stacked_normed'])
+@image_comparison(baseline_images=['hist_stacked_normed',
+                                   'hist_stacked_normed'])
 def test_hist_stacked_density():
     # make some data
     d1 = np.linspace(1, 3, 20)
@@ -3079,6 +3080,11 @@ def test_hist_stacked_density():
     fig, ax = plt.subplots()
     ax.hist((d1, d2), stacked=True, density=True)
 
+    # Also check that the old keyword works.
+    fig, ax = plt.subplots()
+    with pytest.warns(UserWarning):
+        ax.hist((d1, d2), stacked=True, normed=True)
+
 
 @pytest.mark.parametrize('normed', [False, True])
 @pytest.mark.parametrize('density', [False, True])
