Add ImageText.Text.wrap() to wrap text (#9286)

Author: hugovk

Tests/test_imagetext.py

@@ -108,3 +108,123 @@ def test_stroke() -> None:
         assert_image_similar_tofile(
             im, "Tests/images/imagedraw_stroke_" + suffix + ".png", 3.1
         )
+
+
+@pytest.mark.parametrize(
+    "data, width, expected",
+    (
+        ("Hello World!", 100, "Hello World!"),  # No wrap required
+        ("Hello World!", 50, "Hello\nWorld!"),  # Wrap word to a new line
+        # Keep multiple spaces within a line
+        ("Keep  multiple spaces", 90, "Keep  multiple\nspaces"),
+        (" Keep\n leading space", 100, " Keep\n leading space"),
+    ),
+)
+@pytest.mark.parametrize("string", (True, False))
+def test_wrap(data: str, width: int, expected: str, string: bool) -> None:
+    if string:
+        text = ImageText.Text(data)
+        assert text.wrap(width) is None
+        assert text.text == expected
+    else:
+        text_bytes = ImageText.Text(data.encode())
+        assert text_bytes.wrap(width) is None
+        assert text_bytes.text == expected.encode()
+
+
+def test_wrap_long_word() -> None:
+    text = ImageText.Text("Hello World!")
+    with pytest.raises(ValueError, match="Word does not fit within line"):
+        text.wrap(25)
+
+
+def test_wrap_unsupported(font: ImageFont.FreeTypeFont) -> None:
+    transposed_font = ImageFont.TransposedFont(font)
+    text = ImageText.Text("Hello World!", transposed_font)
+    with pytest.raises(ValueError, match="TransposedFont not supported"):
+        text.wrap(50)
+
+    text = ImageText.Text("Hello World!", direction="ttb")
+    with pytest.raises(ValueError, match="Only ltr direction supported"):
+        text.wrap(50)
+
+
+def test_wrap_height() -> None:
+    width = 50 if features.check_module("freetype2") else 60
+    text = ImageText.Text("Text does not fit within height")
+    wrapped = text.wrap(width, 25 if features.check_module("freetype2") else 40)
+    assert wrapped is not None
+    assert wrapped.text == " within height"
+    assert text.text == "Text does\nnot fit"
+
+    text = ImageText.Text("Text does not fit\nwithin height")
+    wrapped = text.wrap(width, 20)
+    assert wrapped is not None
+    assert wrapped.text == " not fit\nwithin height"
+    assert text.text == "Text does"
+
+    text = ImageText.Text("Text does not fit\n\nwithin height")
+    wrapped = text.wrap(width, 25 if features.check_module("freetype2") else 40)
+    assert wrapped is not None
+    assert wrapped.text == "\nwithin height"
+    assert text.text == "Text does\nnot fit"
+
+
+def test_wrap_scaling_unsupported() -> None:
+    font = ImageFont.load_default_imagefont()
+    text = ImageText.Text("Hello World!", font)
+    with pytest.raises(ValueError, match="'scaling' only supports FreeTypeFont"):
+        text.wrap(50, scaling="shrink")
+
+    if features.check_module("freetype2"):
+        text = ImageText.Text("Hello World!")
+        with pytest.raises(ValueError, match="'scaling' requires 'height'"):
+            text.wrap(50, scaling="shrink")
+
+
+@skip_unless_feature("freetype2")
+def test_wrap_shrink() -> None:
+    # No scaling required
+    text = ImageText.Text("Hello World!")
+    assert isinstance(text.font, ImageFont.FreeTypeFont)
+    assert text.font.size == 10
+    assert text.wrap(50, 50, "shrink") is None
+    assert isinstance(text.font, ImageFont.FreeTypeFont)
+    assert text.font.size == 10
+
+    with pytest.raises(ValueError, match="Text could not be scaled"):
+        text.wrap(50, 15, ("shrink", 9))
+
+    assert text.wrap(50, 15, "shrink") is None
+    assert text.font.size == 8
+
+    text = ImageText.Text("Hello World!")
+    assert text.wrap(50, 15, ("shrink", 7)) is None
+    assert isinstance(text.font, ImageFont.FreeTypeFont)
+    assert text.font.size == 8
+
+
+@skip_unless_feature("freetype2")
+def test_wrap_grow() -> None:
+    # No scaling required
+    text = ImageText.Text("Hello World!")
+    assert isinstance(text.font, ImageFont.FreeTypeFont)
+    assert text.font.size == 10
+    assert text.wrap(58, 10, "grow") is None
+    assert isinstance(text.font, ImageFont.FreeTypeFont)
+    assert text.font.size == 10
+
+    with pytest.raises(ValueError, match="Text could not be scaled"):
+        text.wrap(50, 50, ("grow", 12))
+
+    assert text.wrap(50, 50, "grow") is None
+    assert text.font.size == 16
+
+    text = ImageText.Text("A\nB")
+    with pytest.raises(ValueError, match="Text could not be scaled"):
+        text.wrap(50, 10, "grow")
+
+    text = ImageText.Text("Hello World!")
+    assert text.wrap(50, 50, ("grow", 18)) is None
+    assert isinstance(text.font, ImageFont.FreeTypeFont)
+    assert text.font.size == 16

docs/releasenotes/12.2.0.rst

@@ -42,6 +42,31 @@ FontFile.to_imagefont()
     ...
     <PIL.ImageFont.ImageFont object at 0x10457bb80>
 
+ImageText.Text.wrap
+^^^^^^^^^^^^^^^^^^^
+
+:py:meth:`.ImageText.Text.wrap` has been added, to wrap text to fit within a given
+width::
+
+    from PIL import ImageText
+    text = ImageText.Text("Hello World!")
+    text.wrap(50)
+    print(text.text)  # "Hello\nWorld!"
+
+or within a certain width and height, returning a new :py:class:`.ImageText.Text`
+instance if the text does not fit::
+
+    text = ImageText.Text("Text does not fit within height")
+    print(text.wrap(50, 25).text == " within height")
+    print(text.text)  # "Text does\nnot fit"
+
+or scaling, optionally with a font size limit::
+
+    text.wrap(50, 15, "shrink")
+    text.wrap(50, 15, ("shrink", 7))
+    text.wrap(58, 10, "grow")
+    text.wrap(50, 50, ("grow", 12))
+
 Other changes
 =============
 

src/PIL/ImageDraw.py

@@ -538,7 +538,7 @@ def draw_corners(pieslice: bool) -> None:
     def text(
         self,
         xy: tuple[float, float],
-        text: AnyStr | ImageText.Text,
+        text: AnyStr | ImageText.Text[AnyStr],
         fill: _Ink | None = None,
         font: (
             ImageFont.ImageFont
@@ -591,61 +591,62 @@ def getink(fill: _Ink | None) -> int:
                 else ink
             )
 
-        for xy, anchor, line in image_text._split(xy, anchor, align):
+        for line in image_text._split(xy, anchor, align):
 
             def draw_text(ink: int, stroke_width: float = 0) -> None:
                 mode = self.fontmode
                 if stroke_width == 0 and embedded_color:
                     mode = "RGBA"
-                coord = [int(xy[i]) for i in range(2)]
-                start = (math.modf(xy[0])[0], math.modf(xy[1])[0])
+                x = int(line.x)
+                y = int(line.y)
+                start = (math.modf(line.x)[0], math.modf(line.y)[0])
                 try:
                     mask, offset = image_text.font.getmask2(  # type: ignore[union-attr,misc]
-                        line,
+                        line.text,
                         mode,
                         direction=direction,
                         features=features,
                         language=language,
                         stroke_width=stroke_width,
                         stroke_filled=True,
-                        anchor=anchor,
+                        anchor=line.anchor,
                         ink=ink,
                         start=start,
                         *args,
                         **kwargs,
                     )
-                    coord = [coord[0] + offset[0], coord[1] + offset[1]]
+                    x += offset[0]
+                    y += offset[1]
                 except AttributeError:
                     try:
                         mask = image_text.font.getmask(  # type: ignore[misc]
-                            line,
+                            line.text,
                             mode,
                             direction,
                             features,
                             language,
                             stroke_width,
-                            anchor,
+                            line.anchor,
                             ink,
                             start=start,
                             *args,
                             **kwargs,
                         )
                     except TypeError:
-                        mask = image_text.font.getmask(line)
+                        mask = image_text.font.getmask(line.text)
                 if mode == "RGBA":
                     # image_text.font.getmask2(mode="RGBA")
                     # returns color in RGB bands and mask in A
                     # extract mask and set text alpha
                     color, mask = mask, mask.getband(3)
                     ink_alpha = struct.pack("i", ink)[3]
                     color.fillband(3, ink_alpha)
-                    x, y = coord
                     if self.im is not None:
                         self.im.paste(
                             color, (x, y, x + mask.size[0], y + mask.size[1]), mask
                         )
                 else:
-                    self.draw.draw_bitmap(coord, mask, ink)
+                    self.draw.draw_bitmap((x, y), mask, ink)
 
             if stroke_ink is not None:
                 # Draw stroked text