Deprecate CbarAxesBase.toggle_label.

It's a completely ad-hoc API which exists nowhere else, and can be
easily replaced by more standard calls.  (Perhaps there should be a
generic way for a colorbar to toggle its ticklabels without knowing
the side on which they are, but that's another question, and it would
probably not be spelled toggle_labels.)

Author: anntzer

doc/api/next_api_changes/deprecations/25889-AL.rst

@@ -0,0 +1,4 @@
+``CbarAxesBase.toggle_label``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+... is deprecated.  Instead, use standard methods for manipulating colorbar
+labels (`.Colorbar.set_label`) and tick labels (`.Axes.tick_params`).

galleries/examples/axes_grid1/demo_axes_grid.py

@@ -36,7 +36,7 @@
     im = ax.imshow(Z, extent=extent)
 grid.cbar_axes[0].colorbar(im)
 for cax in grid.cbar_axes:
-    cax.toggle_label(False)
+    cax.tick_params(labeltop=False)
 # This affects all axes as share_all = True.
 grid.axes_llc.set(xticks=[-2, 0, 2], yticks=[-2, 0, 2])
 
@@ -49,7 +49,7 @@
 for ax, cax in zip(grid, grid.cbar_axes):
     im = ax.imshow(Z, extent=extent)
     cax.colorbar(im)
-    cax.toggle_label(False)
+    cax.tick_params(labeltop=False)
 # This affects all axes as share_all = True.
 grid.axes_llc.set(xticks=[-2, 0, 2], yticks=[-2, 0, 2])
 

lib/mpl_toolkits/axes_grid1/axes_grid.py

@@ -26,6 +26,7 @@ def colorbar(self, mappable, **kwargs):
         return self.figure.colorbar(
             mappable, cax=self, location=self.orientation, **kwargs)
 
+    @_api.deprecated("3.8", alternative="ax.tick_params and colorbar.set_label")
     def toggle_label(self, b):
         axis = self.axis[self.orientation]
         axis.toggle(ticklabels=b, label=b)