Very soft-deprecate AxesDivider.new_{horizontal,vertical}.

anntzer · anntzer · commit 6447c953f303 · 2021-10-21T00:55:52.000+02:00
`append_axes` is a more general API which is basically just as
ergonomic, and avoids exposing the slightly unusual feature of
axes_grid having indices increasing towards the top for vertical
stacks (contrary to gridspec which goes towards the bottom), and hence
`new_vertical(append_start={True,False})` behaving in the opposite
direction as one may naively expect.

Given that `new_horizontal` and `new_vertical` would basically stay as
helpers, it seems overkill to deprecate them, but perhaps we can at
least hide them from the docs (`:meta private:`).  Also promote
`axes_class` to be a plain normal parameter.
diff --git a/doc/api/prev_api_changes/api_changes_3.5.0/behaviour.rst b/doc/api/prev_api_changes/api_changes_3.5.0/behaviour.rst
@@ -242,6 +242,6 @@ location of values that lie between two levels.
 ``AxesDivider`` now defaults to rcParams-specified pads
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-`.AxesDivider.append_axes`, `.AxesDivider.new_horizontal`, and
-`.AxesDivider.new_vertical` now default to paddings specified by
+`.AxesDivider.append_axes`, ``AxesDivider.new_horizontal``, and
+``AxesDivider.new_vertical`` now default to paddings specified by
 :rc:`figure.subplot.wspace` and :rc:`figure.subplot.hspace` rather than zero.
diff --git a/examples/axes_grid1/demo_axes_divider.py b/examples/axes_grid1/demo_axes_divider.py
@@ -68,7 +68,7 @@ def demo_locatable_axes_easy(ax):
 
     divider = make_axes_locatable(ax)
 
-    ax_cb = divider.new_horizontal(size="5%", pad=0.05)
+    ax_cb = divider.append_axes("right", size="5%", pad=0.05)
     fig = ax.get_figure()
     fig.add_axes(ax_cb)
 
@@ -86,7 +86,7 @@ def demo_images_side_by_side(ax):
     divider = make_axes_locatable(ax)
 
     Z, extent = get_demo_image()
-    ax2 = divider.new_horizontal(size="100%", pad=0.05)
+    ax2 = divider.append_axes("right", size="100%", pad=0.05)
     fig1 = ax.get_figure()
     fig1.add_axes(ax2)
 
diff --git a/examples/axes_grid1/make_room_for_ylabel_using_axesgrid.py b/examples/axes_grid1/make_room_for_ylabel_using_axesgrid.py
@@ -40,7 +40,7 @@
 ax1 = plt.axes([0, 0, 1, 1])
 divider = make_axes_locatable(ax1)
 
-ax2 = divider.new_horizontal("100%", pad=0.3, sharey=ax1)
+ax2 = divider.append_axes("right", "100%", pad=0.3, sharey=ax1)
 ax2.tick_params(labelleft=False)
 fig.add_axes(ax2)
 
diff --git a/lib/mpl_toolkits/axes_grid1/axes_divider.py b/lib/mpl_toolkits/axes_grid1/axes_divider.py
@@ -442,26 +442,11 @@ def _get_new_axes(self, *, axes_class=None, **kwargs):
 
     def new_horizontal(self, size, pad=None, pack_start=False, **kwargs):
         """
-        Add a new axes on the right (or left) side of the main axes.
+        Helper method for ``append_axes("left")`` and ``append_axes("right")``.
 
-        Parameters
-        ----------
-        size : :mod:`~mpl_toolkits.axes_grid1.axes_size` or float or str
-            The axes width.  float or str arguments are interpreted as
-            ``axes_size.from_any(size, AxesX(<main_axes>))``.
-        pad : :mod:`~mpl_toolkits.axes_grid1.axes_size` or float or str
-            Padding between the axes.  float or str arguments are interpreted
-            as ``axes_size.from_any(size, AxesX(<main_axes>))``.  Defaults to
-            :rc:`figure.subplot.wspace` times the main axes width.
-        pack_start : bool
-            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
-            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.
+        See the documentation of `append_axes` for more details.
+
+        :meta private:
         """
         if pad is None:
             pad = mpl.rcParams["figure.subplot.wspace"] * self._xref
@@ -489,26 +474,11 @@ def new_horizontal(self, size, pad=None, pack_start=False, **kwargs):
 
     def new_vertical(self, size, pad=None, pack_start=False, **kwargs):
         """
-        Add a new axes on the top (or bottom) side of the main axes.
+        Helper method for ``append_axes("top")`` and ``append_axes("bottom")``.
 
-        Parameters
-        ----------
-        size : :mod:`~mpl_toolkits.axes_grid1.axes_size` or float or str
-            The axes height.  float or str arguments are interpreted as
-            ``axes_size.from_any(size, AxesY(<main_axes>))``.
-        pad : :mod:`~mpl_toolkits.axes_grid1.axes_size` or float or str
-            Padding between the axes.  float or str arguments are interpreted
-            as ``axes_size.from_any(size, AxesY(<main_axes>))``.  Defaults to
-            :rc:`figure.subplot.hspace` times the main axes height.
-        pack_start : bool
-            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
-            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.
+        See the documentation of `append_axes` for more details.
+
+        :meta private:
         """
         if pad is None:
             pad = mpl.rcParams["figure.subplot.hspace"] * self._yref
@@ -529,31 +499,47 @@ def new_vertical(self, size, pad=None, pack_start=False, **kwargs):
         else:
             self._vertical.append(size)
             locator = self.new_locator(
-                nx=self._xrefindex, ny=len(self._vertical)-1)
+                nx=self._xrefindex, ny=len(self._vertical) - 1)
         ax = self._get_new_axes(**kwargs)
         ax.set_axes_locator(locator)
         return ax
 
     @_api.delete_parameter("3.5", "add_to_figure", alternative="ax.remove()")
-    def append_axes(self, position, size, pad=None, add_to_figure=True,
-                    **kwargs):
+    def append_axes(self, position, size, pad=None, add_to_figure=True, *,
+                    axes_class=None, **kwargs):
         """
-        Create an axes at the given *position* with the same height
-        (or width) of the main axes.
-
-         *position*
-           ["left"|"right"|"bottom"|"top"]
+        Add a new axes on a given side of the main axes.
 
-         *size* and *pad* should be axes_grid.axes_size compatible.
+        Parameters
+        ----------
+        position : {"left", "right", "bottom", "top"}
+            Where the new axes is positioned relative to the main axes.
+        size : :mod:`~mpl_toolkits.axes_grid1.axes_size` or float or str
+            The axes width or height.  float or str arguments are interpreted
+            as ``axes_size.from_any(size, AxesX(<main_axes>))`` for left or
+            right axes, and likewise with ``AxesY`` for bottom or top axes.
+        pad : :mod:`~mpl_toolkits.axes_grid1.axes_size` or float or str
+            Padding between the axes.  float or str arguments are interpreted
+            as for *size*.  Defaults to :rc:`figure.subplot.wspace` times the
+            main axes width (left or right axes) or :rc:`figure.subplot.hspace`
+            times the main axes height (bottom or top axes).
+        axes_class : subclass type of `~.axes.Axes`, optional
+            The type of the new axes.  Defaults to the type of the main axes.
+        **kwargs
+            All extra keywords arguments are passed to the created axes.
         """
         if position == "left":
-            ax = self.new_horizontal(size, pad, pack_start=True, **kwargs)
+            ax = self.new_horizontal(
+                size, pad, pack_start=True, axes_class=axes_class, **kwargs)
         elif position == "right":
-            ax = self.new_horizontal(size, pad, pack_start=False, **kwargs)
+            ax = self.new_horizontal(
+                size, pad, pack_start=False, axes_class=axes_class, **kwargs)
         elif position == "bottom":
-            ax = self.new_vertical(size, pad, pack_start=True, **kwargs)
+            ax = self.new_vertical(
+                size, pad, pack_start=True, axes_class=axes_class, **kwargs)
         elif position == "top":
-            ax = self.new_vertical(size, pad, pack_start=False, **kwargs)
+            ax = self.new_vertical(
+                size, pad, pack_start=False, axes_class=axes_class, **kwargs)
         else:
             _api.check_in_list(["left", "right", "bottom", "top"],
                                position=position)
