Prepare to change the default pad for AxesDivider.append_axes.

anntzer · anntzer · commit c4b37e58c537 · 2019-05-09T00:34:49.000+02:00
Using a nonzero default (configurable from the rcParams and identical to
what `plt.subplots()` use) should make this method a bit more
user-friendly (note that *none* of the uses of `append_axes` throughout
the codebase leaves `pad` to its current default of zero).
diff --git a/doc/api/next_api_changes/2019-05-08-AL.rst b/doc/api/next_api_changes/2019-05-08-AL.rst
@@ -0,0 +1,9 @@
+Deprecations
+````````````
+
+Passing a ``pad`` size of ``None`` (the default) as a synonym for zero to
+the ``append_axes``, ``new_horizontal`` and ``new_vertical`` methods of
+`.axes_grid1.axes_divider.AxesDivider` is deprecated.  In a future release, the
+default value of ``None`` will mean "use :rc:`figure.subplot.wspace` or
+:rc:`figure.subplot.hspace`" (depending on the orientation).  Explicitly pass
+``pad=0`` to keep the old behavior.
diff --git a/lib/mpl_toolkits/axes_grid1/axes_divider.py b/lib/mpl_toolkits/axes_grid1/axes_divider.py
@@ -530,12 +530,17 @@ def new_horizontal(self, size, pad=None, pack_start=False, **kwargs):
             If False, the new axes is appended at the end
             of the list, i.e., it became the right-most axes. If True, it is
             inserted at the start of the list, and becomes the left-most axes.
-        kwargs
+        **kwargs
             All extra keywords arguments are passed to the created axes.
             If *axes_class* is given, the new axes will be created as an
             instance of the given class. Otherwise, the same class of the
             main axes will be used.
         """
+        if pad is None:
+            cbook.warn_deprecated(
+                "3.2", message="In a future version, 'pad' will default to "
+                "rcParams['figure.subplot.wspace'].  Set pad=0 to keep the "
+                "old behavior.)
         if pad:
             if not isinstance(pad, Size._Base):
                 pad = Size.from_any(pad, fraction_ref=self._xref)
@@ -574,12 +579,17 @@ def new_vertical(self, size, pad=None, pack_start=False, **kwargs):
             If False, the new axes is appended at the end
             of the list, i.e., it became the right-most axes. If True, it is
             inserted at the start of the list, and becomes the left-most axes.
-        kwargs
+        **kwargs
             All extra keywords arguments are passed to the created axes.
             If *axes_class* is given, the new axes will be created as an
             instance of the given class. Otherwise, the same class of the
             main axes will be used.
         """
+        if pad is None:
+            cbook.warn_deprecated(
+                "3.2", message="In a future version, 'pad' will default to "
+                "rcParams['figure.subplot.hspace'].  Set pad=0 to keep the "
+                "old behavior.)
         if pad:
             if not isinstance(pad, Size._Base):
                 pad = Size.from_any(pad, fraction_ref=self._yref)
