Various TextPath cleanups.

anntzer · anntzer · commit df3d7981f49b · 2019-01-14T12:24:17.000+01:00
In TextToPath.get_text_path, deprecate the usetex parameter in favor of
a tristate ismath={False, True, "TeX"}, which is consistent with all
other low-level text handling APIs (at the renderer level).  (TextToPath
methods should be considered as low-level APIs; the main high-level API
is TextPath.)

Deprecate `TextPath.text_get_vertices_codes` and `TextPath.is_math_text`
which are clearly helper functions for the main constructor.
Moreover, previously, if TextPath was called with `usetex=False` and
`rcParams["text.usetex"]` == True, then `TextPath.is_math_text` would
return "TeX" as the ismath flag, which would then be interpreted as a
True ismath value (but not a True usetex value(!)) by
TextToPath.get_text_path.  The new implementation avoids that problem.

Remove a nonexistent parameter from the docs of
RendererBase._get_text_path_transform.
diff --git a/doc/api/next_api_changes/2019-01-13-AL.rst b/doc/api/next_api_changes/2019-01-13-AL.rst
@@ -2,3 +2,19 @@ Deprecations
 ````````````
 
 ``Text.is_math_text`` is deprecated.
+
+``TextPath.is_math_text`` and ``TextPath.text_get_vertices_codes`` are
+deprecated.  As an alternative to the latter, construct a new ``TextPath``
+object.
+
+The ``usetex`` parameter of ``TextToPath.get_text_path`` is deprecated and
+folded into the ``ismath`` parameter, which can now take the values False,
+True, and "TeX", consistently with other low-level text processing functions.
+
+Behavior changes
+````````````````
+
+Previously, if :rc:`text.usetex` was True, then constructing a `TextPath` on
+a non-mathtext string with ``usetex=False`` would rely on the mathtext parser
+(but not on usetex support!) to parse the string.  The mathtext parser is not
+invoked anymore, which may cause slight changes in glyph positioning.
diff --git a/lib/matplotlib/backend_bases.py b/lib/matplotlib/backend_bases.py
@@ -556,8 +556,6 @@ def _get_text_path_transform(self, x, y, s, prop, angle, ismath):
             The font property.
         s : str
             The text to be converted.
-        usetex : bool
-            Whether to use matplotlib usetex mode.
         ismath : bool or "TeX"
             If True, use mathtext parser. If "TeX", use *usetex* mode.
         """
diff --git a/lib/matplotlib/textpath.py b/lib/matplotlib/textpath.py
@@ -107,6 +107,7 @@ def get_text_width_height_descent(self, s, prop, ismath):
         d /= 64.0
         return w * scale, h * scale, d * scale
 
+    @cbook._delete_parameter("3.1", "usetex")
     def get_text_path(self, prop, s, ismath=False, usetex=False):
         """
         Convert text *s* to path (a tuple of vertices and codes for
@@ -121,12 +122,11 @@ def get_text_path(self, prop, s, ismath=False, usetex=False):
         s : str
             The text to be converted.
 
-        usetex : bool, optional
-            Whether to use tex rendering. Defaults to ``False``.
+        ismath : {False, True, "TeX"}
+            If True, use mathtext parser.  If "TeX", use tex for renderering.
 
-        ismath : bool, optional
-            If True, use mathtext parser. Effective only if
-            ``usetex == False``.
+        usetex : bool, optional
+            If set, forces *ismath* to True.  This parameter is deprecated.
 
         Returns
         -------
@@ -151,16 +151,15 @@ def get_text_path(self, prop, s, ismath=False, usetex=False):
 
         Also see `TextPath` for a more direct way to create a path from a text.
         """
-        if not usetex:
-            if not ismath:
-                font = self._get_font(prop)
-                glyph_info, glyph_map, rects = self.get_glyphs_with_font(
-                                                    font, s)
-            else:
-                glyph_info, glyph_map, rects = self.get_glyphs_mathtext(
-                                                    prop, s)
-        else:
+        if usetex:
+            ismath = "TeX"
+        if ismath == "TeX":
             glyph_info, glyph_map, rects = self.get_glyphs_tex(prop, s)
+        elif not ismath:
+            font = self._get_font(prop)
+            glyph_info, glyph_map, rects = self.get_glyphs_with_font(font, s)
+        else:
+            glyph_info, glyph_map, rects = self.get_glyphs_mathtext(prop, s)
 
         verts, codes = [], []
 
@@ -457,6 +456,8 @@ def __init__(self, xy, s, size=None, prop=None,
 
         Also see :doc:`/gallery/text_labels_and_annotations/demo_text_path`.
         """
+        # Circular import.
+        from matplotlib.text import Text
 
         if kl or kwargs:
             cbook.warn_deprecated(
@@ -472,8 +473,13 @@ def __init__(self, xy, s, size=None, prop=None,
         self.set_size(size)
 
         self._cached_vertices = None
-        self._vertices, self._codes = \
-            self.text_get_vertices_codes(prop, s, usetex=usetex)
+        s, ismath = Text(usetex=usetex)._preprocess_math(s)
+        if ismath == "TeX":
+            self._vertices, self._codes = text_to_path.get_text_path(
+                prop, s, usetex=True)
+        else:
+            self._vertices, self._codes = text_to_path.get_text_path(
+                prop, s, ismath=ismath)
         self._should_simplify = False
         self._simplify_threshold = rcParams['path.simplify_threshold']
         self._interpolation_steps = _interpolation_steps
@@ -522,6 +528,7 @@ def _revalidate_path(self):
             self._cached_vertices = tr.transform(self._vertices)
             self._invalid = False
 
+    @cbook.deprecated("3.1")
     def is_math_text(self, s):
         """
         Returns True if the given string *s* contains any mathtext.
@@ -541,6 +548,7 @@ def is_math_text(self, s):
         else:
             return s.replace(r'\$', '$'), False
 
+    @cbook.deprecated("3.1", alternative="TextPath")
     def text_get_vertices_codes(self, prop, s, usetex):
         """
         convert the string *s* to vertices and codes using the
