Make eventplot use the standard alias resolution mechanism.

anntzer · anntzer · commit dbc42950671d · 2019-12-29T22:08:18.000+01:00
... or rather, prepare its move.

Right now eventplot is the sole user of local_over_kwdict for alias
resolution.  Prepare to move it towards cbook.normalize_kwargs instead.

normalize_kwargs is stricter (it raises on conflicting kwargs), so we
need a deprecation period for conficting kwargs as well.
diff --git a/doc/api/next_api_changes/deprecations.rst b/doc/api/next_api_changes/deprecations.rst
@@ -73,3 +73,12 @@ Revert deprecation \*min, \*max keyword arguments to ``set_x/y/zlim_3d()``
 These keyword arguments  were deprecated in 3.0, alongside with the respective
 parameters in ``set_xlim()`` / ``set_ylim()``. The deprecations of the 2D
 versions were already reverted in in 3.1.
+
+``cbook.local_over_kwdict``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This function is deprecated.  Use `.cbook.normalize_kwargs` instead.
+
+Passing both singular and plural *colors*, *linewidths*, *linestyles* to `.Axes.eventplot`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Passing e.g. both *linewidth* and *linewidths* will raise a TypeError in the
+future.
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -1295,9 +1295,9 @@ def eventplot(self, positions, orientation='horizontal', lineoffsets=1,
 
         # prevent 'singular' keys from **kwargs dict from overriding the effect
         # of 'plural' keyword arguments (e.g. 'color' overriding 'colors')
-        colors = cbook.local_over_kwdict(colors, kwargs, 'color')
-        linewidths = cbook.local_over_kwdict(linewidths, kwargs, 'linewidth')
-        linestyles = cbook.local_over_kwdict(linestyles, kwargs, 'linestyle')
+        colors = cbook._local_over_kwdict(colors, kwargs, 'color')
+        linewidths = cbook._local_over_kwdict(linewidths, kwargs, 'linewidth')
+        linestyles = cbook._local_over_kwdict(linestyles, kwargs, 'linestyle')
 
         if not np.iterable(lineoffsets):
             lineoffsets = [lineoffsets]
diff --git a/lib/matplotlib/cbook/__init__.py b/lib/matplotlib/cbook/__init__.py
@@ -279,6 +279,7 @@ def __setstate__(self, state):
         self.extend(state['seq'])
 
 
+@deprecated("3.3")
 class IgnoredKeywordWarning(UserWarning):
     """
     A class for issuing warnings about keyword arguments that will be ignored
@@ -287,6 +288,7 @@ class IgnoredKeywordWarning(UserWarning):
     pass
 
 
+@deprecated("3.3", alternative="normalize_kwargs")
 def local_over_kwdict(local_var, kwargs, *keys):
     """
     Enforces the priority of a local variable over potentially conflicting
@@ -321,8 +323,12 @@ def local_over_kwdict(local_var, kwargs, *keys):
     IgnoredKeywordWarning
         For each key in keys that is removed from kwargs but not used as
         the output value.
-
     """
+    return _local_over_kwdict(local_var, kwargs, *keys, IgnoredKeywordWarning)
+
+
+def _local_over_kwdict(
+        local_var, kwargs, *keys, warning_cls=MatplotlibDeprecationWarning):
     out = local_var
     for key in keys:
         kwarg_val = kwargs.pop(key, None)
@@ -331,7 +337,7 @@ def local_over_kwdict(local_var, kwargs, *keys):
                 out = kwarg_val
             else:
                 _warn_external('"%s" keyword argument will be ignored' % key,
-                               IgnoredKeywordWarning)
+                               warning_cls)
     return out
 
 
diff --git a/lib/matplotlib/tests/test_axes.py b/lib/matplotlib/tests/test_axes.py
@@ -28,8 +28,7 @@
 from numpy.testing import (
     assert_allclose, assert_array_equal, assert_array_almost_equal)
 from matplotlib import rc_context
-from matplotlib.cbook import (
-    IgnoredKeywordWarning, MatplotlibDeprecationWarning)
+from matplotlib.cbook import MatplotlibDeprecationWarning
 
 # Note: Some test cases are run twice: once normally and once with labeled data
 #       These two must be defined in the same test function or need to have
@@ -3661,7 +3660,7 @@ def test_eventplot_colors(colors):
 
 
 @image_comparison(['test_eventplot_problem_kwargs.png'], remove_text=True)
-def test_eventplot_problem_kwargs():
+def test_eventplot_problem_kwargs(recwarn):
     '''
     test that 'singular' versions of LineCollection props raise an
     IgnoredKeywordWarning rather than overriding the 'plural' versions (e.g.
@@ -3676,19 +3675,18 @@ def test_eventplot_problem_kwargs():
     fig = plt.figure()
     axobj = fig.add_subplot(111)
 
-    with warnings.catch_warnings(record=True) as w:
-        warnings.simplefilter("always")
-        axobj.eventplot(data,
-                        colors=['r', 'b'],
-                        color=['c', 'm'],
-                        linewidths=[2, 1],
-                        linewidth=[1, 2],
-                        linestyles=['solid', 'dashed'],
-                        linestyle=['dashdot', 'dotted'])
-
-        # check that three IgnoredKeywordWarnings were raised
-        assert len(w) == 3
-        assert all(issubclass(wi.category, IgnoredKeywordWarning) for wi in w)
+    axobj.eventplot(data,
+                    colors=['r', 'b'],
+                    color=['c', 'm'],
+                    linewidths=[2, 1],
+                    linewidth=[1, 2],
+                    linestyles=['solid', 'dashed'],
+                    linestyle=['dashdot', 'dotted'])
+
+    # check that three IgnoredKeywordWarnings were raised
+    assert len(recwarn) == 3
+    assert all(issubclass(wi.category, MatplotlibDeprecationWarning)
+               for wi in recwarn)
 
 
 def test_empty_eventplot():
