Added type hints for PixelAccess methods and others

docs/reference/ImageDraw.rst

@@ -679,23 +679,7 @@ Methods
     :param hints: An optional list of hints.
     :returns: A (drawing context, drawing resource factory) tuple.
 
-.. py:method:: floodfill(image, xy, value, border=None, thresh=0)
-
-    .. warning:: This method is experimental.
-
-    Fills a bounded region with a given color.
-
-    :param image: Target image.
-    :param xy: Seed position (a 2-item coordinate tuple).
-    :param value: Fill color.
-    :param border: Optional border value.  If given, the region consists of
-        pixels with a color different from the border color.  If not given,
-        the region consists of pixels having the same color as the seed
-        pixel.
-    :param thresh: Optional threshold value which specifies a maximum
-        tolerable difference of a pixel value from the 'background' in
-        order for it to be replaced. Useful for filling regions of non-
-        homogeneous, but similar, colors.
+.. autofunction:: PIL.ImageDraw.floodfill
 
 .. _BCP 47 language code: https://www.w3.org/International/articles/language-tags/
 .. _OpenType docs: https://learn.microsoft.com/en-us/typography/opentype/spec/featurelist

docs/reference/PixelAccess.rst

@@ -44,42 +44,7 @@ Access using negative indexes is also possible. ::
 -----------------------------
 
 .. class:: PixelAccess
+  :canonical: PIL.Image.PixelAccess
 
-  .. method:: __setitem__(self, xy, color):
-
-        Modifies the pixel at x,y. The color is given as a single
-        numerical value for single band images, and a tuple for
-        multi-band images
-
-        :param xy: The pixel coordinate, given as (x, y).
-        :param color: The pixel value according to its mode. e.g. tuple (r, g, b) for RGB mode)
-
-  .. method:: __getitem__(self, xy):
-
-       Returns the pixel at x,y. The pixel is returned as a single
-        value for single band images or a tuple for multiple band
-        images
-
-        :param xy: The pixel coordinate, given as (x, y).
-        :returns: a pixel value for single band images, a tuple of
-          pixel values for multiband images.
-
-  .. method:: putpixel(self, xy, color):
-
-        Modifies the pixel at x,y. The color is given as a single
-        numerical value for single band images, and a tuple for
-        multi-band images. In addition to this, RGB and RGBA tuples
-        are accepted for P and PA images.
-
-        :param xy: The pixel coordinate, given as (x, y).
-        :param color: The pixel value according to its mode. e.g. tuple (r, g, b) for RGB mode)
-
-  .. method:: getpixel(self, xy):
-
-       Returns the pixel at x,y. The pixel is returned as a single
-        value for single band images or a tuple for multiple band
-        images
-
-        :param xy: The pixel coordinate, given as (x, y).
-        :returns: a pixel value for single band images, a tuple of
-          pixel values for multiband images.
+  .. automethod:: PIL.Image.PixelAccess.__getitem__
+  .. automethod:: PIL.Image.PixelAccess.__setitem__

docs/reference/PyAccess.rst

@@ -44,3 +44,4 @@ Access using negative indexes is also possible. ::
 
 .. autoclass:: PIL.PyAccess.PyAccess()
     :members:
+    :special-members: __getitem__, __setitem__

src/PIL/Image.py

@@ -41,7 +41,7 @@
 from collections.abc import Callable, MutableMapping
 from enum import IntEnum
 from types import ModuleType
-from typing import IO, TYPE_CHECKING, Any, Literal, Protocol, cast
+from typing import IO, TYPE_CHECKING, Any, Literal, Protocol, SupportsInt, cast
 
 # VERSION was removed in Pillow 6.0.0.
 # PILLOW_VERSION was removed in Pillow 9.0.0.
@@ -482,6 +482,30 @@ def _getscaleoffset(expr):
 # Implementation wrapper
 
 
+class PixelAccess(Protocol):
+    def __getitem__(self, xy: tuple[int, int]) -> float | tuple[int, ...]:
+        """
+        Returns the pixel at x,y. The pixel is returned as a single
+        value for single band images or a tuple for multi-band images.
+
+        :param xy: The pixel coordinate, given as (x, y).
+        :returns: a pixel value for single band images, a tuple of
+                  pixel values for multiband images.
+        """
+        raise NotImplementedError()
+
+    def __setitem__(self, xy: tuple[int, int], value: float | tuple[int, ...]) -> None:
+        """
+        Modifies the pixel at x,y. The color is given as a single
+        numerical value for single band images, and a tuple for
+        multi-band images.
+
+        :param xy: The pixel coordinate, given as (x, y).
+        :param color: The pixel value according to its mode. e.g. tuple (r, g, b) for RGB mode)
+        """
+        raise NotImplementedError()
+
+
 class Image:
     """
     This class represents an image object.  To create
@@ -834,7 +858,7 @@ def frombytes(self, data: bytes, decoder_name: str = "raw", *args) -> None:
             msg = "cannot decode image data"
             raise ValueError(msg)
 
-    def load(self):
+    def load(self) -> PixelAccess | None:
         """
         Allocates storage for the image and loads the pixel data.  In
         normal cases, you don't need to call this method, since the
@@ -847,7 +871,7 @@ def load(self):
         operations. See :ref:`file-handling` for more information.
 
         :returns: An image access object.
-        :rtype: :ref:`PixelAccess` or :py:class:`PIL.PyAccess`
+        :rtype: :py:class:`.PixelAccess` or :py:class:`.PyAccess`
         """
         if self.im is not None and self.palette and self.palette.dirty:
             # realize palette
@@ -876,6 +900,7 @@ def load(self):
                 if self.pyaccess:
                     return self.pyaccess
             return self.im.pixel_access(self.readonly)
+        return None
 
     def verify(self):
         """
@@ -1485,7 +1510,7 @@ def _reload_exif(self) -> None:
         self._exif._loaded = False
         self.getexif()
 
-    def get_child_images(self):
+    def get_child_images(self) -> list[ImageFile.ImageFile]:
         child_images = []
         exif = self.getexif()
         ifds = []
@@ -1509,10 +1534,7 @@ def get_child_images(self):
             fp = self.fp
             thumbnail_offset = ifd.get(513)
             if thumbnail_offset is not None:
-                try:
-                    thumbnail_offset += self._exif_offset
-                except AttributeError:
-                    pass
+                thumbnail_offset += getattr(self, "_exif_offset", 0)
                 self.fp.seek(thumbnail_offset)
                 data = self.fp.read(ifd.get(514))
                 fp = io.BytesIO(data)
@@ -1578,7 +1600,7 @@ def has_transparency_data(self) -> bool:
             or "transparency" in self.info
         )
 
-    def apply_transparency(self):
+    def apply_transparency(self) -> None:
         """
         If a P mode image has a "transparency" key in the info dictionary,
         remove the key and instead apply the transparency to the palette.
@@ -1590,6 +1612,7 @@ def apply_transparency(self):
         from . import ImagePalette
 
         palette = self.getpalette("RGBA")
+        assert palette is not None
         transparency = self.info["transparency"]
         if isinstance(transparency, bytes):
             for i, alpha in enumerate(transparency):
@@ -1601,7 +1624,9 @@ def apply_transparency(self):
 
         del self.info["transparency"]
 
-    def getpixel(self, xy):
+    def getpixel(
+        self, xy: tuple[SupportsInt, SupportsInt]
+    ) -> float | tuple[int, ...] | None:
         """
         Returns the pixel value at a given position.
 
@@ -1865,7 +1890,7 @@ def point(self, data):
             lut = [round(i) for i in lut]
         return self._new(self.im.point(lut, mode))
 
-    def putalpha(self, alpha):
+    def putalpha(self, alpha: Image | int) -> None:
         """
         Adds or replaces the alpha layer in this image.  If the image
         does not have an alpha layer, it's converted to "LA" or "RGBA".
@@ -1912,6 +1937,7 @@ def putalpha(self, alpha):
                 alpha = alpha.convert("L")
         else:
             # constant alpha
+            alpha = cast(int, alpha)  # see python/typing#1013
             try:
                 self.im.fillband(band, alpha)
             except (AttributeError, ValueError):
@@ -1975,7 +2001,7 @@ def putpalette(self, data, rawmode="RGB") -> None:
         self.palette.mode = "RGB"
         self.load()  # install new palette
 
-    def putpixel(self, xy, value):
+    def putpixel(self, xy: tuple[int, int], value: float | tuple[int, ...]) -> None:
         """
         Modifies the pixel at the given position. The color is given as
         a single numerical value for single-band images, and a tuple for
@@ -2015,7 +2041,7 @@ def putpixel(self, xy, value):
                 value = value[:3]
             value = self.palette.getcolor(value, self)
             if self.mode == "PA":
-                value = (value, alpha)
+                value = (value, alpha)  # type: ignore[assignment]
         return self.im.putpixel(xy, value)
 
     def remap_palette(self, dest_map, source_palette=None):

src/PIL/ImageDraw.py

@@ -898,9 +898,17 @@ def getdraw(im=None, hints=None):
     return im, handler
 
 
-def floodfill(image: Image.Image, xy, value, border=None, thresh=0) -> None:
+def floodfill(
+    image: Image.Image,
+    xy: tuple[int, int],
+    value: float | tuple[int, ...],
+    border: float | tuple[int, ...] | None = None,
+    thresh: float = 0,
+) -> None:
     """
-    (experimental) Fills a bounded region with a given color.
+    .. warning:: This method is experimental.
+
+    Fills a bounded region with a given color.
 
     :param image: Target image.
     :param xy: Seed position (a 2-item coordinate tuple). See
@@ -918,6 +926,7 @@ def floodfill(image: Image.Image, xy, value, border=None, thresh=0) -> None:
     # based on an implementation by Eric S. Raymond
     # amended by yo1995 @20180806
     pixel = image.load()
+    assert pixel is not None
     x, y = xy
     try:
         background = pixel[x, y]

src/PIL/ImageGrab.py

@@ -22,11 +22,17 @@
 import subprocess
 import sys
 import tempfile
+from typing import Union, cast
 
 from . import Image
 
 
-def grab(bbox=None, include_layered_windows=False, all_screens=False, xdisplay=None):
+def grab(
+    bbox: tuple[int, int, int, int] | None = None,
+    include_layered_windows: bool = False,
+    all_screens: bool = False,
+    xdisplay: str | None = None,
+) -> Image.Image:
     if xdisplay is None:
         if sys.platform == "darwin":
             fh, filepath = tempfile.mkstemp(".png")
@@ -36,7 +42,7 @@ def grab(bbox=None, include_layered_windows=False, all_screens=False, xdisplay=N
                 left, top, right, bottom = bbox
                 args += ["-R", f"{left},{top},{right-left},{bottom-top}"]
             subprocess.call(args + ["-x", filepath])
-            im = Image.open(filepath)
+            im: Image.Image = Image.open(filepath)
             im.load()
             os.unlink(filepath)
             if bbox:
@@ -63,6 +69,7 @@ def grab(bbox=None, include_layered_windows=False, all_screens=False, xdisplay=N
                 left, top, right, bottom = bbox
                 im = im.crop((left - x0, top - y0, right - x0, bottom - y0))
             return im
+    xdisplay = cast(Union[str, None], xdisplay)  # type: ignore[redundant-cast, unused-ignore]
     try:
         if not Image.core.HAVE_XCB:
             msg = "Pillow was built without XCB support"
@@ -77,7 +84,7 @@ def grab(bbox=None, include_layered_windows=False, all_screens=False, xdisplay=N
             fh, filepath = tempfile.mkstemp(".png")
             os.close(fh)
             subprocess.call(["gnome-screenshot", "-f", filepath])
-            im = Image.open(filepath)
+            im: Image.Image = Image.open(filepath)
             im.load()
             os.unlink(filepath)
             if bbox:
@@ -94,7 +101,7 @@ def grab(bbox=None, include_layered_windows=False, all_screens=False, xdisplay=N
         return im
 
 
-def grabclipboard():
+def grabclipboard() -> Image.Image | list[str] | None:
     if sys.platform == "darwin":
         fh, filepath = tempfile.mkstemp(".png")
         os.close(fh)