Merge pull request #2055 from pelson/mappable_colorbar_attribute

mdboom · mdboom · commit 148ed82a234b · 2013-05-24T09:04:44.000-07:00
Deprecated the set_colorbar method on a scalar mappable.
diff --git a/doc/api/api_changes.rst b/doc/api/api_changes.rst
@@ -117,6 +117,14 @@ Changes in 1.3.x
   position type. Previously, it would draw the right or top spine at
   +1 data offset.
 
+* The ScalarMappable class' set_colorbar is now deprecated. Instead, the
+  :attr:`matplotlib.cm.ScalarMappable.colorbar` attribute should be used.
+  In previous matplotlib versions this attribute was an undocumented tuple
+  of ``(colorbar_instance, colorbar_axes)`` but is now just
+  ``colorbar_instance``. To get the colorbar axes it is possible to just use
+  the :attr:`~matplotlib.colorbar.ColorbarBase.ax` attribute on a colorbar
+  isntance.
+
 * In :class:`~matplotlib.patches.FancyArrow`, the default arrow head width,
   ``head_width``, has been made larger to produce a visible arrow head. The new
   value of this kwarg is ``head_width = 20 * width``.
diff --git a/lib/matplotlib/cm.py b/lib/matplotlib/cm.py
@@ -193,12 +193,14 @@ def __init__(self, norm=None, cmap=None):
         self.norm = norm
         #: The Colormap instance of this ScalarMappable.
         self.cmap = get_cmap(cmap)
+        #: The last colorbar associated with this ScalarMappable. May be None.
         self.colorbar = None
         self.update_dict = {'array': False}
 
+    @cbook.deprecated('1.3', alternative='the colorbar attribute')
     def set_colorbar(self, im, ax):
-        'set the colorbar image and axes associated with mappable'
-        self.colorbar = im, ax
+        """set the colorbar and axes instances associated with mappable"""
+        self.colorbar = im
 
     def to_rgba(self, x, alpha=None, bytes=False):
         """
diff --git a/lib/matplotlib/colorbar.py b/lib/matplotlib/colorbar.py
@@ -269,6 +269,7 @@ def __init__(self, ax, cmap=None,
                  extendrect=False,
                  label='',
                  ):
+        #: The axes that this colorbar lives in.
         self.ax = ax
         self._patch_ax()
         if cmap is None:
@@ -1270,6 +1271,6 @@ def colorbar_factory(cax, mappable, **kwargs):
         cb = Colorbar(cax, mappable, **kwargs)
 
     mappable.callbacksSM.connect('changed', cb.on_mappable_changed)
-    mappable.set_colorbar(cb, cax)
+    mappable.colorbar = cb
 
     return cb
diff --git a/lib/mpl_toolkits/axes_grid/colorbar.py b/lib/mpl_toolkits/axes_grid/colorbar.py
@@ -824,6 +824,6 @@ def on_changed(m):
         cb.update_bruteforce(m)
 
     cbid = mappable.callbacksSM.connect('changed', on_changed)
-    mappable.set_colorbar(cb, cax)
+    mappable.colorbar = cb
     ax.figure.sca(ax)
     return cb
diff --git a/lib/mpl_toolkits/axes_grid1/axes_grid.py b/lib/mpl_toolkits/axes_grid1/axes_grid.py
@@ -92,7 +92,7 @@ def on_changed(m):
             cb.update_bruteforce(m)
 
         self.cbid = mappable.callbacksSM.connect('changed', on_changed)
-        mappable.set_colorbar(cb, self)
+        mappable.colorbar = cb
 
         self.locator = cb.cbar_axis.get_major_locator()
 
diff --git a/lib/mpl_toolkits/axes_grid1/colorbar.py b/lib/mpl_toolkits/axes_grid1/colorbar.py
@@ -825,6 +825,6 @@ def on_changed(m):
         cb.update_bruteforce(m)
 
     cbid = mappable.callbacksSM.connect('changed', on_changed)
-    mappable.set_colorbar(cb, cax)
+    mappable.colorbar = cb
     ax.figure.sca(ax)
     return cb
