ENH: Parse and format comb fields in text widget annotations (#3519)

This patch implements comb-formatted appearance streams.

Closes #2153.

Author: PJBrs

pypdf/generic/_appearance_stream.py

@@ -145,7 +145,9 @@ def _generate_appearance_stream_data(
         font_size: float = 0.0,
         font_color: str = "0 g",
         is_multiline: bool = False,
-        alignment: TextAlignment = TextAlignment.LEFT
+        alignment: TextAlignment = TextAlignment.LEFT,
+        is_comb: bool = False,
+        max_length: Optional[int] = None
     ) -> bytes:
         """
         Generates the raw bytes of the PDF appearance stream for a text field.
@@ -168,6 +170,10 @@ def _generate_appearance_stream_data(
                 graphics state string (e.g., "0 g" for black).
             is_multiline: A boolean indicating if the text field is multiline.
             alignment: Text alignment, can be TextAlignment.LEFT, .RIGHT, or .CENTER.
+            is_comb: Boolean that designates fixed-length fields, where every character
+                fills one "cell", such as in a postcode.
+            max_length: Used if is_comb is set. The maximum number of characters for a fixed-
+                length field.
 
         Returns:
             A byte string containing the PDF content stream data.
@@ -196,6 +202,17 @@ def _generate_appearance_stream_data(
                 text,
                 is_multiline,
             )
+        elif is_comb:
+            if max_length and len(text) > max_length:
+                logger_warning (
+                    f"Length of text {text} exceeds maximum length ({max_length}) of field, input truncated.",
+                    __name__
+                )
+            # We act as if each character is one line, because we draw it separately later on
+            lines = [(
+                font_descriptor.text_width(char) * font_size / 1000,
+                char
+            ) for index, char in enumerate(text) if index < (max_length or len(text))]
         else:
             lines = [(
                 font_descriptor.text_width(line) * font_size / 1000,
@@ -222,7 +239,15 @@ def _generate_appearance_stream_data(
 
             # Calculate the desired absolute starting X for the current line
             desired_abs_x_start: float = 0
-            if alignment == TextAlignment.RIGHT:
+            if is_comb and max_length:
+                # Calculate the width of a cell for one character
+                cell_width = rectangle.width / max_length
+                # Space from the left edge of the cell to the character's baseline start
+                # line_width here is the *actual* character width in points for the single character 'line'
+                centering_offset_in_cell = (cell_width - line_width) / 2
+                # Absolute start X = (Cell Index, i.e., line_number * Cell Width) + Centering Offset
+                desired_abs_x_start = (line_number * cell_width) + centering_offset_in_cell
+            elif alignment == TextAlignment.RIGHT:
                 desired_abs_x_start = rectangle.width - 2 - line_width
             elif alignment == TextAlignment.CENTER:
                 desired_abs_x_start = (rectangle.width - line_width) / 2
@@ -236,6 +261,8 @@ def _generate_appearance_stream_data(
             y_rel_offset: float = 0
             if line_number == 0:
                 y_rel_offset = y_offset  # Initial vertical position
+            elif is_comb:
+                 y_rel_offset = 0.0  # DO NOT move vertically for subsequent characters
             else:
                 y_rel_offset = - font_size * 1.4  # Move down by line height
 
@@ -266,7 +293,9 @@ def __init__(
         font_size: float = 0.0,
         font_color: str = "0 g",
         is_multiline: bool = False,
-        alignment: TextAlignment = TextAlignment.LEFT
+        alignment: TextAlignment = TextAlignment.LEFT,
+        is_comb: bool = False,
+        max_length: Optional[int] = None
     ) -> None:
         """
         Initializes a TextStreamAppearance object.
@@ -286,6 +315,10 @@ def __init__(
             font_color: The font color string.
             is_multiline: A boolean indicating if the text field is multiline.
             alignment: Text alignment, can be TextAlignment.LEFT, .RIGHT, or .CENTER.
+            is_comb: Boolean that designates fixed-length fields, where every character
+                fills one "cell", such as in a postcode.
+            max_length: Used if is_comb is set. The maximum number of characters for a fixed-
+                length field.
 
         """
         super().__init__()
@@ -331,11 +364,13 @@ def __init__(
             rectangle,
             font_descriptor,
             font_glyph_byte_map,
-            font_name,
-            font_size,
-            font_color,
-            is_multiline,
-            alignment
+            font_name=font_name,
+            font_size=font_size,
+            font_color=font_color,
+            is_multiline=is_multiline,
+            alignment=alignment,
+            is_comb=is_comb,
+            max_length=max_length
         )
 
         self[NameObject("/Type")] = NameObject("/XObject")
@@ -439,12 +474,8 @@ def from_text_annotation(
         if not is_null_or_none(font_resource):
             font_resource = cast(DictionaryObject, font_resource.get_object())
 
-        # Retrieve field text, selected values and formatting information
-        is_multiline = False
+        # Retrieve field text and selected values
         field_flags = field.get(FieldDictionaryAttributes.Ff, 0)
-        alignment = field.get("/Q", TextAlignment.LEFT)
-        if field_flags & FieldDictionaryAttributes.FfBits.Multiline:
-            is_multiline = True
         if (
                 field.get(FieldDictionaryAttributes.FT, "/Tx") == "/Ch" and
                 field_flags & FieldDictionaryAttributes.FfBits.Combo == 0
@@ -460,17 +491,30 @@ def from_text_annotation(
         # Escape parentheses (PDF 1.7 reference, table 3.2, Literal Strings)
         text = text.replace("\\", "\\\\").replace("(", r"\(").replace(")", r"\)")
 
+        # Retrieve formatting information
+        is_comb = False
+        max_length = None
+        if field_flags & FieldDictionaryAttributes.FfBits.Comb:
+            is_comb = True
+            max_length = annotation.get("/MaxLen")
+        is_multiline = False
+        if field_flags & FieldDictionaryAttributes.FfBits.Multiline:
+            is_multiline = True
+        alignment = field.get("/Q", TextAlignment.LEFT)
+
         # Create the TextStreamAppearance instance
         new_appearance_stream = cls(
             text,
             selection,
             rectangle,
             font_resource,
-            font_name,
-            font_size,
-            font_color,
-            is_multiline,
-            alignment
+            font_name=font_name,
+            font_size=font_size,
+            font_color=font_color,
+            is_multiline=is_multiline,
+            alignment=alignment,
+            is_comb=is_comb,
+            max_length=max_length
         )
         if AnnotationDictionaryAttributes.AP in annotation:
             for key, value in (

tests/test_appearance_stream.py

@@ -3,6 +3,38 @@
 from pypdf.generic._appearance_stream import TextStreamAppearance
 
 
+def test_comb():
+    rectangle = (0.0, 0.0, 197.285, 18.455)
+    font_size = 10.0
+    text = "01234567"
+    max_length = 10
+    is_comb = True
+    appearance_stream = TextStreamAppearance(
+        text, rectangle=rectangle, font_size=font_size, is_comb=is_comb, max_length=max_length
+    )
+    assert appearance_stream.get_data() == (
+        b"q\n/Tx BMC \nq\n1 1 196.285 17.455 re\nW\nBT\n/Helv 10.0 Tf 0 g\n"
+        b"7.084250000000001 7.454999999999998 Td\n(0) Tj\n"
+        b"19.7285 0.0 Td\n(1) Tj\n"
+        b"19.728500000000004 0.0 Td\n(2) Tj\n"
+        b"19.728499999999997 0.0 Td\n(3) Tj\n"
+        b"19.728499999999997 0.0 Td\n(4) Tj\n"
+        b"19.728499999999997 0.0 Td\n(5) Tj\n"
+        b"19.72850000000001 0.0 Td\n(6) Tj\n"
+        b"19.728499999999997 0.0 Td\n(7) Tj\nET\nQ\nEMC\nQ\n"
+    )
+
+    rectangle = (0.0, 0.0, 20.852, 20.84)
+    text = "AA"
+    max_length = 1
+    appearance_stream = TextStreamAppearance(
+        text, rectangle=rectangle, font_size=font_size, is_comb=is_comb, max_length=max_length
+    )
+    assert appearance_stream.get_data() == (
+        b"q\n/Tx BMC \nq\n1 1 19.852 19.84 re\nW\nBT\n/Helv 10.0 Tf 0 g\n7.091 9.84 Td\n(A) Tj\nET\nQ\nEMC\nQ\n"
+    )
+
+
 def test_scale_text():
     rectangle = (0, 0, 9.1, 55.4)
     font_size = 10.1