Deprecate TextWithDash. (matplotlib#13548)

anntzer · ImportanceOfBeingErnest · commit e0d312986479 · 2019-03-01T12:34:01.000+01:00
TextWithDash appears to be an ancestral version of Annotation that was added over two commits in 2005 (6a4d343, fe80816), revised once in 2006 and another time in 2008, and never touched since then. While it "works", its implementation is 400 lines long, it is only mentioned by a single example (dashpointlabel.py), somewhat complicates Axes.text(), and is likely rarely used and replaceable by Annotation for most use cases. Hence, deprecate it, keeping open the option to undeprecate if this turns out to be too disruptive.
diff --git a/doc/api/next_api_changes/2019-03-01-AL.rst b/doc/api/next_api_changes/2019-03-01-AL.rst
@@ -0,0 +1,5 @@
+Deprecations
+````````````
+
+The ``text.TextWithDash`` class and the ``withdash`` keyword argument to
+``text()`` is deprecated.  Consider using ``annotate()`` instead.
diff --git a/examples/text_labels_and_annotations/dashpointlabel.py b/examples/text_labels_and_annotations/dashpointlabel.py
@@ -4,8 +4,13 @@
 ===============
 
 """
+
+import warnings
+
 import matplotlib.pyplot as plt
 
+warnings.simplefilter("ignore")  # Ignore deprecation of withdash.
+
 DATA = ((1, 3),
         (2, 4),
         (3, 1),
@@ -36,5 +41,6 @@
 
 ax.set_xlim((0, 5))
 ax.set_ylim((0, 5))
+ax.set(title="NOTE: The withdash parameter is deprecated.")
 
 plt.show()
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -673,6 +673,7 @@ def secondary_yaxis(self, location, *, functions=None, **kwargs):
             raise ValueError('secondary_yaxis location must be either '
                              'a float or "left"/"right"')
 
+    @cbook._delete_parameter("3.1", "withdash")
     def text(self, x, y, s, fontdict=None, withdash=False, **kwargs):
         """
         Add text to the axes.
@@ -748,7 +749,8 @@ def text(self, x, y, s, fontdict=None, withdash=False, **kwargs):
         # the withdash kwarg and simply delegate whether there's
         # a dash to TextWithDash and dashlength.
 
-        if withdash:
+        if (withdash
+                and withdash is not cbook.deprecation._deprecated_parameter):
             t = mtext.TextWithDash(x, y, text=s)
         else:
             t = mtext.Text(x, y, text=s)
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -1804,6 +1804,7 @@ def legend(self, *args, **kwargs):
         self.stale = True
         return l
 
+    @cbook._delete_parameter("3.1", "withdash")
     @docstring.dedent_interpd
     def text(self, x, y, s, fontdict=None, withdash=False, **kwargs):
         """
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -2936,7 +2936,9 @@ def table(
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
 @docstring.copy(Axes.text)
-def text(x, y, s, fontdict=None, withdash=False, **kwargs):
+def text(
+        x, y, s, fontdict=None,
+        withdash=cbook.deprecation._deprecated_parameter, **kwargs):
     return gca().text(x, y, s, fontdict=fontdict, withdash=withdash, **kwargs)
 
 
diff --git a/lib/matplotlib/text.py b/lib/matplotlib/text.py
@@ -1245,6 +1245,7 @@ def set_fontname(self, fontname):
 docstring.dedent_interpd(Text.__init__)
 
 
+@cbook.deprecated("3.1", alternative="Annotation")
 class TextWithDash(Text):
     """
     This is basically a :class:`~matplotlib.text.Text` with a dash
