From 7966c344ac4cc572edf1fc19246e650547b76cb6 Mon Sep 17 00:00:00 2001 From: Andrew Murray Date: Thu, 1 Sep 2022 22:26:35 +1000 Subject: [PATCH 1/6] Improved documentation of return values --- docs/reference/ImageDraw.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/reference/ImageDraw.rst b/docs/reference/ImageDraw.rst index 1ef9079fba0..75ef0f5cc9b 100644 --- a/docs/reference/ImageDraw.rst +++ b/docs/reference/ImageDraw.rst @@ -489,6 +489,8 @@ Methods .. versionadded:: 6.2.0 + :returns: A ``(width, height)`` tuple. + .. py:method:: ImageDraw.multiline_textsize(text, font=None, spacing=4, direction=None, features=None, language=None, stroke_width=0) .. deprecated:: 9.2.0 @@ -541,6 +543,8 @@ Methods .. versionadded:: 6.2.0 + :returns: A ``(width, height)`` tuple. + .. py:method:: ImageDraw.textlength(text, font=None, direction=None, features=None, language=None, embedded_color=False) Returns length (in pixels with 1/64 precision) of given text when rendered @@ -608,6 +612,7 @@ Methods It should be a `BCP 47 language code`_. Requires libraqm. :param embedded_color: Whether to use font embedded color glyphs (COLR, CBDT, SBIX). + :returns: A single float, the length of the text. .. py:method:: ImageDraw.textbbox(xy, text, font=None, anchor=None, spacing=4, align="left", direction=None, features=None, language=None, stroke_width=0, embedded_color=False) @@ -657,6 +662,8 @@ Methods Requires libraqm. :param stroke_width: The width of the text stroke. :param embedded_color: Whether to use font embedded color glyphs (COLR, CBDT, SBIX). + :returns: An ``(x0, y0, x1, y1)`` tuple, describing the top left and lower right + corners of the text. .. py:method:: ImageDraw.multiline_textbbox(xy, text, font=None, anchor=None, spacing=4, align="left", direction=None, features=None, language=None, stroke_width=0, embedded_color=False) @@ -700,6 +707,8 @@ Methods Requires libraqm. :param stroke_width: The width of the text stroke. :param embedded_color: Whether to use font embedded color glyphs (COLR, CBDT, SBIX). + :returns: An ``(x0, y0, x1, y1)`` tuple, describing the top left and lower right + corners of the text. .. py:method:: getdraw(im=None, hints=None) From 4783ecf41c1413a05e70d325268141fce6788ac0 Mon Sep 17 00:00:00 2001 From: Andrew Murray Date: Sat, 3 Sep 2022 21:09:44 +1000 Subject: [PATCH 2/6] Updated return values to match ImageFont --- docs/reference/ImageDraw.rst | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/docs/reference/ImageDraw.rst b/docs/reference/ImageDraw.rst index 75ef0f5cc9b..e19e87a0d52 100644 --- a/docs/reference/ImageDraw.rst +++ b/docs/reference/ImageDraw.rst @@ -489,7 +489,7 @@ Methods .. versionadded:: 6.2.0 - :returns: A ``(width, height)`` tuple. + :return: (width, height) .. py:method:: ImageDraw.multiline_textsize(text, font=None, spacing=4, direction=None, features=None, language=None, stroke_width=0) @@ -543,7 +543,7 @@ Methods .. versionadded:: 6.2.0 - :returns: A ``(width, height)`` tuple. + :return: (width, height) .. py:method:: ImageDraw.textlength(text, font=None, direction=None, features=None, language=None, embedded_color=False) @@ -612,7 +612,7 @@ Methods It should be a `BCP 47 language code`_. Requires libraqm. :param embedded_color: Whether to use font embedded color glyphs (COLR, CBDT, SBIX). - :returns: A single float, the length of the text. + :return: Width for horizontal, height for vertical text. .. py:method:: ImageDraw.textbbox(xy, text, font=None, anchor=None, spacing=4, align="left", direction=None, features=None, language=None, stroke_width=0, embedded_color=False) @@ -662,8 +662,7 @@ Methods Requires libraqm. :param stroke_width: The width of the text stroke. :param embedded_color: Whether to use font embedded color glyphs (COLR, CBDT, SBIX). - :returns: An ``(x0, y0, x1, y1)`` tuple, describing the top left and lower right - corners of the text. + :return: ``(left, top, right, bottom)`` bounding box .. py:method:: ImageDraw.multiline_textbbox(xy, text, font=None, anchor=None, spacing=4, align="left", direction=None, features=None, language=None, stroke_width=0, embedded_color=False) @@ -707,8 +706,7 @@ Methods Requires libraqm. :param stroke_width: The width of the text stroke. :param embedded_color: Whether to use font embedded color glyphs (COLR, CBDT, SBIX). - :returns: An ``(x0, y0, x1, y1)`` tuple, describing the top left and lower right - corners of the text. + :return: ``(left, top, right, bottom)`` bounding box .. py:method:: getdraw(im=None, hints=None) From 780de80e5c56e8466faec54f8c0ebe95e543e9ea Mon Sep 17 00:00:00 2001 From: Andrew Murray Date: Sat, 3 Sep 2022 22:23:05 +1000 Subject: [PATCH 3/6] Added examples for updating code --- docs/deprecations.rst | 34 ++++++++++++++++++++++++++++++++++ docs/reference/ImageDraw.rst | 6 ++++++ docs/releasenotes/9.2.0.rst | 34 ++++++++++++++++++++++++++++++++++ src/PIL/ImageFont.py | 15 +++++++++++++++ 4 files changed, 89 insertions(+) diff --git a/docs/deprecations.rst b/docs/deprecations.rst index 9be92770ab9..92f116846f7 100644 --- a/docs/deprecations.rst +++ b/docs/deprecations.rst @@ -197,6 +197,40 @@ Deprecated Use :py:meth:`.ImageDraw2.Draw.textsize` :py:meth:`.ImageDraw2.Draw.textbbox` and :py:meth:`.ImageDraw2.Draw.textlength` =========================================================================== ============================================================================================================= +Previous code: + +.. code-block:: python + + from PIL import Image, ImageDraw, ImageFont + + font = ImageFont.truetype("Tests/fonts/FreeMono.ttf") + width, height = font.getsize("Hello world") + left, top = font.getoffset("Hello world") + + im = Image.new("RGB", (100, 100)) + draw = ImageDraw.Draw(im) + width, height = draw.textsize("Hello world") + + width, height = font.getsize_multiline("Hello\nworld") + width, height = draw.multiline_textsize("Hello\nworld") + +Use instead: + +.. code-block:: python + + from PIL import Image, ImageDraw, ImageFont + + font = ImageFont.truetype("Tests/fonts/FreeMono.ttf") + left, top, right, bottom = font.getbbox("Hello world") + width, height = right - left, bottom - top + + im = Image.new("RGB", (100, 100)) + draw = ImageDraw.Draw(im) + width = draw.textlength("Hello world") + + left, top, right, bottom = draw.multiline_textbbox((0, 0), "Hello\nworld") + width, height = right - left, bottom - top + Removed features ---------------- diff --git a/docs/reference/ImageDraw.rst b/docs/reference/ImageDraw.rst index e19e87a0d52..623f601efeb 100644 --- a/docs/reference/ImageDraw.rst +++ b/docs/reference/ImageDraw.rst @@ -443,6 +443,9 @@ Methods .. deprecated:: 9.2.0 + See https://pillow.readthedocs.io/en/stable/releasenotes/9.2.0.html#font-size-and-offset-methods + for more information. + Use :py:meth:`textlength()` to measure the offset of following text with 1/64 pixel precision. Use :py:meth:`textbbox()` to get the exact bounding box based on an anchor. @@ -495,6 +498,9 @@ Methods .. deprecated:: 9.2.0 + See https://pillow.readthedocs.io/en/stable/releasenotes/9.2.0.html#font-size-and-offset-methods + for more information. + Use :py:meth:`.multiline_textbbox` instead. Return the size of the given string, in pixels. diff --git a/docs/releasenotes/9.2.0.rst b/docs/releasenotes/9.2.0.rst index 9c102f1776a..6dbfa2702eb 100644 --- a/docs/releasenotes/9.2.0.rst +++ b/docs/releasenotes/9.2.0.rst @@ -59,6 +59,40 @@ Deprecated Use :py:meth:`.ImageDraw2.Draw.textsize` :py:meth:`.ImageDraw2.Draw.textbbox` and :py:meth:`.ImageDraw2.Draw.textlength` =========================================================================== ============================================================================================================= +Previous code: + +.. code-block:: python + + from PIL import Image, ImageDraw, ImageFont + + font = ImageFont.truetype("Tests/fonts/FreeMono.ttf") + width, height = font.getsize("Hello world") + left, top = font.getoffset("Hello world") + + im = Image.new("RGB", (100, 100)) + draw = ImageDraw.Draw(im) + width, height = draw.textsize("Hello world") + + width, height = font.getsize_multiline("Hello\nworld") + width, height = draw.multiline_textsize("Hello\nworld") + +Use instead: + +.. code-block:: python + + from PIL import Image, ImageDraw, ImageFont + + font = ImageFont.truetype("Tests/fonts/FreeMono.ttf") + left, top, right, bottom = font.getbbox("Hello world") + width, height = right - left, bottom - top + + im = Image.new("RGB", (100, 100)) + draw = ImageDraw.Draw(im) + width = draw.textlength("Hello world") + + left, top, right, bottom = draw.multiline_textbbox((0, 0), "Hello\nworld") + width, height = right - left, bottom - top + API Additions ============= diff --git a/src/PIL/ImageFont.py b/src/PIL/ImageFont.py index 9386d008602..3d1e4b0bfe1 100644 --- a/src/PIL/ImageFont.py +++ b/src/PIL/ImageFont.py @@ -139,6 +139,9 @@ def getsize(self, text, *args, **kwargs): """ .. deprecated:: 9.2.0 + For more information, see + https://pillow.readthedocs.io/en/stable/releasenotes/9.2.0.html#deprecations. + Use :py:meth:`.getbbox` or :py:meth:`.getlength` instead. Returns width and height (in pixels) of given text. @@ -428,6 +431,9 @@ def getsize( """ .. deprecated:: 9.2.0 + For more information, see + https://pillow.readthedocs.io/en/stable/releasenotes/9.2.0.html#deprecations. + Use :py:meth:`getlength()` to measure the offset of following text with 1/64 pixel precision. Use :py:meth:`getbbox()` to get the exact bounding box based on an anchor. @@ -498,6 +504,9 @@ def getsize_multiline( """ .. deprecated:: 9.2.0 + For more information, see + https://pillow.readthedocs.io/en/stable/releasenotes/9.2.0.html#deprecations. + Use :py:meth:`.ImageDraw.multiline_textbbox` instead. Returns width and height (in pixels) of given text if rendered in font @@ -557,6 +566,9 @@ def getoffset(self, text): """ .. deprecated:: 9.2.0 + For more information, see + https://pillow.readthedocs.io/en/stable/releasenotes/9.2.0.html#deprecations. + Use :py:meth:`.getbbox` instead. Returns the offset of given text. This is the gap between the @@ -851,6 +863,9 @@ def getsize(self, text, *args, **kwargs): """ .. deprecated:: 9.2.0 + For more information, see + https://pillow.readthedocs.io/en/stable/releasenotes/9.2.0.html#deprecations. + Use :py:meth:`.getbbox` or :py:meth:`.getlength` instead. """ deprecate("getsize", 10, "getbbox or getlength") From 209ec9da470ccee20e23620e77972be14016dd7c Mon Sep 17 00:00:00 2001 From: Andrew Murray Date: Tue, 6 Sep 2022 06:43:52 +1000 Subject: [PATCH 4/6] Use target --- docs/deprecations.rst | 2 ++ docs/reference/ImageDraw.rst | 6 ++---- src/PIL/ImageFont.py | 15 +++++---------- 3 files changed, 9 insertions(+), 14 deletions(-) diff --git a/docs/deprecations.rst b/docs/deprecations.rst index 92f116846f7..05de19c9e0f 100644 --- a/docs/deprecations.rst +++ b/docs/deprecations.rst @@ -178,6 +178,8 @@ Image.coerce_e This undocumented method has been deprecated and will be removed in Pillow 10 (2023-07-01). +.. _Font size and offset methods: + Font size and offset methods ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/reference/ImageDraw.rst b/docs/reference/ImageDraw.rst index 623f601efeb..61242b35a0c 100644 --- a/docs/reference/ImageDraw.rst +++ b/docs/reference/ImageDraw.rst @@ -443,8 +443,7 @@ Methods .. deprecated:: 9.2.0 - See https://pillow.readthedocs.io/en/stable/releasenotes/9.2.0.html#font-size-and-offset-methods - for more information. + See :ref:`deprecations ` for more information. Use :py:meth:`textlength()` to measure the offset of following text with 1/64 pixel precision. @@ -498,8 +497,7 @@ Methods .. deprecated:: 9.2.0 - See https://pillow.readthedocs.io/en/stable/releasenotes/9.2.0.html#font-size-and-offset-methods - for more information. + See :ref:`deprecations ` for more information. Use :py:meth:`.multiline_textbbox` instead. diff --git a/src/PIL/ImageFont.py b/src/PIL/ImageFont.py index 3d1e4b0bfe1..c1b7435f363 100644 --- a/src/PIL/ImageFont.py +++ b/src/PIL/ImageFont.py @@ -139,8 +139,7 @@ def getsize(self, text, *args, **kwargs): """ .. deprecated:: 9.2.0 - For more information, see - https://pillow.readthedocs.io/en/stable/releasenotes/9.2.0.html#deprecations. + See :ref:`deprecations ` for more information. Use :py:meth:`.getbbox` or :py:meth:`.getlength` instead. @@ -431,8 +430,7 @@ def getsize( """ .. deprecated:: 9.2.0 - For more information, see - https://pillow.readthedocs.io/en/stable/releasenotes/9.2.0.html#deprecations. + See :ref:`deprecations ` for more information. Use :py:meth:`getlength()` to measure the offset of following text with 1/64 pixel precision. @@ -504,8 +502,7 @@ def getsize_multiline( """ .. deprecated:: 9.2.0 - For more information, see - https://pillow.readthedocs.io/en/stable/releasenotes/9.2.0.html#deprecations. + See :ref:`deprecations ` for more information. Use :py:meth:`.ImageDraw.multiline_textbbox` instead. @@ -566,8 +563,7 @@ def getoffset(self, text): """ .. deprecated:: 9.2.0 - For more information, see - https://pillow.readthedocs.io/en/stable/releasenotes/9.2.0.html#deprecations. + See :ref:`deprecations ` for more information. Use :py:meth:`.getbbox` instead. @@ -863,8 +859,7 @@ def getsize(self, text, *args, **kwargs): """ .. deprecated:: 9.2.0 - For more information, see - https://pillow.readthedocs.io/en/stable/releasenotes/9.2.0.html#deprecations. + See :ref:`deprecations ` for more information. Use :py:meth:`.getbbox` or :py:meth:`.getlength` instead. """ From 7359af91f05e72a20b35ae62cc0cdc95e5424ea1 Mon Sep 17 00:00:00 2001 From: Andrew Murray <3112309+radarhere@users.noreply.github.com> Date: Tue, 6 Sep 2022 16:18:55 +1000 Subject: [PATCH 5/6] Rearranged text Co-authored-by: Hugo van Kemenade --- src/PIL/ImageFont.py | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/src/PIL/ImageFont.py b/src/PIL/ImageFont.py index c1b7435f363..4df89755be9 100644 --- a/src/PIL/ImageFont.py +++ b/src/PIL/ImageFont.py @@ -430,12 +430,12 @@ def getsize( """ .. deprecated:: 9.2.0 - See :ref:`deprecations ` for more information. - Use :py:meth:`getlength()` to measure the offset of following text with 1/64 pixel precision. Use :py:meth:`getbbox()` to get the exact bounding box based on an anchor. + See :ref:`deprecations ` for more information. + Returns width and height (in pixels) of given text if rendered in font with provided direction, features, and language. @@ -502,10 +502,10 @@ def getsize_multiline( """ .. deprecated:: 9.2.0 - See :ref:`deprecations ` for more information. - Use :py:meth:`.ImageDraw.multiline_textbbox` instead. + See :ref:`deprecations ` for more information. + Returns width and height (in pixels) of given text if rendered in font with provided direction, features, and language, while respecting newline characters. @@ -563,10 +563,10 @@ def getoffset(self, text): """ .. deprecated:: 9.2.0 - See :ref:`deprecations ` for more information. - Use :py:meth:`.getbbox` instead. + See :ref:`deprecations ` for more information. + Returns the offset of given text. This is the gap between the starting coordinate and the first marking. Note that this gap is included in the result of :py:func:`~PIL.ImageFont.FreeTypeFont.getsize`. @@ -859,9 +859,9 @@ def getsize(self, text, *args, **kwargs): """ .. deprecated:: 9.2.0 - See :ref:`deprecations ` for more information. - Use :py:meth:`.getbbox` or :py:meth:`.getlength` instead. + + See :ref:`deprecations ` for more information. """ deprecate("getsize", 10, "getbbox or getlength") with warnings.catch_warnings(): From bce9df62f1dd17c93c2615a24b34b22f2688cfac Mon Sep 17 00:00:00 2001 From: Andrew Murray <3112309+radarhere@users.noreply.github.com> Date: Tue, 6 Sep 2022 16:19:47 +1000 Subject: [PATCH 6/6] Rearranged text Co-authored-by: Hugo van Kemenade --- src/PIL/ImageFont.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/PIL/ImageFont.py b/src/PIL/ImageFont.py index 4df89755be9..04da64b9f46 100644 --- a/src/PIL/ImageFont.py +++ b/src/PIL/ImageFont.py @@ -139,10 +139,10 @@ def getsize(self, text, *args, **kwargs): """ .. deprecated:: 9.2.0 - See :ref:`deprecations ` for more information. - Use :py:meth:`.getbbox` or :py:meth:`.getlength` instead. + See :ref:`deprecations ` for more information. + Returns width and height (in pixels) of given text. :param text: Text to measure.