Deprecate setting the same property under two different aliases. (#12962)

anntzer · timhoffm · commit da8dea2f3fac · 2018-12-25T22:52:56.000+01:00
This will allow getting rid of the notion of alias priority, and is
consistent with Python's behavior (as explained in the changelog entry).
diff --git a/doc/api/next_api_changes/2018-12-09-AL.rst b/doc/api/next_api_changes/2018-12-09-AL.rst
@@ -0,0 +1,19 @@
+Setting the same artist property multiple time via aliases is deprecated
+````````````````````````````````````````````````````````````````````````
+
+Previously, code such as ``plt.plot([0, 1], c="red", color="blue")`` would
+emit a warning indicating that ``c`` and ``color`` are aliases of one another,
+and only keep the ``color`` kwarg.  This behavior is deprecated; in a future
+version, this will raise a TypeError, similarly to Python's behavior when a
+keyword argument is passed twice (``plt.plot([0, 1], c="red", c="blue")``).
+
+This warning is raised by `~.cbook.normalize_kwargs`.
+
+Artist.set now normalizes keywords before sorting them
+``````````````````````````````````````````````````````
+
+`Artist.set` currently sorts its keyword arguments in reverse alphabetical
+order (with a special-case to put ``color`` at the end) before applying them.
+
+It now normalizes aliases (and, as above, emits a warning on duplicate
+properties) before doing the sorting (so ``c`` goes to the end too).
diff --git a/lib/matplotlib/artist.py b/lib/matplotlib/artist.py
@@ -1064,12 +1064,12 @@ def properties(self):
         return ArtistInspector(self).properties()
 
     def set(self, **kwargs):
-        """A property batch setter. Pass *kwargs* to set properties.
-        """
+        """A property batch setter.  Pass *kwargs* to set properties."""
+        kwargs = cbook.normalize_kwargs(
+            kwargs, getattr(type(self), "_alias_map", {}))
         props = OrderedDict(
             sorted(kwargs.items(), reverse=True,
                    key=lambda x: (self._prop_order.get(x[0], 0), x[0])))
-
         return self.update(props)
 
     def findobj(self, match=None, include_self=True):
diff --git a/lib/matplotlib/cbook/__init__.py b/lib/matplotlib/cbook/__init__.py
@@ -1799,9 +1799,11 @@ def normalize_kwargs(kw, alias_mapping=None, required=(), forbidden=(),
         if tmp:
             ret[canonical] = tmp[-1]
             if len(tmp) > 1:
-                _warn_external("Saw kwargs {seen!r} which are all aliases for "
-                               "{canon!r}.  Kept value from {used!r}".format(
-                               seen=seen, canon=canonical, used=seen[-1]))
+                warn_deprecated(
+                    "3.1", message=f"Saw kwargs {seen!r} which are all "
+                    f"aliases for {canonical!r}.  Kept value from "
+                    f"{seen[-1]!r}.  Passing multiple aliases for the same "
+                    f"property will raise a TypeError %(removal)s.")
 
     # at this point we know that all keys which are aliased are removed, update
     # the return dictionary from the cleaned local copy of the input
