MNT: Restore and deprecate auto-adding Axes3D to figure on init

tacaswell · jklymak · QuLogic · tacaswell · commit 668cecc0a9f7 · 2021-02-17T23:06:49.000-05:00
Only warn when directly created by the user, not via our machinery. Closes #18939 Co-authored-by: Jody Klymak <jklymak@gmail.com> Co-authored-by: Elliott Sales de Andrade <quantum.analyst@gmail.com>
diff --git a/doc/api/next_api_changes/behavior/18564-AL.rst b/doc/api/next_api_changes/behavior/18564-AL.rst
@@ -1,8 +1,25 @@
-Axes3D no longer adds itself to figure
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-New `.Axes3D` objects previously added themselves to figures when they were
-created, which lead to them being added twice if
-``fig.add_subplot(111, projection='3d')`` was called.  Now ``ax = Axes3d(fig)``
-will need to be explicitly added to the figure with ``fig.add_axes(ax)``, as
-also needs to be done for normal `.axes.Axes`.
+Axes3D automatically adding self to Figure is deprecated
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+New `.Axes3D` objects previously added themselves to figures when they
+were created, unlike all other Axes classes, which lead to them being
+added twice if ``fig.add_subplot(111, projection='3d')`` was called.
+
+This behavior is now deprecated and will warn.  The new keyword argument
+*auto_add_to_figure* controls the behavior and can be used to suppress the
+warning.  The default value will change to False in mpl3.5, and any
+non-False value will be an error in mpl3.6.
+
+In the future, `.Axes3D` will need to be explicitly added to the
+figure ::
+
+  fig = Figure()
+  # create Axes3D
+  ax = Axes3d(fig)
+  # add to Figure
+  fig.add_axes(ax)
+
+as needs to be done for other `.axes.Axes` sub-classes. Or, a 3-d 
+projection can be made via::
+
+    fig.add_subplot(projection='3d')
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -1517,7 +1517,8 @@ def _process_projection_requirements(
                 raise TypeError(
                     f"projection must be a string, None or implement a "
                     f"_as_mpl_axes method, not {projection!r}")
-
+        if projection_class.__name__ == 'Axes3D':
+            kwargs.setdefault('auto_add_to_figure', False)
         return projection_class, kwargs
 
     def get_default_bbox_extra_artists(self):
diff --git a/lib/mpl_toolkits/mplot3d/axes3d.py b/lib/mpl_toolkits/mplot3d/axes3d.py
@@ -64,6 +64,15 @@ def __init__(
             Other axes to share z-limits with.
         proj_type : {'persp', 'ortho'}
             The projection type, default 'persp'.
+        auto_add_to_figure : bool, default: True
+            Prior to Matplotlib 3.4 Axes3D would add themselves
+            to their host Figure on init.  Other Axes class do not
+            do this.
+
+            This behavior is deprecated in 3.4, the default will
+            change to False in 3.5.  The keyword will be undocumented
+            and a non-False value will be an error in 3.6.
+
         **kwargs
             Other optional keyword arguments:
 
@@ -97,6 +106,8 @@ def __init__(
             self._shared_z_axes.join(self, sharez)
             self._adjustable = 'datalim'
 
+        auto_add_to_figure = kwargs.pop('auto_add_to_figure', True)
+
         super().__init__(
             fig, rect, frameon=True, box_aspect=box_aspect, *args, **kwargs
         )
@@ -129,6 +140,18 @@ def __init__(
         # for bounding box calculations
         self.spines[:].set_visible(False)
 
+        if auto_add_to_figure:
+            _api.warn_deprecated(
+                "3.4", removal="3.6", message="Axes3D(fig) adding itself "
+                "to the figure is deprecated since %(since)s. "
+                "Pass the keyword argument auto_add_to_figure=False "
+                "and use fig.add_axes(ax) to suppress this warning. "
+                "The default value of auto_add_to_figure will change to "
+                "False in mpl3.5 and True values will "
+                "no longer work %(removal)s.  This is consistent with "
+                "other Axes classes.")
+            fig.add_axes(self)
+
     def set_axis_off(self):
         self._axis3don = False
         self.stale = True
