fromarray: add type hints

[adamjstewart]

Really excited to see type hints in the latest release!

The only feature I'm using that was missing type hints is fromarray, so I added them. Not 100% sure if numpy.typing.ArrayLike is the right way to go, but feel free to suggest alternatives.

[Yay295]

I think the actual type would be numpy.ndarray, but that would require importing numpy.

[adamjstewart]

It doesn't have to be a numpy.ndarray, it could also be a PIL.Image or any other structure that implements an array interface. There are many ways to avoid importing numpy for typing: https://mypy.readthedocs.io/en/stable/runtime_troubles.html

[Yay295]

The other half of the NumPy support, which also isn't typed yet, is here:

Pillow/src/PIL/Image.py

Lines 686 to 709 in aeeb596

	@property
	def __array_interface__(self):
	# numpy array interface support
	new = {"version": 3}
	try:
	if self.mode == "1":
	# Binary images need to be extended from bits to bytes
	# See: https://github.com/python-pillow/Pillow/issues/350
	new["data"] = self.tobytes("raw", "L")
	else:
	new["data"] = self.tobytes()
	except Exception as e:
	if not isinstance(e, (MemoryError, RecursionError)):
	try:
	import numpy
	from packaging.version import parse as parse_version
	except ImportError:
	pass
	else:
	if parse_version(numpy.__version__) < parse_version("1.23"):
	warnings.warn(str(e))
	raise
	new["shape"], new["typestr"] = _conv_type_shape(self)
	return new

[Yay295]

I think numpy.typing.ArrayLike is too broad, since it includes scalars and sequences, whereas Image.fromarray() only supports the NumPy array interface.

[nulano]

I think you may need to add numpy to the list of dependencies here

Pillow/pyproject.toml

Lines 69 to 71 in aeeb596

	typing = [
	'typing-extensions; python_version < "3.10"',
	]

or in a new block to fix the mypy error.

[Yay295]

Something like

from typing import Protocol, Sequence, TypedDict
class ArrayInterfaceDict(TypedDict):
    shape: Sequence[int]
    typestr: str
class ArrayInterface(Protocol):
    __array_interface__: ArrayInterfaceDict

would be a more exact definition of what Pillow requires.

[nulano]

Something like

from typing import Protocol, Sequence, TypedDict
class ArrayInterfaceDict(TypedDict):
    shape: Sequence[int]
    typestr: str
class ArrayInterface(Protocol):
    __array_interface__: ArrayInterfaceDict

would be a more exact definition of what Pillow requires.

Adding that to PIL._typing would probably be a better option than requiring numpy be installed.

[radarhere]

__array_interface__ can optionally have "strides", but TypedDict only gained optional items in Python 3.11, so it doesn't look like we can use a TypedDict here.

Otherwise, I've created adamjstewart#1 as a suggestion to add the protocol.

[adamjstewart]

Thanks for the help @radarhere!

P.S. Love the profile pic @Yay295, excited for season 3 coming out this weekend!

[nulano]

Since (I assume) this is not intended to be exported, I would expect we either want this to be private, i.e.

Suggested change

	class SupportsArrayInterface(Protocol):
	class _SupportsArrayInterface(Protocol):

or in a private module, i.e. PIL._typing.SupportsArrayInterface.

@radarhere what do you think?

[radarhere]

I was modelling this after our implementation of SupportsGetMesh.

#7812 (comment)

If we're using _SupportsGetMesh as a type hint, this probably is something users might want to use, so should be accessible as a non-underscore thing?

[nulano]

I feel like the difference is that SupportsGetMesh is a Pillow protocol, whereas SupportsArrayInterface seems to be a numpy protocol. Similarly, we have PIL._typing.SupportsRead for a builtin Python protocol. I would therefore expect users to either use the actual numpy type (e.g. numpy.ndarray) or define their own protocol.

@hugovk Do you have any thoughts as the author of the quoted comment?

[hugovk]

Hmm, let's go for SupportsArrayInterface, it's probably more useful that way, and it's only a small class. We an always deprecate/remove later if needed.

[nulano]

Not 100% sure if numpy.typing.ArrayLike is the right way to go

NumPy seems to overload the np.array function with several types including Any and I can't find a more specific protocol.

[adamjstewart]

Anything else needed for this PR?

[radarhere]

There's an unresolved debate, but I expect it will be resolved sooner or later before the next release.

[hugovk]

Thanks!