Typing issue when updating from 3.9.1, suggested documentation update

[thomas-forte]

Explanation

While updating my app, something changed causing an error within pypdf. The issue was due to the dictionary of fields I was sending into update_page_form_field_values, that was previously a mix of strings, integers, and float values. I discovered the note in the doc-string that the function expected a string, list of strings or a tuple.

Correcting this fixed my issue, but it took some time to find as the error was nested, and that the typing on fields is Any, especially since floats worked previously.

Updating the typing from Any to the expected types could be helpful to anyone else with this problem. Or another suggestion would be to coerce to a string type on TextStringObject simply by calling str() on the value

Either way my issue is fixed, I love this package!

Code Example

pypdf/pypdf/_writer.py

Line 1047 in de5d115

def update_page_form_field_values(

def update_page_form_field_values(
        self,
        page: Union[PageObject, List[PageObject], None],
        fields: Dict[str, Union[str, List[str], Tuple[str, str, float]]],
        flags: FA.FfBits = FFBITS_NUL,
        auto_regenerate: Optional[bool] = True,
    ) -> None:

OR

pypdf/pypdf/generic/_base.py

Line 632 in de5d115

class TextStringObject(str, PdfObject): # noqa: SLOT000

def __new__(cls, value: Any) -> "TextStringObject":
    value=str(value)
    ...

[thomas-forte]

P.S. If you think this is a good idea, I can throw up a PR over the weekend.

[stefan6419846]

Thanks for the report.

Regarding TextStringObject.__new__: Aren't we already doing this implicitly with the super call?

pypdf/pypdf/generic/_base.py

Line 651 in de5d115

o = str.__new__(cls, value)

Apart from this, feel free to open a corresponding PR.

[thomas-forte]

Yes but the failure is on the if statement here which is using the original value not o and in my case was failing because the original value was a float not a string.

pypdf/pypdf/generic/_base.py

Line 656 in de5d115

if value.startswith(("\xfe\xff", "\xff\xfe")):

[stefan6419846]

Do you have some full example of what you tried to do?

[thomas-forte]

Yes, it's pretty abstract though but here is my use:

    merged_context = {
        **{k: "" for k in reader.get_form_text_fields()},  # convert all fields to blank
        **{k: str(v) for k, v in context.items() if v is not None},  # merge populated fields over blanks
    }

    writer.update_page_form_field_values(writer.pages[0], merged_context, FieldFlag(1))

This generates a dictionary of values to update the pdf with, where the keys are the field names.

I recently added str(v) to solve this issue but prior I was not converting the v to a string and it could be an int, str, or float. Specifically the float caused this error, I did not test with an int but I suspect that would also throw the error since an int does not have the startswith method:

Internal Server Error: /jobs/jobs/2/reports
Traceback (most recent call last):
  ...
  File "/Users/thomasforte/github/_work/track-star-api/core/pdfs/pdf_template_job_report.py", line 23, in generate_pdf_template_job_report
    writer.update_page_form_field_values(writer.pages[0], merged_context, FieldFlag(1))
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/thomasforte/github/_work/track-star-api/venv/lib/python3.12/site-packages/pypdf/_writer.py", line 1052, in update_page_form_field_values
    writer_parent_annot[NameObject(FA.V)] = TextStringObject(value)
                                            ~~~~~~~~~~~~~~~~^^^^^^^
  File "/Users/thomasforte/github/_work/track-star-api/venv/lib/python3.12/site-packages/pypdf/generic/_base.py", line 596, in __new__
    if value.startswith(("\xfe\xff", "\xff\xfe")):
       ^^^^^^^^^^^^^^^^
AttributeError: 'float' object has no attribute 'startswith'