ENH: _writer: Add method to scale and wrap text

This patch adds a method to scale and wrap text,
depending on whether or not text is allowed to be
wrapped.

It takes a couple of arguments, including the text
string itself, field width and height, font size,
a dictionary with character widths, and a bool
specifying whether or not text is allowed to wrap.

Returns a list of lines and a font size.

Author: PJBrs

pypdf/_writer.py

@@ -3432,6 +3432,107 @@ def calculate_text_width(character_widths: dict[str, int], font_size: float, txt
     return (total_font_units_width * font_size) / 1000.0
 
 
+def scale_text(
+    font_descriptor: FontDescriptor,
+    font_size: float,
+    field_width: float,
+    field_height: float,
+    txt: str,
+    wrap_lines: bool,
+    min_font_size: float = 4.0,       # Minimum font size to attempt
+    font_size_step: float = 0.2       # How much to decrease font size by each step
+) -> tuple[list[str], float]:
+    """
+    Takes a piece of text and scales it to field_width or field_height, given font_name
+    and font_size. For multiline fields, adds newlines to wrap the text.
+
+    Args:
+        font_descriptor: A FontDescriptor for the font to be used.
+        font_size: The font size in points.
+        field_width: The width of the field in which to fit the text.
+        field_height: The height of the field in which to fit the text.
+        txt: The text to fit with the field.
+        wrap_lines: Whether to scale and wrap the text, or only to scale.
+        min_font_size: The minimum font size at which to scale the text.
+        font_size_step: The amount by which to decrement font size per step while scaling.
+
+    Returns:
+        The text in terms of a list of wrapped_lines at a certain font_size.
+    """
+    # Single line:
+    if not wrap_lines:
+        test_width = calculate_text_width(font_descriptor.character_widths, font_size, txt)
+        if test_width > field_width or font_size > field_height:
+            new_font_size = font_size - font_size_step
+            if new_font_size >= min_font_size:
+                # Text overflows height; Retry with smaller font size.
+                return scale_text(
+                    font_descriptor,
+                    new_font_size,
+                    field_width,
+                    field_height,
+                    txt,
+                    wrap_lines,
+                    min_font_size,
+                    font_size_step
+                )
+            # Font size lower than set minimum font size, give up.
+            return [txt], round(font_size, 1)
+        return [txt], round(font_size, 1)
+    # Multiline:
+    orig_txt = txt
+    paragraphs = re.sub(r"\n", "\r", txt).split("\r")
+    wrapped_lines = []
+    current_line_words: list[str] = []
+    current_line_width: float = 0
+    for paragraph in paragraphs:
+        if not paragraph.strip():
+            wrapped_lines.append("")
+            continue
+        words = paragraph.split(" ")
+        for i, word in enumerate(words):
+            word_width = calculate_text_width(font_descriptor.character_widths, font_size, word)
+            space_width = calculate_text_width(font_descriptor.character_widths, font_size, " ") if i > 0 else 0
+            test_width = current_line_width + space_width + word_width
+            if test_width > field_width and current_line_words:
+                wrapped_lines.append(" ".join(current_line_words))
+                current_line_words = [word]
+                current_line_width = word_width
+            elif not current_line_words and word_width > field_width:
+                wrapped_lines.append(word)
+                current_line_words = []
+                current_line_width = 0
+            else:
+                if current_line_words:
+                    current_line_width += space_width
+                current_line_words.append(word)
+                current_line_width += word_width
+        if current_line_words:
+            wrapped_lines.append(" ".join(current_line_words))
+            current_line_words = []
+            current_line_width = 0
+    # Estimate total height.
+    # Assumed line spacing of 1.4
+    estimated_total_height = font_size + (len(wrapped_lines) - 1) * 1.4 * font_size
+    if estimated_total_height > field_height:
+        new_font_size = font_size - font_size_step
+        if new_font_size >= min_font_size:
+            # Text overflows height; Retry with smaller font size.
+            return scale_text(
+                font_descriptor,
+                new_font_size,
+                field_width,
+                field_height,
+                orig_txt,
+                wrap_lines,
+                min_font_size,
+                font_size_step
+            )
+        # Font size lower than set minimum font size, give up.
+        return wrapped_lines, round(font_size, 1)
+    return wrapped_lines, round(font_size, 1)
+
+
 def generate_appearance_stream(
     txt: str,
     sel: list[str],

tests/test_writer.py

@@ -19,6 +19,8 @@
     PdfWriter,
     Transformation,
 )
+from pypdf._font import FontDescriptor
+from pypdf._writer import scale_text
 from pypdf.annotations import Link
 from pypdf.errors import DeprecationError, PageSizeNotDefinedError, PyPdfError
 from pypdf.generic import (
@@ -1650,6 +1652,44 @@ def test_merge_content_stream_to_page():
     assert contents[1].get_object().get_data() == more_content
 
 
+def test_scale_text():
+    font_res = DictionaryObject({NameObject("/BaseFont"): NameObject("/Helvetica")})
+    my_font = FontDescriptor.from_font_resource(font_res)
+    field_width = 55.4
+    field_height = 9.1
+    font_size = 10.1
+    txt = "Hello World"
+    wrap_lines = False
+    lines, font_height = scale_text(my_font, font_size, field_width - 3, field_height - 3, txt, wrap_lines)
+    assert font_height == 5.9
+    txt = "This is a very very long sentence that probably will scale below the minimum font size"
+    lines, font_height = scale_text(my_font, font_size, field_width - 3, field_height - 3, txt, wrap_lines)
+    assert font_height == 4.1
+    field_width = 160
+    field_height = 360
+    font_size = 12.0
+    txt = """Welcome to pypdf
+pypdf is a free and open source pure-python PDF library capable of splitting, merging, cropping, and
+transforming the pages of PDF files. It can also add custom data, viewing options, and passwords to PDF
+files. pypdf can retrieve text and metadata from PDFs as well.
+
+See pdfly for a CLI application that uses pypdf to interact with PDFs.
+    """
+    wrap_lines = True
+    lines, font_height = scale_text(my_font, font_size, field_width - 3, field_height - 3, txt, wrap_lines)
+    assert font_height == 12.0
+    assert lines[1] == "pypdf is a free and open"
+    field_height = 160
+    lines, font_height = scale_text(my_font, font_size, field_width - 3, field_height - 3, txt, wrap_lines)
+    assert font_height == 8.8
+    field_height = 12
+    lines, font_height = scale_text(my_font, font_size, field_width - 3, field_height - 3, txt, wrap_lines)
+    assert font_height == 4.0
+    txt = "pneumonoultramicroscopicsilicovolcanoconiosis"
+    lines, font_height = scale_text(my_font, font_size, field_width - 3, field_height - 3, txt, wrap_lines)
+    assert font_height == 8.8
+
+
 @pytest.mark.enable_socket
 def test_update_form_fields2():
     my_files = {