Deprecate FancyBboxPatch(..., boxstyle="custom", bbox_transmuter=...)

anntzer · anntzer · commit b44be42463b1 · 2020-06-25T00:28:03.000+02:00
One can directly pass the custom bbox as the `boxstyle` argument,
instead of setting `boxstyle` to "custom" and passing it as the
(otherwise unused) `bbox_transmuter` argument.  This is consistent with
arrowstyles and connectionstyles.

The old API appears to date back to very early boxstyle API designs
(pre-73f34bf), where arbitrary callables were not directly supported.

In text.py one can just not pop `bbox_transmuter` from rectprops but
just pass the dict as is to FancyBboxPatch, triggering the deprecation
if and only if the key is present.
diff --git a/doc/api/api_changes_3.4/deprecations.rst b/doc/api/api_changes_3.4/deprecations.rst
@@ -1,2 +1,8 @@
 Deprecations
 ------------
+
+``FancyBboxPatch(..., boxstyle="custom", bbox_transmuter=...)``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+In order to use a custom boxsyle, directly pass it as the *boxstyle* argument
+to `.FancyBboxPatch`.  This was previously already possible, and is consistent
+with custom arrow styles and connection styles.
diff --git a/lib/matplotlib/patches.py b/lib/matplotlib/patches.py
@@ -3564,6 +3564,7 @@ def __str__(self):
         return s % (self._x, self._y, self._width, self._height)
 
     @docstring.dedent_interpd
+    @cbook._delete_parameter("3.4", "bbox_transmuter", alternative="boxstyle")
     def __init__(self, xy, width, height,
                  boxstyle="round",
                  bbox_transmuter=None,
@@ -3618,6 +3619,10 @@ def __init__(self, xy, width, height,
         self._height = height
 
         if boxstyle == "custom":
+            cbook._warn_deprecated(
+                "3.4", message="Support for boxstyle='custom' is deprecated "
+                "since %(since)s and will be removed %(removal)s; directly "
+                "pass a boxstyle instance as the boxstyle parameter instead.")
             if bbox_transmuter is None:
                 raise ValueError("bbox_transmuter argument is needed with "
                                  "custom boxstyle")
diff --git a/lib/matplotlib/text.py b/lib/matplotlib/text.py
@@ -449,20 +449,12 @@ def set_bbox(self, rectprops):
             else:
                 if pad is None:
                     pad = 0.3
-
             # boxstyle could be a callable or a string
             if isinstance(boxstyle, str) and "pad" not in boxstyle:
                 boxstyle += ",pad=%0.2f" % pad
-
-            bbox_transmuter = props.pop("bbox_transmuter", None)
-
             self._bbox_patch = FancyBboxPatch(
-                                    (0., 0.),
-                                    1., 1.,
-                                    boxstyle=boxstyle,
-                                    bbox_transmuter=bbox_transmuter,
-                                    transform=IdentityTransform(),
-                                    **props)
+                (0, 0), 1, 1,
+                boxstyle=boxstyle, transform=IdentityTransform(), **props)
         else:
             self._bbox_patch = None
 
