Change dict to mapping in writer.update_page_form_field_values

[starspritechippy]

Explanation

Passing a variable of type dict[str, str] into the PdfWriter.update_page_form_field_values currently gives a pretty big error message when using Pylance regarding invariance, this message is left below. Since - from what I can tell - update_page_form_field_values does not write to the fields argument, its type annotation can be safely changed into collections.Mapping as the error suggests. Since I'm not entirely confident what the message means or what else the change might bring with it, I'm opening this as an issue rather than as a PR so I can get other people's input as well.

Pylance message:

Argument of type "dict[str, str]" cannot be assigned to parameter "fields" of type "dict[str, str | list[str] | tuple[str, str, float]]" in function "update_page_form_field_values"
  "dict[str, str]" is not assignable to "dict[str, str | list[str] | tuple[str, str, float]]"
    Type parameter "_VT@dict" is invariant, but "str" is not the same as "str | list[str] | tuple[str, str, float]"
    Consider switching from "dict" to "Mapping" which is covariant in the value typePylance(reportArgumentType)

Code Example

in https://github.com/py-pdf/pypdf/blob/main/pypdf/_writer.py#L1066 change

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,
    flatten: bool = False,
) -> None:
    ....

to

def update_page_form_field_values(
    self,
    page: Union[PageObject, list[PageObject], None],
    fields: Mapping[str, Union[str, list[str], tuple[str, str, float]]],
    flags: FA.FfBits = FFBITS_NUL,
    auto_regenerate: Optional[bool] = True,
    flatten: bool = False,
) -> None:
    ....

[stefan6419846]

Thanks for the report.

Which other side effects would this change have? Does the mapping type have a different meaning than a dictionary?

In general, I do not really see the benefit of changing the dictionary to a mapping here as this would restrict us internally, although I do not think that we are going to change the internal implementation to do in-place operations.

As far as I can tell from the answers at https://stackoverflow.com/questions/73603289/ linked in some similar discussions, you should easily be able to circumvent this in your code as well by explicitly typing your fields variable. (This is the approach I tend to prefer in my own code as well as this makes it easier for me to quickly determine the type of a specific variable without having to follow the whole code flow.)

[starspritechippy]

Thank you for the response. I don't believe there would be any side effects, but I'd like someone with more experience to confirm this: The update_page_form_field_values method doesn't seem to mutate the fields parameter in any way, so using a Mapping here should have no noticeable effect, other than fixing the variance problem, since Mappings are immutable from what I can tell.

Annotating my variable with the type expected by the update_page_form_field_values method would fix the problem, but my variable is strictly dict[str, str], the dict's values are not list[str] or tuple[str, str, float], so it feels wrong annotating my code as such. Given that the fields parameter does include the possibility that the fields dict's value is of type str, I believe changing the parameter type to be a Mapping is more correct.