ENH: _appearance_stream: Use kwargs instead of long argument lists

Author: PJBrs

pypdf/generic/_appearance_stream.py

@@ -139,15 +139,7 @@ def _generate_appearance_stream_data(
         text: str = "",
         selection: Optional[list[str]] = None,
         rectangle: Union[RectangleObject, tuple[float, float, float, float]] = (0.0, 0.0, 0.0, 0.0),
-        font_descriptor: Optional[FontDescriptor] = None,
-        font_glyph_byte_map: Optional[dict[str, bytes]] = None,
-        font_name: str = "/Helv",
-        font_size: float = 0.0,
-        font_color: str = "0 g",
-        is_multiline: bool = False,
-        alignment: TextAlignment = TextAlignment.LEFT,
-        is_comb: bool = False,
-        max_length: Optional[int] = None
+        **formatting_kwargs: Any
     ) -> bytes:
         """
         Generates the raw bytes of the PDF appearance stream for a text field.
@@ -159,30 +151,38 @@ def _generate_appearance_stream_data(
         Args:
             text: The text to be rendered in the form field.
             selection: An optional list of strings that should be highlighted as selected.
-            font_glyph_byte_map: An optional dictionary mapping characters to their
-                byte representation for glyph encoding.
             rect: The bounding box of the form field. Can be a `RectangleObject`
                 or a tuple of four floats (x1, y1, x2, y2).
-            font_name: The name of the font resource to use (e.g., "/Helv").
-            font_size: The font size. If 0, it is automatically calculated
-                based on whether the field is multiline or not.
-            font_color: The color to apply to the font, represented as a PDF
-                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.
+            **formatting_kwargs: A series of keyword arguments that describe how the
+                appearance stream should be formatted. Can include the following:
+                font_descriptor: The font descriptor associated with the font resource.
+                font_glyph_byte_map: An optional dictionary mapping characters to their
+                    byte representation for glyph encoding.
+                font_name: The name of the font resource, e.g., "/Helv".
+                font_size: The font size. If 0, it's auto-calculated.
+                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.
 
         Returns:
             A byte string containing the PDF content stream data.
 
         """
-        font_glyph_byte_map = font_glyph_byte_map or {}
         if isinstance(rectangle, tuple):
             rectangle = RectangleObject(rectangle)
-        font_descriptor = cast(FontDescriptor, font_descriptor)
+        font_descriptor = cast(FontDescriptor, formatting_kwargs.get("font_descriptor"))
+        font_glyph_byte_map = formatting_kwargs.get("font_glyph_byte_map", {})
+        font_name = formatting_kwargs.get("font_name")
+        font_size = formatting_kwargs.get("font_size", 0.0)
+        font_color = formatting_kwargs.get("font_color", "0 g")
+        is_multiline = formatting_kwargs.get("is_multiline", False)
+        alignment = formatting_kwargs.get("alignment", TextAlignment.LEFT)
+        is_comb = formatting_kwargs.get("is_comb", False)
+        max_length = formatting_kwargs.get("max_length", len(text))
 
         # If font_size is 0, apply the logic for multiline or large-as-possible font
         if font_size == 0:
@@ -203,7 +203,7 @@ def _generate_appearance_stream_data(
                 is_multiline,
             )
         elif is_comb:
-            if max_length and len(text) > max_length:
+            if len(text) > max_length:
                 logger_warning (
                     f"Length of text {text} exceeds maximum length ({max_length}) of field, input truncated.",
                     __name__
@@ -212,7 +212,7 @@ def _generate_appearance_stream_data(
             lines = [(
                 font_descriptor.text_width(char) * font_size / 1000,
                 char
-            ) for index, char in enumerate(text) if index < (max_length or len(text))]
+            ) for index, char in enumerate(text) if index < max_length]
         else:
             lines = [(
                 font_descriptor.text_width(line) * font_size / 1000,
@@ -288,14 +288,7 @@ def __init__(
         text: str = "",
         selection: Optional[list[str]] = None,
         rectangle: Union[RectangleObject, tuple[float, float, float, float]] = (0.0, 0.0, 0.0, 0.0),
-        font_resource: Optional[DictionaryObject] = None,
-        font_name: str = "/Helv",
-        font_size: float = 0.0,
-        font_color: str = "0 g",
-        is_multiline: bool = False,
-        alignment: TextAlignment = TextAlignment.LEFT,
-        is_comb: bool = False,
-        max_length: Optional[int] = None
+        **formatting_kwargs: Any,
     ) -> None:
         """
         Initializes a TextStreamAppearance object.
@@ -307,28 +300,33 @@ def __init__(
         Args:
             text: The text to be rendered in the form field.
             selection: An optional list of strings that should be highlighted as selected.
-            rect: The bounding box of the form field. Can be a `RectangleObject`
+            rectangle: The bounding box of the form field. Can be a `RectangleObject`
                 or a tuple of four floats (x1, y1, x2, y2).
-            font_resource: An optional variable that represents a PDF font dictionary.
-            font_name: The name of the font resource, e.g., "/Helv".
-            font_size: The font size. If 0, it's auto-calculated.
-            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.
-
+            **formatting_kwargs: A series of keyword arguments that describe how the
+                appearance stream should be formatted. Can include the following:
+                font_resource: An optional variable that represents a PDF font dictionary.
+                font_name: The name of the font resource, e.g., "/Helv".
+                font_size: The font size. If 0, it's auto-calculated.
+                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__()
 
         # If a font resource was added, get the font character map
-        if font_resource:
-            font_resource = cast(DictionaryObject, font_resource.get_object())
+        if formatting_kwargs.get("font_resource"):
+            font_resource = cast(DictionaryObject, formatting_kwargs["font_resource"].get_object())
             font_descriptor = FontDescriptor.from_font_resource(font_resource)
+            font_name = formatting_kwargs.get("font_name")
         else:
-            logger_warning(f"Font dictionary for {font_name} not found; defaulting to Helvetica.", __name__)
+            logger_warning(
+                f'Font dictionary for {formatting_kwargs.get("font_name")} not found; '
+                "defaulting to Helvetica.", __name__
+            )
             font_name = "/Helv"
             font_resource = DictionaryObject({
                 NameObject("/Subtype"): NameObject("/Type1"),
@@ -339,6 +337,9 @@ def __init__(
             })
             font_descriptor = CORE_FONT_METRICS["Helvetica"]
 
+        formatting_kwargs.pop("font_resource", None)
+        formatting_kwargs.pop("font_name", None)
+
         # Get the font glyph data
         _font_subtype, _, font_encoding, font_map = build_char_map_from_dict(
             200, font_resource
@@ -362,15 +363,10 @@ def __init__(
             text,
             selection,
             rectangle,
-            font_descriptor,
-            font_glyph_byte_map,
-            font_name,
-            font_size,
-            font_color,
-            is_multiline,
-            alignment,
-            is_comb,
-            max_length
+            font_descriptor=font_descriptor,
+            font_glyph_byte_map=font_glyph_byte_map,
+            font_name=font_name,
+            **formatting_kwargs
         )
 
         self[NameObject("/Type")] = NameObject("/XObject")
@@ -507,14 +503,14 @@ def from_text_annotation(
             text,
             selection,
             rectangle,
-            font_resource,
-            font_name,
-            font_size,
-            font_color,
-            is_multiline,
-            alignment,
-            is_comb,
-            max_length
+            font_resource=font_resource,
+            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 (