Deprecate parameter props of Shadow

timhoffm · timhoffm · commit f7ff8dc659e4 · 2020-02-15T19:23:16.000+01:00
diff --git a/doc/api/next_api_changes/deprecations.rst b/doc/api/next_api_changes/deprecations.rst
@@ -211,3 +211,8 @@ The *clear_temp* parameter and attribute of `.FileMovieWriter` is
 deprecated.  In the future, files placed in a temporary directory (using
 ``frame_prefix=None``, the default) will be cleared; files placed elsewhere
 will not.
+
+Passing *props* to `.Shadow`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The parameter *props* of `.Shadow` is deprecated. Use keyword arguments
+instead.
diff --git a/examples/text_labels_and_annotations/demo_text_path.py b/examples/text_labels_and_annotations/demo_text_path.py
@@ -116,8 +116,8 @@ def draw(self, renderer=None):
     text_patch = PathClippedImagePatch(text_path, arr, ec="none",
                                        transform=IdentityTransform())
 
-    shadow1 = Shadow(text_patch, 1, -1, props=dict(fc="none", ec="0.6", lw=3))
-    shadow2 = Shadow(text_patch, 1, -1, props=dict(fc="0.3", ec="none"))
+    shadow1 = Shadow(text_patch, 1, -1, fc="none", ec="0.6", lw=3)
+    shadow2 = Shadow(text_patch, 1, -1, fc="0.3", ec="none")
 
     # make offset box
     offsetbox = AuxTransformBox(IdentityTransform())
diff --git a/lib/matplotlib/patches.py b/lib/matplotlib/patches.py
@@ -627,33 +627,51 @@ class Shadow(Patch):
     def __str__(self):
         return "Shadow(%s)" % (str(self.patch))
 
+    @cbook._delete_parameter("3.3", "props")
     @docstring.dedent_interpd
     def __init__(self, patch, ox, oy, props=None, **kwargs):
         """
-        Create a shadow of the given *patch* offset by *ox*, *oy*.
-        *props*, if not *None*, is a patch property update dictionary.
-        If *None*, the shadow will have have the same color as the face,
+        Create a shadow of the given *patch*.
+
+        By default, the shadow will have the same face color as the *patch*,
         but darkened.
 
-        Valid keyword arguments are:
+        Parameters
+        ----------
+        patch : `.Patch`
+            The patch to create the shadow for.
+        ox, oy : float
+            The shift of the shadow in data coordinates, scaled by a factor
+            of dpi/72.
+        props : dict
+            *deprecated (use kwargs instead)* Properties of the shadow patch.
+        **kwargs
+            Properties of the shadow patch. Supported keys are:
 
-        %(Patch)s
+            %(Patch)s
         """
         Patch.__init__(self)
         self.patch = patch
-        self.props = props
+        # Note: when removing props, we can directly pass kwargs to _update()
+        # and remove self._props
+        self._props = {**(props if props is not None else {}), **kwargs}
         self._ox, self._oy = ox, oy
         self._shadow_transform = transforms.Affine2D()
         self._update()
 
+    @cbook.deprecated("3.3")
+    @property
+    def props(self):
+        return self._props
+
     def _update(self):
         self.update_from(self.patch)
 
         # Place the shadow patch directly behind the inherited patch.
         self.set_zorder(np.nextafter(self.patch.zorder, -np.inf))
 
-        if self.props is not None:
-            self.update(self.props)
+        if self._props:
+            self.update(self._props)
         else:
             color = .3 * np.asarray(colors.to_rgb(self.patch.get_facecolor()))
             self.set_facecolor(color)
