Deprecate AnchoredEllipse.

Needing to construct exactly just an anchored ellipse seems unlikely,
and any customization will need accessing the underlying APIs
(AnchoredOffsetbox, AuxTransformBox, Ellipse) anyways.  Mashing together
the parameters of all three constructors is rather awkward, too.

Author: anntzer

doc/api/next_api_changes/deprecations/25781-AL.rst

@@ -0,0 +1,4 @@
+``AnchoredEllipse`` is deprecated
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Instead, directly construct an `.AnchoredOffsetbox`, an `.AuxTransformBox`, and an
+`~.patches.Ellipse`, as demonstrated in :doc:`/gallery/misc/anchored_artists`.

galleries/examples/axes_grid1/simple_anchored_artists.py

@@ -46,18 +46,6 @@ def draw_circle(ax):
     ax.add_artist(ada)
 
 
-def draw_ellipse(ax):
-    """
-    Draw an ellipse of width=0.1, height=0.15 in data coordinates
-    """
-    from mpl_toolkits.axes_grid1.anchored_artists import AnchoredEllipse
-    ae = AnchoredEllipse(ax.transData, width=0.1, height=0.15, angle=0.,
-                         loc='lower left', pad=0.5, borderpad=0.4,
-                         frameon=True)
-
-    ax.add_artist(ae)
-
-
 def draw_sizebar(ax):
     """
     Draw a horizontal bar with length of 0.1 in data coordinates,
@@ -78,7 +66,6 @@ def draw_sizebar(ax):
 
 draw_text(ax)
 draw_circle(ax)
-draw_ellipse(ax)
 draw_sizebar(ax)
 
 plt.show()

lib/mpl_toolkits/axes_grid1/anchored_artists.py

@@ -1,4 +1,4 @@
-from matplotlib import transforms
+from matplotlib import _api, transforms
 from matplotlib.offsetbox import (AnchoredOffsetbox, AuxTransformBox,
                                   DrawingArea, TextArea, VPacker)
 from matplotlib.patches import (Rectangle, Ellipse, ArrowStyle,
@@ -124,6 +124,7 @@ def __init__(self, transform, loc,
                          **kwargs)
 
 
+@_api.deprecated("3.8")
 class AnchoredEllipse(AnchoredOffsetbox):
     def __init__(self, transform, width, height, angle, loc,
                  pad=0.1, borderpad=0.1, prop=None, frameon=True, **kwargs):

lib/mpl_toolkits/axes_grid1/tests/test_axes_grid1.py

@@ -526,9 +526,11 @@ def test_anchored_artists():
     box.drawing_area.add_artist(el)
     ax.add_artist(box)
 
-    ae = AnchoredEllipse(ax.transData, width=0.1, height=0.25, angle=-60,
-                         loc='lower left', pad=0.5, borderpad=0.4,
-                         frameon=True)
+    # Manually construct the ellipse instead, once the deprecation elapses.
+    with pytest.warns(mpl.MatplotlibDeprecationWarning):
+        ae = AnchoredEllipse(ax.transData, width=0.1, height=0.25, angle=-60,
+                             loc='lower left', pad=0.5, borderpad=0.4,
+                             frameon=True)
     ax.add_artist(ae)
 
     asb = AnchoredSizeBar(ax.transData, 0.2, r"0.2 units", loc='lower right',