Merge pull request #14014 from timhoffm/pyplot-subplot-figure

dstansby · web-flow · commit 0f37d4f6f198 · 2019-05-28T23:25:28.000+01:00
Disallow figure argument for pyplot.subplot() and Figure.add_subplot()
diff --git a/doc/api/next_api_changes/2019-04-23-TH.rst b/doc/api/next_api_changes/2019-04-23-TH.rst
@@ -0,0 +1,6 @@
+API changes
+```````````
+
+`.Figure.add_subplot()` and `.pyplot.subplot()` do not accept a `figure`
+keyword argument anymore. It only used to work anyway if the passed figure
+was ``self`` or the current figure, respectively.
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -1307,9 +1307,9 @@ def add_subplot(self, *args, **kwargs):
         Other Parameters
         ----------------
         **kwargs
-            This method also takes the keyword arguments for
-            the returned axes base class. The keyword arguments for the
-            rectilinear base class `~.axes.Axes` can be found in
+            This method also takes the keyword arguments for the returned axes
+            base class; except for the *figure* argument. The keyword arguments
+            for the rectilinear base class `~.axes.Axes` can be found in
             the following table but there might also be other keyword
             arguments if another projection is used.
 
@@ -1378,6 +1378,12 @@ def add_subplot(self, *args, **kwargs):
                                  "three-digit number, not {}".format(args[0]))
             args = tuple(map(int, str(args[0])))
 
+        if 'figure' in kwargs:
+            # Axes itself allows for a 'figure' kwarg, but since we want to
+            # bind the created Axes to self, it is not allowed here.
+            raise TypeError(
+                "add_subplot() got an unexpected keyword argument 'figure'")
+
         if isinstance(args[0], SubplotBase):
 
             a = args[0]
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -929,9 +929,9 @@ def subplot(*args, **kwargs):
     Other Parameters
     ----------------
     **kwargs
-        This method also takes the keyword arguments for
-        the returned axes base class. The keyword arguments for the
-        rectilinear base class `~.axes.Axes` can be found in
+        This method also takes the keyword arguments for the returned axes
+        base class; except for the *figure* argument. The keyword arguments
+        for the rectilinear base class `~.axes.Axes` can be found in
         the following table but there might also be other keyword
         arguments if another projection is used.
 
