Merge pull request #6556 from radarhere/returns

Improved documentation of ImageDraw return values

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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -197,6 +199,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
 ----------------
 

docs/reference/ImageDraw.rst

@@ -443,6 +443,8 @@ Methods
 
     .. deprecated:: 9.2.0
 
+    See :ref:`deprecations <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.
@@ -489,10 +491,14 @@ Methods
 
                      .. versionadded:: 6.2.0
 
+    :return: (width, height)
+
 .. py:method:: ImageDraw.multiline_textsize(text, font=None, spacing=4, direction=None, features=None, language=None, stroke_width=0)
 
     .. deprecated:: 9.2.0
 
+    See :ref:`deprecations <Font size and offset methods>` for more information.
+
     Use :py:meth:`.multiline_textbbox` instead.
 
     Return the size of the given string, in pixels.
@@ -541,6 +547,8 @@ Methods
 
                      .. versionadded:: 6.2.0
 
+    :return: (width, height)
+
 .. 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 +616,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).
+    :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)
 
@@ -657,6 +666,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).
+    :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)
 
@@ -700,6 +710,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).
+    :return: ``(left, top, right, bottom)`` bounding box
 
 .. py:method:: getdraw(im=None, hints=None)
 

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
 =============
 

src/PIL/ImageFont.py

@@ -141,6 +141,8 @@ def getsize(self, text, *args, **kwargs):
 
         Use :py:meth:`.getbbox` or :py:meth:`.getlength` instead.
 
+        See :ref:`deprecations <Font size and offset methods>` for more information.
+
         Returns width and height (in pixels) of given text.
 
         :param text: Text to measure.
@@ -432,6 +434,8 @@ def getsize(
         1/64 pixel precision.
         Use :py:meth:`getbbox()` to get the exact bounding box based on an anchor.
 
+        See :ref:`deprecations <Font size and offset methods>` for more information.
+
         Returns width and height (in pixels) of given text if rendered in font with
         provided direction, features, and language.
 
@@ -500,6 +504,8 @@ def getsize_multiline(
 
         Use :py:meth:`.ImageDraw.multiline_textbbox` instead.
 
+        See :ref:`deprecations <Font size and offset methods>` 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.
@@ -559,6 +565,8 @@ def getoffset(self, text):
 
         Use :py:meth:`.getbbox` instead.
 
+        See :ref:`deprecations <Font size and offset methods>` 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`.
@@ -852,6 +860,8 @@ def getsize(self, text, *args, **kwargs):
         .. deprecated:: 9.2.0
 
         Use :py:meth:`.getbbox` or :py:meth:`.getlength` instead.
+
+        See :ref:`deprecations <Font size and offset methods>` for more information.
         """
         deprecate("getsize", 10, "getbbox or getlength")
         with warnings.catch_warnings():