Merge pull request matplotlib#13978 from anntzer/normalize_kwargs

timhoffm · web-flow · commit 76db50151a65 · 2019-04-18T07:46:22.000+02:00
Make normalize_kwargs more convenient for third-party use.
diff --git a/doc/users/next_whats_new/2019-04-17-AL.rst b/doc/users/next_whats_new/2019-04-17-AL.rst
@@ -0,0 +1,12 @@
+`cbook.normalize_kwargs` can be used to normalize artist property names
+```````````````````````````````````````````````````````````````````````
+
+`cbook.normalize_kwargs` now presents a convenient interface to normalize
+artist properties (e.g., from "lw" to "linewidth"):
+
+>>> cbook.normalize_kwargs({"lw": 1}, Line2D)
+{"linewidth": 1}
+
+The first argument is the mapping to be normalized, and the second argument can
+be an artist class or an artist instance (it can also be a mapping in a
+specific format; see the function's docstring for details).
diff --git a/lib/matplotlib/artist.py b/lib/matplotlib/artist.py
@@ -1048,8 +1048,7 @@ def properties(self):
 
     def set(self, **kwargs):
         """A property batch setter.  Pass *kwargs* to set properties."""
-        kwargs = cbook.normalize_kwargs(
-            kwargs, getattr(type(self), "_alias_map", {}))
+        kwargs = cbook.normalize_kwargs(kwargs, self)
         props = OrderedDict(
             sorted(kwargs.items(), reverse=True,
                    key=lambda x: (self._prop_order.get(x[0], 0), x[0])))
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -1662,7 +1662,7 @@ def plot(self, *args, scalex=True, scaley=True, data=None, **kwargs):
         additionally use any  `matplotlib.colors` spec, e.g. full names
         (``'green'``) or hex strings (``'#008000'``).
         """
-        kwargs = cbook.normalize_kwargs(kwargs, mlines.Line2D._alias_map)
+        kwargs = cbook.normalize_kwargs(kwargs, mlines.Line2D)
         lines = [*self._get_lines(*args, data=data, **kwargs)]
         for line in lines:
             self.add_line(line)
@@ -2280,7 +2280,7 @@ def bar(self, x, height, width=0.8, bottom=None, *, align="center",
         %(Rectangle)s
 
         """
-        kwargs = cbook.normalize_kwargs(kwargs, mpatches.Patch._alias_map)
+        kwargs = cbook.normalize_kwargs(kwargs, mpatches.Patch)
         color = kwargs.pop('color', None)
         if color is None:
             color = self._get_patches_for_fill.get_next_color()
@@ -3188,7 +3188,7 @@ def errorbar(self, x, y, yerr=None, xerr=None,
         .. [Notes section required for data comment. See #10189.]
 
         """
-        kwargs = cbook.normalize_kwargs(kwargs, mlines.Line2D._alias_map)
+        kwargs = cbook.normalize_kwargs(kwargs, mlines.Line2D)
         # anything that comes in as 'None', drop so the default thing
         # happens down stream
         kwargs = {k: v for k, v in kwargs.items() if v is not None}
@@ -5081,7 +5081,7 @@ def fill(self, *args, data=None, **kwargs):
         two curves.
         """
         # For compatibility(!), get aliases from Line2D rather than Patch.
-        kwargs = cbook.normalize_kwargs(kwargs, mlines.Line2D._alias_map)
+        kwargs = cbook.normalize_kwargs(kwargs, mlines.Line2D)
 
         patches = []
         for poly in self._get_patches_for_fill(*args, data=data, **kwargs):
@@ -5176,8 +5176,7 @@ def fill_between(self, x, y1, y2=0, where=None, interpolate=False,
 
         """
         if not rcParams['_internal.classic_mode']:
-            kwargs = cbook.normalize_kwargs(
-                kwargs, mcoll.Collection._alias_map)
+            kwargs = cbook.normalize_kwargs(kwargs, mcoll.Collection)
             if not any(c in kwargs for c in ('color', 'facecolor')):
                 kwargs['facecolor'] = \
                     self._get_patches_for_fill.get_next_color()
@@ -5358,8 +5357,7 @@ def fill_betweenx(self, y, x1, x2=0, where=None,
 
         """
         if not rcParams['_internal.classic_mode']:
-            kwargs = cbook.normalize_kwargs(
-                kwargs, mcoll.Collection._alias_map)
+            kwargs = cbook.normalize_kwargs(kwargs, mcoll.Collection)
             if not any(c in kwargs for c in ('color', 'facecolor')):
                 kwargs['facecolor'] = \
                     self._get_patches_for_fill.get_next_color()
diff --git a/lib/matplotlib/cbook/__init__.py b/lib/matplotlib/cbook/__init__.py
@@ -1687,13 +1687,16 @@ def normalize_kwargs(kw, alias_mapping=None, required=(), forbidden=(),
     Parameters
     ----------
 
-    alias_mapping, dict, optional
+    alias_mapping : dict or Artist subclass or Artist instance, optional
         A mapping between a canonical name to a list of
         aliases, in order of precedence from lowest to highest.
 
         If the canonical value is not in the list it is assumed to have
         the highest priority.
 
+        If an Artist subclass or instance is passed, use its properties alias
+        mapping.
+
     required : iterable, optional
         A tuple of fields that must be in kwargs.
 
@@ -1711,11 +1714,15 @@ def normalize_kwargs(kw, alias_mapping=None, required=(), forbidden=(),
     TypeError
         To match what python raises if invalid args/kwargs are passed to
         a callable.
-
     """
+    from matplotlib.artist import Artist
+
     # deal with default value of alias_mapping
     if alias_mapping is None:
         alias_mapping = dict()
+    elif (isinstance(alias_mapping, type) and issubclass(alias_mapping, Artist)
+          or isinstance(alias_mapping, Artist)):
+        alias_mapping = getattr(alias_mapping, "_alias_map", {})
 
     # make a local so we can pop
     kw = dict(kw)
