Deprecate TextWithDash.

anntzer · anntzer · commit 8b033a8ce7ea · 2019-02-28T18:56:43.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/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.
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
