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`.
matplotlib · mdboom · Sep 10, 2013 · Aug 27, 2013 · Aug 27, 2013 · Sep 6, 2013
commit 3363b125715724ad89d4b33cbddb23e31e7277d5
diff --git a/doc/api/api_changes.rst b/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:



diff --git a/lib/matplotlib/offsetbox.py b/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__":

diff --git a/lib/matplotlib/text.py b/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

diff --git a/lib/mpl_toolkits/axisartist/axis_artist.py b/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):