ENH: Support Figure.add_axes() without parameters

Author: timhoffm

doc/release/next_whats_new/add_axes.rst

@@ -0,0 +1,7 @@
+``Figure.add_axes()`` without parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+`.Figure.add_axes` can now be called without parameters to add a full-figure
+`~.axes.Axes`. This is equivalent to calling ``fig.add_subplot()`` without
+parameters. This also creates the same Axes as ``fig, ax = plt.subplots()``
+does.

lib/matplotlib/figure.py

@@ -535,9 +535,20 @@ def add_axes(self, *args, **kwargs):
 
         Call signatures::
 
+            add_axes()
             add_axes(rect, projection=None, polar=False, **kwargs)
             add_axes(ax)
 
+        Without parameters a "standard" Axes is created that fills the figure.
+        ``fig = plt.figure(), ax = fig.add_axes()`` is equivalent to
+        ``fig, ax = plt.subplots()``.
+
+        If a *rect* tuple is passed, a new Axes is created at the given figure
+        coordinates.
+
+        Passing an existing `~.axes.Axes` instance *ax* adds it to the figure.
+        This is only for rare use cases. See the notes section below.
+
         Parameters
         ----------
         rect : tuple (left, bottom, width, height)
@@ -613,19 +624,21 @@ def add_axes(self, *args, **kwargs):
             fig.delaxes(ax)
             fig.add_axes(ax)
         """
-
-        if not len(args) and 'rect' not in kwargs:
-            raise TypeError("add_axes() missing 1 required positional argument: 'rect'")
-        elif 'rect' in kwargs:
+        if 'rect' in kwargs:
+            # handle add_axes(rect=[...]) as add_axes([...])
             if len(args):
                 raise TypeError("add_axes() got multiple values for argument 'rect'")
             args = (kwargs.pop('rect'), )
-        if len(args) != 1:
-            raise _api.nargs_error("add_axes", 1, len(args))
+
+        if len(args) > 1:
+            raise _api.nargs_error("add_axes", "0 or 1", len(args))
+
+        if not args:
+            return self.add_subplot()
 
         if isinstance(args[0], Axes):
             a, = args
-            key = a._projection_init
+            key = a._projection_initxes
             if a.get_figure(root=False) is not self:
                 raise ValueError(
                     "The Axes must have been created in the present figure")
@@ -648,10 +661,10 @@ def add_subplot(self, *args, **kwargs):
 
         Call signatures::
 
+           add_subplot()
            add_subplot(nrows, ncols, index, **kwargs)
            add_subplot(pos, **kwargs)
            add_subplot(ax)
-           add_subplot()
 
         Parameters
         ----------

lib/matplotlib/tests/test_figure.py

@@ -10,6 +10,7 @@
 import numpy as np
 import pytest
 from PIL import Image
+from numpy.ma.testutils import assert_array_equal
 
 import matplotlib as mpl
 from matplotlib import gridspec
@@ -534,6 +535,12 @@ def test_invalid_figure_size(width, height):
         fig.set_size_inches(width, height)
 
 
+def test_add_axes():
+    fig, ax = plt.subplots()
+    ax2 = plt.figure(2).add_axes()
+    assert_array_equal(ax2.get_position().get_points(), ax.get_position().get_points())
+
+
 def test_invalid_figure_add_axes():
     fig = plt.figure()
     with pytest.raises(TypeError,