Improved documentation

docs/reference/ImageDraw.rst

@@ -582,6 +582,8 @@ Methods
         hello_world = hello + world  # kerning is disabled, no need to adjust
         assert hello_world == draw.textlength("HelloWorld", font, features=["-kern"])  # True
 
+    .. seealso:: :py:meth:`PIL.ImageText.Text.get_length`
+
     .. versionadded:: 8.0.0
 
     :param text: Text to be measured. May not contain any newline characters.
@@ -683,6 +685,8 @@ Methods
     1/64 pixel precision. The bounding box includes extra margins for
     some fonts, e.g. italics or accents.
 
+    .. seealso:: :py:meth:`PIL.ImageText.Text.get_bbox`
+
     .. versionadded:: 8.0.0
 
     :param xy: The anchor coordinates of the text.

docs/reference/ImageText.rst

@@ -4,9 +4,9 @@
 :py:mod:`~PIL.ImageText` module
 ===============================
 
-The :py:mod:`~PIL.ImageText` module defines a class with the same name. Instances of
-this class provide a way to use fonts with text strings or bytes. The result is a
-simple API to apply styling to pieces of text and measure or draw them.
+The :py:mod:`~PIL.ImageText` module defines a :py:class:`~PIL.ImageText.Text` class.
+Instances of this class provide a way to use fonts with text strings or bytes. The
+result is a simple API to apply styling to pieces of text and measure or draw them.
 
 Example
 -------
@@ -27,6 +27,33 @@ Example
     d = ImageDraw.Draw(im)
     d.text((0, 0), text, "#f00")
 
+Comparison
+----------
+
+Without ``ImageText.Text``::
+
+  from PIL import Image, ImageDraw
+  im = Image.new(mode, size)
+  d = ImageDraw.Draw(im)
+
+  d.textlength(text, font, direction, features, language, embedded_color)
+  d.multiline_textbbox(xy, text, font, anchor, spacing, align, direction, features, language, stroke_width, embedded_color)
+  d.text(xy, text, fill, font, anchor, spacing, align, direction, features, language, stroke_width, stroke_fill, embedded_color)
+
+With ``ImageText.Text``::
+
+  from PIL import ImageText
+  text = ImageText.Text(text, font, mode, spacing, direction, features, language)
+  text.embed_color()
+  text.stroke(stroke_width, stroke_fill)
+
+  text.get_length()
+  text.get_bbox(xy, anchor, align)
+
+  im = Image.new(mode, size)
+  d = ImageDraw.Draw(im)
+  d.text(xy, text, fill, anchor=anchor, align=align)
+
 Methods
 -------
 

docs/releasenotes/12.0.0.rst

@@ -124,6 +124,39 @@ Image.alpha_composite: LA images
 
 :py:meth:`~PIL.Image.alpha_composite` can now use LA images as well as RGBA.
 
+API additions
+=============
+
+Added ImageText.Text
+^^^^^^^^^^^^^^^^^^^^
+
+:py:class:`PIL.ImageText.Text` has been added, as a simpler way to use fonts with text
+strings or bytes.
+
+Without ``ImageText.Text``::
+
+  from PIL import Image, ImageDraw
+  im = Image.new(mode, size)
+  d = ImageDraw.Draw(im)
+
+  d.textlength(text, font, direction, features, language, embedded_color)
+  d.multiline_textbbox(xy, text, font, anchor, spacing, align, direction, features, language, stroke_width, embedded_color)
+  d.text(xy, text, fill, font, anchor, spacing, align, direction, features, language, stroke_width, stroke_fill, embedded_color)
+
+With ``ImageText.Text``::
+
+  from PIL import ImageText
+  text = ImageText.Text(text, font, mode, spacing, direction, features, language)
+  text.embed_color()
+  text.stroke(stroke_width, stroke_fill)
+
+  text.get_length()
+  text.get_bbox(xy, anchor, align)
+
+  im = Image.new(mode, size)
+  d = ImageDraw.Draw(im)
+  d.text(xy, text, fill, anchor=anchor, align=align)
+
 Other changes
 =============