Add various type annotations

[srittau]

Changes proposed in this pull request:

• This PR add various type annotations, especially for the Image, ImageFont, ImageDraw, and _imagingft modules.

[nulano]

FWIW I have some WIP type annotations for ImageFont and _imagingft here: main...nulano:Pillow:types-imagefont

[srittau]

I think this is ready for review. The docs build might still fail, but I'd need help with that.

[srittau]

Also, the pypy3.10 failure seems unrelated?

[hugovk]

Yeah, the PyPy one is a bit flaky.

[radarhere]

The docs build might still fail, but I'd need help with that.

The error

docstring of PIL.Image.Image.transform:1: WARNING: py:class reference target not found: PIL.Image.GetDataTransform

is saying that the GetDataTransform doesn't appear in the documentation, so transform()'s description can't link to it.

The way to solve this is by updating docs/reference/Image.rst to include it, by adding

.. autoclass:: GetDataTransform
    :show-inheritance:

But given that our other protocols so far are SupportsGetMesh and SupportsArrayInterface, maybe this new protocol could be renamed SupportsGetData?

[radarhere]

Could you explain why you made this change?

[srittau]

The problem here is that options can be any of the remaining Image.transform arguments, i.e.:

        resample: int = Resampling.NEAREST,
        fill: int = 1,
        fillcolor: float | tuple[float, ...] | str | None 

dict is wrong in any case, but we could annotate it as float | tuple[float, ...] | str | None (with int being redundant with float), but that would imply that any argument could have that type. I see four alternatives:

• Don't bother and use Any.
• Use float | tuple[float, ...] | str | None as that would prevent some typing errors, but not all (e.g. fill=(1,2,3) would not be caught), at the cost of a slightly misleading type hints.
• Just replace options with the actual forwarded arguments. (The option I would probably choose, as there are only three options.)
• Use Unpack, which means we would need to introduce a new TypedDict for the arguments.

[radarhere]

I've created srittau#2 with various suggestions.

[lgeiger]

@srittau @radarhere This change ended up being a breaking change for me when upgrading from 10.3.0 to 10.4.0 since .resize() previously would accept a numpy array as size. This now fails with an internal error message:

  File "/usr/local/lib/python3.11/site-packages/PIL/Image.py", line 2297, in resize
    if self.size == size and box == (0, 0) + self.size:
       ^^^^^^^^^^^^^^^^^
ValueError: The truth value of an array with more than one element is ambiguous. Use a.any() or a.all()

If this change was intentional I think it would be best to raise a nice error message or revert this and relax the input type requirements.

[radarhere]

Let's move this conversation to #8195

[radarhere]

#8201 has now restored the ability to use a NumPy array.