Soft deprecate the textpath module (import from text instead)

oscargus · oscargus · commit 71a368580a3b · 2022-12-17T11:44:06.000+01:00
The textpath module was created in 2009, but the status has
been a bit vague with many examples and exisiting code found
on the internet importing from text instead.

In this PR everything is changed to point at text, although textpath
is still available for backwards compatibility.
diff --git a/doc/api/index.rst b/doc/api/index.rst
@@ -147,7 +147,6 @@ Alphabetical list of modules:
    testing_api.rst
    text_api.rst
    texmanager_api.rst
-   textpath_api.rst
    ticker_api.rst
    tight_bbox_api.rst
    tight_layout_api.rst
diff --git a/doc/api/text_api.rst b/doc/api/text_api.rst
@@ -2,6 +2,8 @@
 ``matplotlib.text``
 *******************
 
+.. redirect-from:: /api/textpath_api
+
 .. automodule:: matplotlib.text
    :no-members:
 
@@ -19,3 +21,13 @@
    :members:
    :undoc-members:
    :show-inheritance:
+
+.. autoclass:: matplotlib.text.TextPath
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: matplotlib.text.TextToPath
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/api/textpath_api.rst b/doc/api/textpath_api.rst
diff --git a/examples/lines_bars_and_markers/multivariate_marker_plot.py b/examples/lines_bars_and_markers/multivariate_marker_plot.py
@@ -13,7 +13,7 @@
 import matplotlib.pyplot as plt
 from matplotlib.markers import MarkerStyle
 from matplotlib.transforms import Affine2D
-from matplotlib.textpath import TextPath
+from matplotlib.text import TextPath
 from matplotlib.colors import Normalize
 
 SUCCESS_SYMBOLS = [
diff --git a/examples/misc/logos2.py b/examples/misc/logos2.py
@@ -11,7 +11,7 @@
 import matplotlib.cm as cm
 import matplotlib.font_manager
 from matplotlib.patches import Rectangle, PathPatch
-from matplotlib.textpath import TextPath
+from matplotlib.text import TextPath
 import matplotlib.transforms as mtrans
 
 MPL_BLUE = '#11557c'
diff --git a/examples/text_labels_and_annotations/demo_text_path.py b/examples/text_labels_and_annotations/demo_text_path.py
@@ -3,7 +3,7 @@
 Using a text as a Path
 ======================
 
-`~matplotlib.textpath.TextPath` creates a `.Path` that is the outline of the
+`~matplotlib.text.TextPath` creates a `.Path` that is the outline of the
 characters of a text. The resulting path can be employed e.g. as a clip path
 for an image.
 """
diff --git a/lib/matplotlib/backend_bases.py b/lib/matplotlib/backend_bases.py
@@ -43,7 +43,7 @@
 
 import matplotlib as mpl
 from matplotlib import (
-    _api, backend_tools as tools, cbook, colors, _docstring, textpath,
+    _api, backend_tools as tools, cbook, colors, _docstring, text,
     _tight_bbox, transforms, widgets, get_backend, is_interactive, rcParams)
 from matplotlib._pylab_helpers import Gcf
 from matplotlib.backend_managers import ToolManager
@@ -172,7 +172,7 @@ class RendererBase:
     def __init__(self):
         super().__init__()
         self._texmanager = None
-        self._text2path = textpath.TextToPath()
+        self._text2path = text.TextToPath()
         self._raster_depth = 0
         self._rasterizing = False
 
@@ -515,7 +515,7 @@ def draw_tex(self, gc, x, y, s, prop, angle, *, mtext=None):
             The y location of the text baseline in display coords.
         s : str
             The TeX text string.
-        prop : `matplotlib.font_manager.FontProperties`
+        prop : `~matplotlib.font_manager.FontProperties`
             The font properties.
         angle : float
             The rotation angle in degrees anti-clockwise.
@@ -538,12 +538,12 @@ def draw_text(self, gc, x, y, s, prop, angle, ismath=False, mtext=None):
             The y location of the text baseline in display coords.
         s : str
             The text string.
-        prop : `matplotlib.font_manager.FontProperties`
+        prop : `~matplotlib.font_manager.FontProperties`
             The font properties.
         angle : float
             The rotation angle in degrees anti-clockwise.
         ismath : bool or "TeX"
-            If True, use mathtext parser. If "TeX", use *usetex* mode.
+            If True, use mathtext parser. If "TeX", use tex for rendering.
         mtext : `matplotlib.text.Text`
             The original text object to be rendered.
 
@@ -569,12 +569,18 @@ def _get_text_path_transform(self, x, y, s, prop, angle, ismath):
 
         Parameters
         ----------
-        prop : `matplotlib.font_manager.FontProperties`
-            The font property.
+        x : float
+            The x location of the text in display coords.
+        y : float
+            The y location of the text baseline in display coords.
         s : str
             The text to be converted.
+        prop : `~matplotlib.font_manager.FontProperties`
+            The font property.
+        angle : float
+            Angle in degrees to render the text at.
         ismath : bool or "TeX"
-            If True, use mathtext parser. If "TeX", use *usetex* mode.
+            If True, use mathtext parser. If "TeX", use tex for rendering.
         """
 
         text2path = self._text2path
@@ -599,18 +605,22 @@ def _get_text_path_transform(self, x, y, s, prop, angle, ismath):
 
     def _draw_text_as_path(self, gc, x, y, s, prop, angle, ismath):
         """
-        Draw the text by converting them to paths using textpath module.
+        Draw the text by converting them to paths using `.TextToPath`.
 
         Parameters
         ----------
-        prop : `matplotlib.font_manager.FontProperties`
-            The font property.
+        x : float
+            The x location of the text in display coords.
+        y : float
+            The y location of the text baseline in display coords.
         s : str
             The text to be converted.
-        usetex : bool
-            Whether to use usetex mode.
+        prop : `~matplotlib.font_manager.FontProperties`
+            The font property.
+        angle : float
+            Angle in degrees to render the text at.
         ismath : bool or "TeX"
-            If True, use mathtext parser. If "TeX", use *usetex* mode.
+            If True, use mathtext parser. If "TeX", use tex for rendering.
         """
         path, transform = self._get_text_path_transform(
             x, y, s, prop, angle, ismath)
diff --git a/lib/matplotlib/backends/backend_svg.py b/lib/matplotlib/backends/backend_svg.py
@@ -1050,18 +1050,7 @@ def _adjust_char_id(self, char_id):
         return char_id.replace("%20", "_")
 
     def _draw_text_as_path(self, gc, x, y, s, prop, angle, ismath, mtext=None):
-        """
-        Draw the text by converting them to paths using the textpath module.
-
-        Parameters
-        ----------
-        s : str
-            text to be converted
-        prop : `matplotlib.font_manager.FontProperties`
-            font property
-        ismath : bool
-            If True, use mathtext parser. If "TeX", use *usetex* mode.
-        """
+        # docstring inherited
         writer = self.writer
 
         writer.comment(s)
diff --git a/lib/matplotlib/markers.py b/lib/matplotlib/markers.py
@@ -516,11 +516,11 @@ def _set_tuple_marker(self):
 
     def _set_mathtext_path(self):
         """
-        Draw mathtext markers '$...$' using TextPath object.
+        Draw mathtext markers '$...$' using `.TextPath` object.
 
         Submitted by tcb
         """
-        from matplotlib.textpath import TextPath
+        from matplotlib.text import TextPath
 
         # again, the properties could be initialised just once outside
         # this function
diff --git a/lib/matplotlib/text.py b/lib/matplotlib/text.py
@@ -15,7 +15,7 @@
 from .artist import Artist
 from .font_manager import FontProperties
 from .patches import FancyArrowPatch, FancyBboxPatch, Rectangle
-from .textpath import TextPath  # noqa # Unused, but imported by others.
+from .textpath import TextPath, TextToPath  # Logically located here
 from .transforms import (
     Affine2D, Bbox, BboxBase, BboxTransformTo, IdentityTransform, Transform)
 
diff --git a/lib/matplotlib/textpath.py b/lib/matplotlib/textpath.py
@@ -100,7 +100,7 @@ def get_text_path(self, prop, s, ismath=False):
         from those::
 
             from matplotlib.path import Path
-            from matplotlib.textpath import TextToPath
+            from matplotlib.text import TextToPath
             from matplotlib.font_manager import FontProperties
 
             fp = FontProperties(family="Humor Sans", style="italic")
@@ -341,7 +341,7 @@ def __init__(self, xy, s, size=None, prop=None,
         The following creates a path from the string "ABC" with Helvetica
         font face; and another path from the latex fraction 1/2::
 
-            from matplotlib.textpath import TextPath
+            from matplotlib.text import TextPath
             from matplotlib.font_manager import FontProperties
 
             fp = FontProperties(family="Helvetica", style="italic")
diff --git a/lib/mpl_toolkits/axes_grid1/anchored_artists.py b/lib/mpl_toolkits/axes_grid1/anchored_artists.py
@@ -340,22 +340,22 @@ def __init__(self, transform, label_x, label_y, length=0.15,
         back_length : float, default: 0.15
             Fraction of the arrow behind the arrow crossing.
         head_width : float, default: 10
-            Width of arrow head, sent to ArrowStyle.
+            Width of arrow head, sent to `.ArrowStyle`.
         head_length : float, default: 15
-            Length of arrow head, sent to ArrowStyle.
+            Length of arrow head, sent to `.ArrowStyle`.
         tail_width : float, default: 2
-            Width of arrow tail, sent to ArrowStyle.
+            Width of arrow tail, sent to `.ArrowStyle`.
         text_props, arrow_props : dict
-            Properties of the text and arrows, passed to
-            `~.textpath.TextPath` and `~.patches.FancyArrowPatch`.
+            Properties of the text and arrows, passed to `.TextPath` and
+            `.FancyArrowPatch`.
         **kwargs
             Keyword arguments forwarded to `.AnchoredOffsetbox`.
 
         Attributes
         ----------
         arrow_x, arrow_y : `~matplotlib.patches.FancyArrowPatch`
             Arrow x and y
-        text_path_x, text_path_y : `~matplotlib.textpath.TextPath`
+        text_path_x, text_path_y : `~matplotlib.text.TextPath`
             Path for arrow labels
         p_x, p_y : `~matplotlib.patches.PathPatch`
             Patch for arrow labels
