API : property-ify Artist.axes

 - deprecate Artist.{get,set}_axes
 - add axes property
 - Raise exception when trying to move artists between axes.

Author: tacaswell

doc/api/api_changes/2014-12-12_axes_property.rst

@@ -0,0 +1,16 @@
+Prevent moving artists between Axes, Property-ify Artist.axes, deprecate Artist.{get,set}_axes
+``````````````````````````````````````````````````````````````````````````````````````````````
+
+The reason this was done was to prevent adding an Artist that is
+already associated with an Axes to be moved/added to a different Axes.
+This was never supported as it causes havoc with the transform stack.
+The apparent support for this (as it did not raise an exception) was
+the source of multiple bug reports and questions on SO.
+
+For almost all use-cases, the assignment of the axes to an artist should be
+taken care of by the axes as part of the ``Axes.add_*`` method, hence the
+deprecation {get,set}_axes.
+
+Removing the ``set_axes`` method will also remove the 'axes' line from
+the ACCEPTS kwarg tables (assuming that the removal date gets here
+before that gets overhauled).

lib/matplotlib/artist.py

@@ -8,6 +8,7 @@
 import inspect
 import matplotlib
 import matplotlib.cbook as cbook
+from matplotlib.cbook import mplDeprecation
 from matplotlib import docstring, rcParams
 from .transforms import (Bbox, IdentityTransform, TransformedBbox,
                          TransformedPath, Transform)
@@ -77,6 +78,7 @@ class Artist(object):
     zorder = 0
 
     def __init__(self):
+        self._axes = None
         self.figure = None
 
         self._transform = None
@@ -175,17 +177,43 @@ def set_axes(self, axes):
         Set the :class:`~matplotlib.axes.Axes` instance in which the
         artist resides, if any.
 
+        This has been deprecated in mpl 1.5, please use the
+        axes property.  Will be removed in 1.7 or 2.0.
+
         ACCEPTS: an :class:`~matplotlib.axes.Axes` instance
         """
+        warnings.warn(_get_axes_msg, mplDeprecation, stacklevel=1)
         self.axes = axes
 
     def get_axes(self):
         """
         Return the :class:`~matplotlib.axes.Axes` instance the artist
-        resides in, or *None*
+        resides in, or *None*.
+
+        This has been deprecated in mpl 1.5, please use the
+        axes property.  Will be removed in 1.7 or 2.0.
         """
+        warnings.warn(_get_axes_msg, mplDeprecation, stacklevel=1)
         return self.axes
 
+    @property
+    def axes(self):
+        """
+        The :class:`~matplotlib.axes.Axes` instance the artist
+        resides in, or *None*.
+        """
+        return self._axes
+
+    @axes.setter
+    def axes(self, new_axes):
+        if self._axes is not None and new_axes != self._axes:
+            raise ValueError("Can not reset the axes.  You are "
+                             "probably trying to re-use an artist "
+                             "in more than one Axes which is not "
+                             "supported")
+        self._axes = new_axes
+        return new_axes
+
     def get_window_extent(self, renderer):
         """
         Get the axes bounding box in display space.
@@ -751,10 +779,13 @@ def update(self, props):
         changed = False
 
         for k, v in six.iteritems(props):
-            func = getattr(self, 'set_' + k, None)
-            if func is None or not six.callable(func):
-                raise AttributeError('Unknown property %s' % k)
-            func(v)
+            if k in ['axes']:
+                setattr(self, k, v)
+            else:
+                func = getattr(self, 'set_' + k, None)
+                if func is None or not six.callable(func):
+                    raise AttributeError('Unknown property %s' % k)
+                func(v)
             changed = True
         self.eventson = store
         if changed:
@@ -1328,3 +1359,6 @@ def kwdoc(a):
         return '\n'.join(ArtistInspector(a).pprint_setters(leadingspace=2))
 
 docstring.interpd.update(Artist=kwdoc(Artist))
+
+_get_axes_msg = """This has been deprecated in mpl 1.5, please use the
+axes property.  A removal date has not been set."""

lib/matplotlib/axes/_base.py

@@ -392,7 +392,8 @@ def __init__(self, fig, rect,
         else:
             self._position = mtransforms.Bbox.from_bounds(*rect)
         self._originalPosition = self._position.frozen()
-        self.set_axes(self)
+        # self.set_axes(self)
+        self.axes = self
         self.set_aspect('auto')
         self._adjustable = 'box'
         self.set_anchor('C')
@@ -774,7 +775,7 @@ def _set_artist_props(self, a):
         if not a.is_transform_set():
             a.set_transform(self.transData)
 
-        a.set_axes(self)
+        a.axes = self
 
     def _gen_axes_patch(self):
         """
@@ -1431,7 +1432,7 @@ def add_artist(self, a):
 
         Returns the artist.
         """
-        a.set_axes(self)
+        a.axes = self
         self.artists.append(a)
         self._set_artist_props(a)
         a.set_clip_path(self.patch)

lib/matplotlib/figure.py

@@ -298,7 +298,11 @@ def __init__(self,
             Defaults to rc ``figure.autolayout``.
         """
         Artist.__init__(self)
-
+        # remove the non-figure artist _axes property
+        # as it makes no sense for a figure to be _in_ an axes
+        # this is used by the property methods in the artist base class
+        # which are over-ridden in this class
+        del self._axes
         self.callbacks = cbook.CallbackRegistry()
 
         if figsize is None:

lib/matplotlib/legend.py

@@ -304,7 +304,7 @@ def __init__(self, parent, handles, labels,
 
         if isinstance(parent, Axes):
             self.isaxes = True
-            self.set_axes(parent)
+            self.axes = parent
             self.set_figure(parent.figure)
         elif isinstance(parent, Figure):
             self.isaxes = False
@@ -391,7 +391,9 @@ def _set_artist_props(self, a):
         """
         a.set_figure(self.figure)
         if self.isaxes:
-            a.set_axes(self.axes)
+            # a.set_axes(self.axes)
+            a.axes = self.axes
+
         a.set_transform(self.get_transform())
 
     def _set_loc(self, loc):

lib/matplotlib/lines.py

@@ -536,15 +536,17 @@ def get_window_extent(self, renderer):
             bbox = bbox.padded(ms)
         return bbox
 
-    def set_axes(self, ax):
-        Artist.set_axes(self, ax)
+    @Artist.axes.setter
+    def axes(self, ax):
+        # call the set method from the base-class property
+        Artist.axes.fset(self, ax)
+        # connect unit-related callbacks
         if ax.xaxis is not None:
             self._xcid = ax.xaxis.callbacks.connect('units',
                                                     self.recache_always)
         if ax.yaxis is not None:
             self._ycid = ax.yaxis.callbacks.connect('units',
                                                     self.recache_always)
-    set_axes.__doc__ = Artist.set_axes.__doc__
 
     def set_data(self, *args):
         """