From 9b8a598d00a4fcf9579415586053583ef80a1add Mon Sep 17 00:00:00 2001 From: Oscar Gustafsson Date: Sun, 7 Aug 2022 12:15:45 +0200 Subject: [PATCH] Soft deprecate the textpath module (import from text instead) 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. --- doc/api/index.rst | 1 - doc/api/text_api.rst | 12 ++++++ doc/api/textpath_api.rst | 8 ---- .../multivariate_marker_plot.py | 2 +- examples/misc/logos2.py | 2 +- .../demo_text_path.py | 2 +- lib/matplotlib/backend_bases.py | 38 ++++++++++++------- lib/matplotlib/backends/backend_svg.py | 13 +------ lib/matplotlib/markers.py | 4 +- lib/matplotlib/text.py | 2 +- lib/matplotlib/textpath.py | 4 +- .../axes_grid1/anchored_artists.py | 12 +++--- 12 files changed, 51 insertions(+), 49 deletions(-) delete mode 100644 doc/api/textpath_api.rst diff --git a/doc/api/index.rst b/doc/api/index.rst index 3c947bbe3af4..2e8c33fa05e5 100644 --- 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 index 8bed3173ebdb..af37e5c526a3 100644 --- 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 deleted file mode 100644 index 875e4b376867..000000000000 --- a/doc/api/textpath_api.rst +++ /dev/null @@ -1,8 +0,0 @@ -*********************** -``matplotlib.textpath`` -*********************** - -.. automodule:: matplotlib.textpath - :members: - :undoc-members: - :show-inheritance: diff --git a/examples/lines_bars_and_markers/multivariate_marker_plot.py b/examples/lines_bars_and_markers/multivariate_marker_plot.py index 89670b5a223f..7627375b99f5 100644 --- 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 index 06e3b5d65e7a..8febb8b57d60 100644 --- 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 index 3d23e047fd90..1899f314f5b6 100644 --- 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 index 0fd39b04c470..db92346d201e 100644 --- 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 index 03b376a69894..df39e620f888 100644 --- 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 index ace32192b322..91d9f64c1635 100644 --- 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 index 470ee42c713b..d20e06f204d8 100644 --- 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 index 6eb11b5f09d8..e4bb791f6f93 100644 --- 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 index 9989e5184f77..7638a75d924a 100644 --- a/lib/mpl_toolkits/axes_grid1/anchored_artists.py +++ b/lib/mpl_toolkits/axes_grid1/anchored_artists.py @@ -340,14 +340,14 @@ 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`. @@ -355,7 +355,7 @@ def __init__(self, transform, label_x, label_y, length=0.15, ---------- 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