Deprecate ismath parameter to draw_tex and ismath="TeX!".

anntzer · anntzer · commit f5e6f5df201e · 2020-05-25T01:22:54.000+02:00
This parameter is a bit confusing for backend implementers and actually
effectively ignored (because draw_tex() already means "pass the entire
string to usetex).

Calling through draw_tex() was the only way, previously, to get
`ismath="TeX!"` passed to `get_text_width_height_descent` (other than
calling it manually), but that was handled identically to
`ismath="TeX"` by some backends and just not supported by others.
Again, folding "TeX!" into "TeX" makes the required API simpler for
backend implementers.
diff --git a/doc/api/api_changes_3.3/deprecations.rst b/doc/api/api_changes_3.3/deprecations.rst
@@ -576,3 +576,16 @@ Statusbar classes and attributes
 The ``statusbar`` attribute of `.FigureManagerBase`, `.StatusbarBase` and all
 its subclasses, and ``StatusBarWx``, are deprecated, as messages are now
 displayed in the toolbar instead.
+
+``ismath`` parameter of ``draw_tex``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The ``ismath`` parameter of the ``draw_tex`` method of all renderer classes is
+deprecated (as a call to ``draw_tex`` -- not to be confused with ``draw_text``!
+-- means that the entire string should be passed to the ``usetex`` machinery
+anyways).  Likewise, the text machinery will no longer pass the ``ismath``
+parameter when calling ``draw_tex`` (this should only matter for backend
+implementers).
+
+Passing ``ismath="TeX!"`` to `.RendererAgg.get_text_width_height_descent` is
+deprecated.  Pass ``ismath="TeX"`` instead, consistently with other low-level
+APIs which support the values True, False, and "TeX" for ``ismath``.
diff --git a/lib/matplotlib/backend_bases.py b/lib/matplotlib/backend_bases.py
@@ -503,6 +503,7 @@ def option_scale_image(self):
         """
         return False
 
+    @cbook._delete_parameter("3.3", "ismath")
     def draw_tex(self, gc, x, y, s, prop, angle, ismath='TeX!', mtext=None):
         """
         """
diff --git a/lib/matplotlib/backends/backend_agg.py b/lib/matplotlib/backends/backend_agg.py
@@ -216,6 +216,11 @@ def get_text_width_height_descent(self, s, prop, ismath):
         # docstring inherited
 
         if ismath in ["TeX", "TeX!"]:
+            if ismath == "TeX!":
+                cbook._warn_deprecated(
+                    "3.3", message="Support for ismath='TeX!' is deprecated "
+                    "since %(since)s and will be removed %(removal)s; use "
+                    "ismath='TeX' instead.")
             # todo: handle props
             texmanager = self.get_texmanager()
             fontsize = prop.get_size_in_points()
@@ -238,6 +243,7 @@ def get_text_width_height_descent(self, s, prop, ismath):
         d /= 64.0
         return w, h, d
 
+    @cbook._delete_parameter("3.2", "ismath")
     def draw_tex(self, gc, x, y, s, prop, angle, ismath='TeX!', mtext=None):
         # docstring inherited
         # todo, handle props, angle, origins
@@ -248,7 +254,7 @@ def draw_tex(self, gc, x, y, s, prop, angle, ismath='TeX!', mtext=None):
         Z = texmanager.get_grey(s, size, self.dpi)
         Z = np.array(Z * 255.0, np.uint8)
 
-        w, h, d = self.get_text_width_height_descent(s, prop, ismath)
+        w, h, d = self.get_text_width_height_descent(s, prop, ismath="TeX")
         xd = d * sin(radians(angle))
         yd = d * cos(radians(angle))
         x = round(x + xd)
diff --git a/lib/matplotlib/backends/backend_pdf.py b/lib/matplotlib/backends/backend_pdf.py
@@ -2003,6 +2003,7 @@ def draw_mathtext(self, gc, x, y, s, prop, angle):
         # Pop off the global transformation
         self.file.output(Op.grestore)
 
+    @cbook._delete_parameter("3.3", "ismath")
     def draw_tex(self, gc, x, y, s, prop, angle, ismath='TeX!', mtext=None):
         # docstring inherited
         texmanager = self.get_texmanager()
diff --git a/lib/matplotlib/backends/backend_ps.py b/lib/matplotlib/backends/backend_ps.py
@@ -467,6 +467,7 @@ def draw_path_collection(self, gc, master_transform, paths, all_transforms,
 
         self._path_collection_id += 1
 
+    @cbook._delete_parameter("3.3", "ismath")
     def draw_tex(self, gc, x, y, s, prop, angle, ismath='TeX!', mtext=None):
         # docstring inherited
         if not hasattr(self, "psfrag"):
@@ -475,10 +476,10 @@ def draw_tex(self, gc, x, y, s, prop, angle, ismath='TeX!', mtext=None):
                 "rcParams['text.usetex'] and does not support having "
                 "usetex=True only for some elements; this element will thus "
                 "be rendered as if usetex=False.")
-            self.draw_text(gc, x, y, s, prop, angle, ismath, mtext)
+            self.draw_text(gc, x, y, s, prop, angle, False, mtext)
             return
 
-        w, h, bl = self.get_text_width_height_descent(s, prop, ismath)
+        w, h, bl = self.get_text_width_height_descent(s, prop, ismath="TeX")
         fontsize = prop.get_size_in_points()
         thetext = 'psmarker%d' % self.textcnt
         color = '%1.3f,%1.3f,%1.3f' % gc.get_rgb()[:3]
diff --git a/lib/matplotlib/backends/backend_svg.py b/lib/matplotlib/backends/backend_svg.py
@@ -1114,6 +1114,7 @@ def _draw_text_as_text(self, gc, x, y, s, prop, angle, ismath, mtext=None):
 
             writer.end('g')
 
+    @cbook._delete_parameter("3.3", "ismath")
     def draw_tex(self, gc, x, y, s, prop, angle, ismath='TeX!', mtext=None):
         # docstring inherited
         self._draw_text_as_path(gc, x, y, s, prop, angle, ismath="TeX")
diff --git a/lib/matplotlib/text.py b/lib/matplotlib/text.py
@@ -726,7 +726,7 @@ def draw(self, renderer):
                 if textobj.get_usetex():
                     textrenderer.draw_tex(gc, x, y, clean_line,
                                           textobj._fontproperties, angle,
-                                          ismath=ismath, mtext=mtext)
+                                          mtext=mtext)
                 else:
                     textrenderer.draw_text(gc, x, y, clean_line,
                                            textobj._fontproperties, angle,
