Merge pull request #23576 from oscargus/softdeprecatetextpath

QuLogic · web-flow · commit 0425a7fa40b9 · 2022-12-21T15:56:44.000-05:00
Soft deprecate the textpath module (import from text instead)
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  # noqa # 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
