Warn in colorbar() when mappable.axes != figure.gca().

anntzer · anntzer · commit 464072ee7eab · 2018-10-08T23:27:37.000+02:00
diff --git a/doc/api/api_changes/2018-10-08-AL-colorbar.rst b/doc/api/api_changes/2018-10-08-AL-colorbar.rst
@@ -0,0 +1,12 @@
+Figure.colorbar now warns when the mappable's axes is different from the current axes
+`````````````````````````````````````````````````````````````````````````````````````
+
+Currently, `Figure.colorbar()` steals space by default from the current axes
+to place the colorbar.  In a future version, it will steal space from the
+mappable's axes instead.  In preparation for this change, `Figure.colorbar()`
+now emits a warning when the current axes is not the same as the mappable's
+axes.
+
+The :attr:`.ax` attribute to `ContourSet` is deprecated in favor of
+:attr:`.axes` for consistency with artists (even though `ContourSet` is not an
+`Artist` subclass).
diff --git a/lib/matplotlib/blocking_input.py b/lib/matplotlib/blocking_input.py
@@ -273,7 +273,7 @@ class BlockingContourLabeler(BlockingMouseInput):
 
     def __init__(self, cs):
         self.cs = cs
-        BlockingMouseInput.__init__(self, fig=cs.ax.figure)
+        BlockingMouseInput.__init__(self, fig=cs.axes.figure)
 
     def add_click(self, event):
         self.button1(event)
diff --git a/lib/matplotlib/contour.py b/lib/matplotlib/contour.py
@@ -315,7 +315,7 @@ def set_label_props(self, label, text, color):
         label.set_text(text)
         label.set_color(color)
         label.set_fontproperties(self.labelFontProps)
-        label.set_clip_box(self.ax.bbox)
+        label.set_clip_box(self.axes.bbox)
 
     def get_text(self, lev, fmt):
         """Get the text of the label."""
@@ -457,7 +457,7 @@ def calc_label_rot_and_inline(self, slc, ind, lw, lc=None, spacing=5):
         return rotation, nlc
 
     def _get_label_text(self, x, y, rotation):
-        dx, dy = self.ax.transData.inverted().transform_point((x, y))
+        dx, dy = self.axes.transData.inverted().transform_point((x, y))
         t = text.Text(dx, dy, rotation=rotation,
                       horizontalalignment='center',
                       verticalalignment='center')
@@ -468,7 +468,7 @@ def _get_label_clabeltext(self, x, y, rotation):
         # the data coordinate and create a label using ClabelText
         # class. This way, the rotation of the clabel is along the
         # contour line always.
-        transDataInv = self.ax.transData.inverted()
+        transDataInv = self.axes.transData.inverted()
         dx, dy = transDataInv.transform_point((x, y))
         drotation = transDataInv.transform_angles(np.array([rotation]),
                                                   np.array([[x, y]]))
@@ -488,7 +488,7 @@ def _add_label(self, t, x, y, lev, cvalue):
         self.labelXYs.append((x, y))
 
         # Add label to plot here - useful for manual mode label selection
-        self.ax.add_artist(t)
+        self.axes.add_artist(t)
 
     def add_label(self, x, y, rotation, lev, cvalue):
         """
@@ -534,7 +534,7 @@ def add_label_near(self, x, y, inline=True, inline_spacing=5,
         """
 
         if transform is None:
-            transform = self.ax.transData
+            transform = self.axes.transData
 
         if transform:
             x, y = transform.transform_point((x, y))
@@ -553,7 +553,7 @@ def add_label_near(self, x, y, inline=True, inline_spacing=5,
         # grab its vertices
         lc = active_path.vertices
         # sort out where the new vertex should be added data-units
-        xcmin = self.ax.transData.inverted().transform_point([xmin, ymin])
+        xcmin = self.axes.transData.inverted().transform_point([xmin, ymin])
         # if there isn't a vertex close enough
         if not np.allclose(xcmin, lc[imin]):
             # insert new data into the vertex list
@@ -569,13 +569,13 @@ def add_label_near(self, x, y, inline=True, inline_spacing=5,
         lc = paths[segmin].vertices
 
         # In pixel/screen space
-        slc = self.ax.transData.transform(lc)
+        slc = self.axes.transData.transform(lc)
 
         # Get label width for rotating labels and breaking contours
         lw = self.get_label_width(self.labelLevelList[lmin],
                                   self.labelFmt, self.labelFontSizeList[lmin])
         # lw is in points.
-        lw *= self.ax.figure.dpi / 72.0  # scale to screen coordinates
+        lw *= self.axes.figure.dpi / 72  # scale to screen coordinates
         # now lw in pixels
 
         # Figure out label rotation.
@@ -619,7 +619,7 @@ def labels(self, inline, inline_spacing):
             con = self.collections[icon]
             trans = con.get_transform()
             lw = self.get_label_width(lev, self.labelFmt, fsize)
-            lw *= self.ax.figure.dpi / 72.0  # scale to screen coordinates
+            lw *= self.axes.figure.dpi / 72  # scale to screen coordinates
             additions = []
             paths = con.get_paths()
             for segNum, linepath in enumerate(paths):
@@ -840,7 +840,7 @@ def __init__(self, ax, *args,
             Keyword arguments are as described in the docstring of
             `~axes.Axes.contour`.
         """
-        self.ax = ax
+        self.axes = ax
         self.levels = levels
         self.filled = filled
         self.linewidths = linewidths
@@ -959,7 +959,7 @@ def __init__(self, ax, *args,
                     alpha=self.alpha,
                     transform=self.get_transform(),
                     zorder=zorder)
-                self.ax.add_collection(col, autolim=False)
+                self.axes.add_collection(col, autolim=False)
                 self.collections.append(col)
         else:
             tlinewidths = self._process_linewidths()
@@ -981,14 +981,14 @@ def __init__(self, ax, *args,
                     transform=self.get_transform(),
                     zorder=zorder)
                 col.set_label('_nolegend_')
-                self.ax.add_collection(col, autolim=False)
+                self.axes.add_collection(col, autolim=False)
                 self.collections.append(col)
 
         for col in self.collections:
             col.sticky_edges.x[:] = [self._mins[0], self._maxs[0]]
             col.sticky_edges.y[:] = [self._mins[1], self._maxs[1]]
-        self.ax.update_datalim([self._mins, self._maxs])
-        self.ax.autoscale_view(tight=True)
+        self.axes.update_datalim([self._mins, self._maxs])
+        self.axes.autoscale_view(tight=True)
 
         self.changed()  # set the colors
 
@@ -997,16 +997,21 @@ def __init__(self, ax, *args,
             warnings.warn('The following kwargs were not used by contour: ' +
                           s)
 
+    @cbook.deprecated("3.1")
+    @property
+    def ax(self):
+        return self.axes
+
     def get_transform(self):
         """
         Return the :class:`~matplotlib.transforms.Transform`
         instance used by this ContourSet.
         """
         if self._transform is None:
-            self._transform = self.ax.transData
+            self._transform = self.axes.transData
         elif (not isinstance(self._transform, mtransforms.Transform)
               and hasattr(self._transform, '_as_mpl_transform')):
-            self._transform = self._transform._as_mpl_transform(self.ax)
+            self._transform = self._transform._as_mpl_transform(self.axes)
         return self._transform
 
     def __getstate__(self):
@@ -1497,9 +1502,9 @@ def _process_args(self, *args, **kwargs):
 
             # if the transform is not trans data, and some part of it
             # contains transData, transform the xs and ys to data coordinates
-            if (t != self.ax.transData and
-                    any(t.contains_branch_seperately(self.ax.transData))):
-                trans_to_data = t - self.ax.transData
+            if (t != self.axes.transData and
+                    any(t.contains_branch_seperately(self.axes.transData))):
+                trans_to_data = t - self.axes.transData
                 pts = (np.vstack([x.flat, y.flat]).T)
                 transformed_pts = trans_to_data.transform(pts)
                 x = transformed_pts[..., 0]
@@ -1567,9 +1572,9 @@ def _check_xyz(self, args, kwargs):
         Exception class (here and elsewhere).
         """
         x, y = args[:2]
-        kwargs = self.ax._process_unit_info(xdata=x, ydata=y, kwargs=kwargs)
-        x = self.ax.convert_xunits(x)
-        y = self.ax.convert_yunits(y)
+        kwargs = self.axes._process_unit_info(xdata=x, ydata=y, kwargs=kwargs)
+        x = self.axes.convert_xunits(x)
+        y = self.axes.convert_yunits(y)
 
         x = np.asarray(x, dtype=np.float64)
         y = np.asarray(y, dtype=np.float64)
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -2127,13 +2127,20 @@ def colorbar(self, mappable, cax=None, ax=None, use_gridspec=True, **kw):
         """
         if ax is None:
             ax = self.gca()
+            if ax is not mappable.axes:
+                cbook.warn_deprecated(
+                    "3.1", message="Starting from Matplotlib 3.3, colorbar() "
+                    "will steal space from the mappable's axes, rather than "
+                    "from the current axes, to place the colorbar.  To "
+                    "silence this warning, explicitly pass the 'ax' argument "
+                    "to colorbar().")
 
         # Store the value of gca so that we can set it back later on.
         current_ax = self.gca()
 
         if cax is None:
-            if use_gridspec and isinstance(ax, SubplotBase)  \
-                     and (not self.get_constrained_layout()):
+            if (use_gridspec and isinstance(ax, SubplotBase)
+                    and not self.get_constrained_layout()):
                 cax, kw = cbar.make_axes_gridspec(ax, **kw)
             else:
                 cax, kw = cbar.make_axes(ax, **kw)
