matplotlib
diff --git a/‎doc/api/next_api_changes/2019-04-23-TH.rst
Copy file name to clipboard
+6Lines changed: 6 additions & 0 deletions b/‎doc/api/next_api_changes/2019-04-23-TH.rst
Copy file name to clipboard
+6Lines changed: 6 additions & 0 deletions
diff --git a/‎lib/matplotlib/figure.py
Copy file name to clipboardExpand all lines: lib/matplotlib/figure.py
+9-3Lines changed: 9 additions & 3 deletions b/‎lib/matplotlib/figure.py
Copy file name to clipboardExpand all lines: lib/matplotlib/figure.py
+9-3Lines changed: 9 additions & 3 deletions
diff --git a/‎lib/matplotlib/pyplot.py
Copy file name to clipboardExpand all lines: lib/matplotlib/pyplot.py
+3-3Lines changed: 3 additions & 3 deletions b/‎lib/matplotlib/pyplot.py
Copy file name to clipboardExpand all lines: lib/matplotlib/pyplot.py
+3-3Lines changed: 3 additions & 3 deletions
@@ -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.
@@ -1301,9 +1301,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.
             %(Axes)s
@@ -1376,6 +1376,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]
 
@@ -912,9 +912,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.
         %(Axes)s