re factored _AnnoationBase to push keeping track of there the

secondary object is to the sub-classes.

Added properties to maintain back-compatibility

added properties to replace xytext and textcoords (xyann, anncoords)

properly deprecated `textcoord` and `xytext` in favor of `anncoords`
and `xyann`.

Author: tacaswell

doc/api/api_changes.rst

@@ -59,9 +59,24 @@ original location:
   thus `colorbar.ColorbarBase.outline` is now a
   `matplotlib.patches.Polygon` object.
 
+
 * The rcParams `savefig.transparent` has been added to control
   default transparency when saving figures.
 
+* Slightly refactored the `Annotation` family.  The text location in
+  `Annotation` is now handled entirely handled by the underlying `Text`
+  object so `set_position` works as expected.  The attributes `xytext` and
+  `textcoords` have been deprecated in favor of `xyann` and `anncoords` so
+  that `Annotation` and `AnnotaionBbox` can share a common sensibly named
+  api for getting/setting the location of the text or box.
+
+    - `xyann` -> set the location of the annotation
+    - `xy` -> set where the arrow points to
+    - `anncoords` -> set the units of the annotation location
+    - `xycoords` -> set the units of the point location
+    - `set_position()` -> `Annotation` only set location of annotation
+
+
 .. _changes_in_1_3:
 
 

lib/matplotlib/offsetbox.py

@@ -1265,6 +1265,10 @@ def __init__(self, offsetbox, xy,
 
         self.set_fontsize(fontsize)
 
+        self.xybox = xybox
+
+        self.boxcoords = boxcoords
+
         if arrowprops is not None:
             self._arrow_relpos = self.arrowprops.pop("relpos", (0.5, 0.5))
             self.arrow_patch = FancyArrowPatch((0, 0), (1, 1),
@@ -1274,8 +1278,8 @@ def __init__(self, offsetbox, xy,
             self.arrow_patch = None
 
         _AnnotationBase.__init__(self,
-                                 xy, xytext=xybox,
-                                 xycoords=xycoords, textcoords=boxcoords,
+                                 xy,
+                                 xycoords=xycoords,
                                  annotation_clip=annotation_clip)
 
         martist.Artist.__init__(self, **kwargs)
@@ -1295,6 +1299,22 @@ def __init__(self, offsetbox, xy,
             self.patch.set(**bboxprops)
         self._drawFrame = frameon
 
+    @property
+    def xyann(self):
+        return self.xybox
+
+    @xyann.setter
+    def xyann(self, xyann):
+        self.xybox = xyann
+
+    @property
+    def anncoords(self):
+        return self.boxcoords
+
+    @anncoords.setter
+    def anncoords(self, coords):
+        self.boxcoords = coords
+
     def contains(self, event):
         t, tinfo = self.offsetbox.contains(event)
         #if self.arrow_patch is not None:
@@ -1352,14 +1372,14 @@ def _update_position_xybox(self, renderer, xy_pixel):
         patch.
         """
 
-        x, y = self.xytext
-        if isinstance(self.textcoords, tuple):
-            xcoord, ycoord = self.textcoords
+        x, y = self.xybox
+        if isinstance(self.boxcoords, tuple):
+            xcoord, ycoord = self.boxcoords
             x1, y1 = self._get_xy(renderer, x, y, xcoord)
             x2, y2 = self._get_xy(renderer, x, y, ycoord)
             ox0, oy0 = x1, y2
         else:
-            ox0, oy0 = self._get_xy(renderer, x, y, self.textcoords)
+            ox0, oy0 = self._get_xy(renderer, x, y, self.boxcoords)
 
         w, h, xd, yd = self.offsetbox.get_extent(renderer)
 
@@ -1579,32 +1599,30 @@ def __init__(self, annotation, use_blit=False):
 
     def save_offset(self):
         ann = self.annotation
-        x, y = ann.xytext
-        if isinstance(ann.textcoords, tuple):
-            xcoord, ycoord = ann.textcoords
+        x, y = ann.xyann
+        if isinstance(ann.anncoords, tuple):
+            xcoord, ycoord = ann.anncoords
             x1, y1 = ann._get_xy(self.canvas.renderer, x, y, xcoord)
             x2, y2 = ann._get_xy(self.canvas.renderer, x, y, ycoord)
             ox0, oy0 = x1, y2
         else:
-            ox0, oy0 = ann._get_xy(self.canvas.renderer, x, y, ann.textcoords)
+            ox0, oy0 = ann._get_xy(self.canvas.renderer, x, y, ann.anncoords)
 
         self.ox, self.oy = ox0, oy0
-        self.annotation.textcoords = "figure pixels"
+        self.annotation.anncoords = "figure pixels"
         self.update_offset(0, 0)
 
     def update_offset(self, dx, dy):
         ann = self.annotation
-        ann.xytext = self.ox + dx, self.oy + dy
-        x, y = ann.xytext
-        # xy is never used
-        xy = ann._get_xy(self.canvas.renderer, x, y, ann.textcoords)
+        ann.xyann = self.ox + dx, self.oy + dy
+        x, y = ann.xyann
 
     def finalize_offset(self):
-        loc_in_canvas = self.annotation.xytext
-        self.annotation.textcoords = "axes fraction"
+        loc_in_canvas = self.annotation.xyann
+        self.annotation.anncoords = "axes fraction"
         pos_axes_fraction = self.annotation.axes.transAxes.inverted()
         pos_axes_fraction = pos_axes_fraction.transform_point(loc_in_canvas)
-        self.annotation.xytext = tuple(pos_axes_fraction)
+        self.annotation.xyann = tuple(pos_axes_fraction)
 
 
 if __name__ == "__main__":

lib/matplotlib/text.py

@@ -1435,19 +1435,12 @@ def __call__(self, renderer):
 
 class _AnnotationBase(object):
     def __init__(self,
-                 xy, xytext=None,
-                 xycoords='data', textcoords=None,
+                 xy,
+                 xycoords='data',
                  annotation_clip=None):
-        if xytext is None:
-            xytext = xy
-        if textcoords is None:
-            textcoords = xycoords
-        # we'll draw ourself after the artist we annotate by default
-        x, y = self.xytext = xytext
 
         self.xy = xy
         self.xycoords = xycoords
-        self.textcoords = textcoords
         self.set_annotation_clip(annotation_clip)
 
         self._draggable = None
@@ -1655,6 +1648,26 @@ def draggable(self, state=None, use_blit=False):
 
         return self._draggable
 
+    @property
+    @cbook.deprecated('1.4', message='Use `anncoords` instead', name='textcoords', alternative='anncoords')
+    def textcoords(self):
+        return self.anncoords
+
+    @textcoords.setter
+    @cbook.deprecated('1.4', message='Use `anncoords` instead', name='textcoords', alternative='anncoords')
+    def textcoords(self, val):
+        self.anncoords = val
+
+    @property
+    @cbook.deprecated('1.4', message='Use `xyann` instead', name='xytext', alternative='xyann')
+    def xytext(self):
+        self.xyann
+
+    @xytext.setter
+    @cbook.deprecated('1.4', message='Use `xyann` instead', name='xytext', alternative='xyann')
+    def xytext(self, val):
+        self.xyann = val
+
 
 class Annotation(Text, _AnnotationBase):
     """
@@ -1778,11 +1791,20 @@ def __init__(self, s, xy,
         """
 
         _AnnotationBase.__init__(self,
-                                 xy, xytext=xytext,
-                                 xycoords=xycoords, textcoords=textcoords,
+                                 xy,
+                                 xycoords=xycoords,
                                  annotation_clip=annotation_clip)
 
-        x, y = self.xytext
+        # clean up textcoords and assign default
+        if textcoords is None:
+            textcoords = self.xycoords
+        self._textcoords = textcoords
+
+        # cleanup xytext defaults
+        if xytext is None:
+            xytext = self.xy
+        x, y = xytext
+
         Text.__init__(self, x, y, s, **kwargs)
 
         self.arrowprops = arrowprops
@@ -1802,10 +1824,26 @@ def contains(self, event):
         if self.arrow is not None:
             in_arrow, _ = self.arrow.contains(event)
             contains = contains or in_arrow
-        # self.arrow_patch is currently not checked as this can be a line - JJ
+        # self.arrow_patch is currently not checked as this can be a line - J
 
         return contains, tinfo
 
+    @property
+    def xyann(self):
+        return self.get_position()
+
+    @xyann.setter
+    def xyann(self, xytext):
+        self.set_position(xytext)
+
+    @property
+    def anncoords(self):
+        return self._textcoords
+
+    @anncoords.setter
+    def anncoords(self, coords):
+        self._textcoords = coords
+
     def set_figure(self, fig):
 
         if self.arrow is not None:
@@ -1825,18 +1863,14 @@ def _update_position_xytext(self, renderer, xy_pixel):
         """Update the pixel positions of the annotation text and the arrow
         patch.
         """
+        # generate transformation,
+        self.set_transform(self._get_xy_transform(renderer, self.anncoords))
 
-        x, y = self.xytext
-        self._x, self._y = self._get_xy(renderer, x, y,
-                                        self.textcoords)
-
-        x, y = xy_pixel
-
-        ox0, oy0 = self._x, self._y
-        ox1, oy1 = x, y
+        ox0, oy0 = self._get_xy_display()
+        ox1, oy1 = xy_pixel
 
         if self.arrowprops:
-            x0, y0 = x, y
+            x0, y0 = xy_pixel
             l, b, w, h = self.get_window_extent(renderer).bounds
             r = l + w
             t = b + h

lib/mpl_toolkits/axisartist/axis_artist.py

@@ -1378,7 +1378,7 @@ def _update_offsetText(self):
         self.offsetText.set_text( self.axis.major.formatter.get_offset() )
         self.offsetText.set_size(self.major_ticklabels.get_size())
         offset = self.major_ticklabels.get_pad() + self.major_ticklabels.get_size() + 2.
-        self.offsetText.xytext= (0, offset)
+        self.offsetText.xyann= (0, offset)
 
 
     def _draw_offsetText(self, renderer):