MAINT: Refactor code from _writer to _appearance_stream

This patch introduces a new module - appearance_stream - and
copies two methods from _writer to this new module. Currently,
these methods are needed to develop an appearance stream for a
text annotation. They are:
update_field_annotation (renamed from _update_field_annotation)
generate_appearance_stream

The update_field_annotation was a PdfWriter method, which means
that the current code needs some refactoring, since it now has a
circular import of PdfWriter.

Other than changing self to writer in update_field_annotation,
and changing the code in PdfWriter to call update_field_annotation
from _appearance_stream, this patch changes nothing.

In a future change, we might want to make a class
TextAppearanceStream based on generate_appearance_stream, with
.from_annotation(Annotation) as a class method (based on
update_field_annotaion). scale_text would also be a method in
this class.

Author: PJBrs

pypdf/_writer.py

@@ -48,7 +48,6 @@
     cast,
 )
 
-from ._cmap import _default_fonts_space_width, build_char_map_from_dict
 from ._doc_common import DocumentInformation, PdfDocCommon
 from ._encryption import EncryptAlgorithm, Encryption
 from ._page import PageObject, Transformation
@@ -85,7 +84,6 @@
     BooleanObject,
     ByteStringObject,
     ContentStream,
-    DecodedStreamObject,
     Destination,
     DictionaryObject,
     EmbeddedFile,
@@ -107,6 +105,7 @@
     hex_to_rgb,
     is_null_or_none,
 )
+from .generic._appearance_stream import update_field_annotation
 from .pagerange import PageRange, PageRangeSpec
 from .types import (
     AnnotationSubtype,
@@ -907,157 +906,6 @@ def _add_apstream_object(
         xobject_drawing_commands = f"q\n{xobject_cm._to_cm()}\n{xobject_name} Do\nQ".encode()
         self._merge_content_stream_to_page(page, xobject_drawing_commands)
 
-    def _update_field_annotation(
-        self,
-        page: PageObject,
-        field: DictionaryObject,
-        annotation: DictionaryObject,
-        font_name: str = "",
-        font_size: float = -1,
-    ) -> StreamObject:
-        # Calculate rectangle dimensions
-        _rct = cast(RectangleObject, annotation[AA.Rect])
-        rct = RectangleObject((0, 0, abs(_rct[2] - _rct[0]), abs(_rct[3] - _rct[1])))
-
-        # Extract font information
-        da = annotation.get_inherited(
-            AA.DA,
-            cast(DictionaryObject, self.root_object[CatalogDictionary.ACRO_FORM]).get(
-                AA.DA, None
-            ),
-        )
-        if da is None:
-            da = TextStringObject("/Helv 0 Tf 0 g")
-        else:
-            da = da.get_object()
-        font_properties = da.replace("\n", " ").replace("\r", " ").split(" ")
-        font_properties = [x for x in font_properties if x != ""]
-        if font_name:
-            font_properties[font_properties.index("Tf") - 2] = font_name
-        else:
-            font_name = font_properties[font_properties.index("Tf") - 2]
-        font_height = (
-            font_size
-            if font_size >= 0
-            else float(font_properties[font_properties.index("Tf") - 1])
-        )
-        if font_height == 0:
-            if field.get(FA.Ff, 0) & FA.FfBits.Multiline:
-                font_height = DEFAULT_FONT_HEIGHT_IN_MULTILINE
-            else:
-                font_height = rct.height - 2
-        font_properties[font_properties.index("Tf") - 1] = str(font_height)
-        da = " ".join(font_properties)
-        y_offset = rct.height - 1 - font_height
-
-        # Retrieve font information from local DR ...
-        dr: Any = cast(
-            DictionaryObject,
-            cast(
-                DictionaryObject,
-                annotation.get_inherited(
-                    "/DR",
-                    cast(
-                        DictionaryObject, self.root_object[CatalogDictionary.ACRO_FORM]
-                    ).get("/DR", DictionaryObject()),
-                ),
-            ).get_object(),
-        )
-        dr = dr.get("/Font", DictionaryObject()).get_object()
-        # _default_fonts_space_width keys is the list of Standard fonts
-        if font_name not in dr and font_name not in _default_fonts_space_width:
-            # ...or AcroForm dictionary
-            dr = cast(
-                dict[Any, Any],
-                cast(
-                    DictionaryObject, self.root_object[CatalogDictionary.ACRO_FORM]
-                ).get("/DR", {}),
-            )
-            dr = dr.get_object().get("/Font", DictionaryObject()).get_object()
-        font_res = dr.get(font_name, None)
-        if not is_null_or_none(font_res):
-            font_res = cast(DictionaryObject, font_res.get_object())
-            _font_subtype, _, font_encoding, font_map = build_char_map_from_dict(
-                200, font_res
-            )
-            try:  # remove width stored in -1 key
-                del font_map[-1]
-            except KeyError:
-                pass
-            font_full_rev: dict[str, bytes]
-            if isinstance(font_encoding, str):
-                font_full_rev = {
-                    v: k.encode(font_encoding) for k, v in font_map.items()
-                }
-            else:
-                font_full_rev = {v: bytes((k,)) for k, v in font_encoding.items()}
-                font_encoding_rev = {v: bytes((k,)) for k, v in font_encoding.items()}
-                for key, value in font_map.items():
-                    font_full_rev[value] = font_encoding_rev.get(key, key)
-        else:
-            logger_warning(f"Font dictionary for {font_name} not found.", __name__)
-            font_full_rev = {}
-
-        # Retrieve field text and selected values
-        field_flags = field.get(FA.Ff, 0)
-        if field.get(FA.FT, "/Tx") == "/Ch" and field_flags & FA.FfBits.Combo == 0:
-            txt = "\n".join(annotation.get_inherited(FA.Opt, []))
-            sel = field.get("/V", [])
-            if not isinstance(sel, list):
-                sel = [sel]
-        else:  # /Tx
-            txt = field.get("/V", "")
-            sel = []
-        # Escape parentheses (PDF 1.7 reference, table 3.2, Literal Strings)
-        txt = txt.replace("\\", "\\\\").replace("(", r"\(").replace(")", r"\)")
-        # Generate appearance stream
-        ap_stream = generate_appearance_stream(
-            txt, sel, da, font_full_rev, rct, font_height, y_offset
-        )
-
-        # Create appearance dictionary
-        dct = DecodedStreamObject.initialize_from_dictionary(
-            {
-                NameObject("/Type"): NameObject("/XObject"),
-                NameObject("/Subtype"): NameObject("/Form"),
-                NameObject("/BBox"): rct,
-                "__streamdata__": ByteStringObject(ap_stream),
-                "/Length": 0,
-            }
-        )
-        if AA.AP in annotation:
-            for k, v in cast(DictionaryObject, annotation[AA.AP]).get("/N", {}).items():
-                if k not in {"/BBox", "/Length", "/Subtype", "/Type", "/Filter"}:
-                    dct[k] = v
-
-        # Update Resources with font information if necessary
-        if font_res is not None:
-            dct[NameObject("/Resources")] = DictionaryObject(
-                {
-                    NameObject("/Font"): DictionaryObject(
-                        {
-                            NameObject(font_name): getattr(
-                                font_res, "indirect_reference", font_res
-                            )
-                        }
-                    )
-                }
-            )
-        if AA.AP not in annotation:
-            annotation[NameObject(AA.AP)] = DictionaryObject(
-                {NameObject("/N"): self._add_object(dct)}
-            )
-        elif "/N" not in cast(DictionaryObject, annotation[AA.AP]):
-            cast(DictionaryObject, annotation[NameObject(AA.AP)])[
-                NameObject("/N")
-            ] = self._add_object(dct)
-        else:  # [/AP][/N] exists
-            n = annotation[AA.AP]["/N"].indirect_reference.idnum  # type: ignore
-            self._objects[n - 1] = dct
-            dct.indirect_reference = IndirectObject(n, 0, self)
-
-        return dct
-
     FFBITS_NUL = FA.FfBits(0)
 
     def update_page_form_field_values(
@@ -1170,12 +1018,12 @@ def update_page_form_field_values(
                 ):
                     # textbox
                     if isinstance(value, tuple):
-                        appearance_stream_obj = self._update_field_annotation(
-                            page, parent_annotation, annotation, value[1], value[2]
+                        appearance_stream_obj = update_field_annotation(
+                            self, page, parent_annotation, annotation, value[1], value[2]
                         )
                     else:
-                        appearance_stream_obj = self._update_field_annotation(
-                            page, parent_annotation, annotation
+                        appearance_stream_obj = update_field_annotation(
+                            self, page, parent_annotation, annotation
                             )
                 elif (
                     annotation.get(FA.FT) == "/Sig"
@@ -3409,36 +3257,3 @@ def _create_outline_item(
             format_flag += OutlineFontFlag.bold
         outline_item.update({NameObject("/F"): NumberObject(format_flag)})
     return outline_item
-
-
-def generate_appearance_stream(
-    txt: str,
-    sel: list[str],
-    da: str,
-    font_full_rev: dict[str, bytes],
-    rct: RectangleObject,
-    font_height: float,
-    y_offset: float,
-) -> bytes:
-    ap_stream = f"q\n/Tx BMC \nq\n1 1 {rct.width - 1} {rct.height - 1} re\nW\nBT\n{da}\n".encode()
-    for line_number, line in enumerate(txt.replace("\n", "\r").split("\r")):
-        if line in sel:
-            # may be improved but cannot find how to get fill working => replaced with lined box
-            ap_stream += (
-                f"1 {y_offset - (line_number * font_height * 1.4) - 1} {rct.width - 2} {font_height + 2} re\n"
-                f"0.5 0.5 0.5 rg s\n{da}\n"
-            ).encode()
-        if line_number == 0:
-            ap_stream += f"2 {y_offset} Td\n".encode()
-        else:
-            # Td is a relative translation
-            ap_stream += f"0 {- font_height * 1.4} Td\n".encode()
-        enc_line: list[bytes] = [
-            font_full_rev.get(c, c.encode("utf-16-be")) for c in line
-        ]
-        if any(len(c) >= 2 for c in enc_line):
-            ap_stream += b"<" + (b"".join(enc_line)).hex().encode() + b"> Tj\n"
-        else:
-            ap_stream += b"(" + b"".join(enc_line) + b") Tj\n"
-    ap_stream += b"ET\nQ\nEMC\nQ\n"
-    return ap_stream