Merge remote-tracking branch 'upstream/main' into type_hints

# Conflicts:
#	src/PIL/Image.py

.appveyor.yml

@@ -32,10 +32,10 @@ install:
 - curl -fsSL -o pillow-test-images.zip https://github.com/python-pillow/test-images/archive/main.zip
 - 7z x pillow-test-images.zip -oc:\
 - xcopy /S /Y c:\test-images-main\* c:\pillow\tests\images
-- curl -fsSL -o nasm-win64.zip https://raw.githubusercontent.com/python-pillow/pillow-depends/main/nasm-2.16.01-win64.zip
+- curl -fsSL -o nasm-win64.zip https://raw.githubusercontent.com/python-pillow/pillow-depends/main/nasm-2.16.03-win64.zip
 - 7z x nasm-win64.zip -oc:\
-- choco install ghostscript --version=10.3.0
-- path c:\nasm-2.16.01;C:\Program Files\gs\gs10.00.0\bin;%PATH%
+- choco install ghostscript --version=10.3.1
+- path c:\nasm-2.16.03;C:\Program Files\gs\gs10.00.0\bin;%PATH%
 - cd c:\pillow\winbuild\
 - ps: |
         c:\python38\python.exe c:\pillow\winbuild\build_prepare.py -v --depends=C:\pillow-depends\

.ci/requirements-cibw.txt

@@ -1 +1 @@
-cibuildwheel==2.18.1
+cibuildwheel==2.19.0

.github/workflows/test-windows.yml

@@ -86,7 +86,7 @@ jobs:
         choco install nasm --no-progress
         echo "C:\Program Files\NASM" >> $env:GITHUB_PATH
 
-        choco install ghostscript --version=10.3.0 --no-progress
+        choco install ghostscript --version=10.3.1 --no-progress
         echo "C:\Program Files\gs\gs10.00.0\bin" >> $env:GITHUB_PATH
 
         # Install extra test images

.github/workflows/wheels-dependencies.sh

@@ -16,9 +16,9 @@ ARCHIVE_SDIR=pillow-depends-main
 
 # Package versions for fresh source builds
 FREETYPE_VERSION=2.13.2
-HARFBUZZ_VERSION=8.4.0
+HARFBUZZ_VERSION=8.5.0
 LIBPNG_VERSION=1.6.43
-JPEGTURBO_VERSION=3.0.2
+JPEGTURBO_VERSION=3.0.3
 OPENJPEG_VERSION=2.5.2
 XZ_VERSION=5.4.5
 TIFF_VERSION=4.6.0
@@ -33,9 +33,9 @@ if [[ -n "$IS_MACOS" ]] || [[ "$MB_ML_VER" != 2014 ]]; then
 else
     ZLIB_VERSION=1.2.8
 fi
-LIBWEBP_VERSION=1.3.2
+LIBWEBP_VERSION=1.4.0
 BZIP2_VERSION=1.0.8
-LIBXCB_VERSION=1.16.1
+LIBXCB_VERSION=1.17.0
 BROTLI_VERSION=1.1.0
 
 if [[ -n "$IS_MACOS" ]] && [[ "$CIBW_ARCHS" == "x86_64" ]]; then
@@ -70,7 +70,7 @@ function build {
     fi
     build_new_zlib
 
-    build_simple xcb-proto 1.16.0 https://xorg.freedesktop.org/archive/individual/proto
+    build_simple xcb-proto 1.17.0 https://xorg.freedesktop.org/archive/individual/proto
     if [ -n "$IS_MACOS" ]; then
         build_simple xorgproto 2024.1 https://www.x.org/pub/individual/proto
         build_simple libXau 1.0.11 https://www.x.org/pub/individual/lib

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.4.3
+    rev: v0.4.7
     hooks:
       - id: ruff
         args: [--exit-non-zero-on-fix]
@@ -24,7 +24,7 @@ repos:
         exclude: (Makefile$|\.bat$|\.cmake$|\.eps$|\.fits$|\.gd$|\.opt$)
 
   - repo: https://github.com/pre-commit/mirrors-clang-format
-    rev: v18.1.4
+    rev: v18.1.5
     hooks:
       - id: clang-format
         types: [c]
@@ -50,7 +50,7 @@ repos:
         exclude: ^.github/.*TEMPLATE|^Tests/(fonts|images)/
 
   - repo: https://github.com/python-jsonschema/check-jsonschema
-    rev: 0.28.2
+    rev: 0.28.4
     hooks:
       - id: check-github-workflows
       - id: check-readthedocs
@@ -67,7 +67,7 @@ repos:
       - id: pyproject-fmt
 
   - repo: https://github.com/abravalheri/validate-pyproject
-    rev: v0.16
+    rev: v0.18
     hooks:
       - id: validate-pyproject
 

CHANGES.rst

@@ -5,6 +5,12 @@ Changelog (Pillow)
 10.4.0 (unreleased)
 -------------------
 
+- Accept 't' suffix for libtiff version #8126, #8129
+  [radarhere]
+
+- Deprecate ImageDraw.getdraw hints parameter #8124
+  [radarhere, hugovk]
+
 - Added ImageDraw circle() #8085
   [void4, hugovk, radarhere]
 

Tests/bench_cffi_access.py

@@ -44,6 +44,7 @@ def test_direct() -> None:
     caccess = im.im.pixel_access(False)
     access = PyAccess.new(im, False)
 
+    assert access is not None
     assert caccess[(0, 0)] == access[(0, 0)]
 
     print(f"Size: {im.width}x{im.height}")

Tests/test_features.py

@@ -38,7 +38,9 @@ def test_version() -> None:
             assert function(name) == version
             if name != "PIL":
                 if name == "zlib" and version is not None:
-                    version = version.replace(".zlib-ng", "")
+                    version = re.sub(".zlib-ng$", "", version)
+                elif name == "libtiff" and version is not None:
+                    version = re.sub("t$", "", version)
                 assert version is None or re.search(r"\d+(\.\d+)*$", version)
 
     for module in features.modules:
@@ -124,7 +126,7 @@ def test_unsupported_module() -> None:
 
 
 @pytest.mark.parametrize("supported_formats", (True, False))
-def test_pilinfo(supported_formats) -> None:
+def test_pilinfo(supported_formats: bool) -> None:
     buf = io.StringIO()
     features.pilinfo(buf, supported_formats=supported_formats)
     out = buf.getvalue()

Tests/test_file_bmp.py

@@ -140,7 +140,7 @@ def test_load_dib() -> None:
         (124, "g/pal8v5.bmp"),
     ),
 )
-def test_dib_header_size(header_size, path):
+def test_dib_header_size(header_size: int, path: str) -> None:
     image_path = "Tests/images/bmp/" + path
     with open(image_path, "rb") as fp:
         data = fp.read()[14:]

Tests/test_file_bufrstub.py

@@ -1,10 +1,11 @@
 from __future__ import annotations
 
 from pathlib import Path
+from typing import IO
 
 import pytest
 
-from PIL import BufrStubImagePlugin, Image
+from PIL import BufrStubImagePlugin, Image, ImageFile
 
 from .helper import hopper
 
@@ -50,20 +51,20 @@ def test_save(tmp_path: Path) -> None:
 
 
 def test_handler(tmp_path: Path) -> None:
-    class TestHandler:
+    class TestHandler(ImageFile.StubHandler):
         opened = False
         loaded = False
         saved = False
 
-        def open(self, im) -> None:
+        def open(self, im: ImageFile.StubImageFile) -> None:
             self.opened = True
 
-        def load(self, im):
+        def load(self, im: ImageFile.StubImageFile) -> Image.Image:
             self.loaded = True
             im.fp.close()
             return Image.new("RGB", (1, 1))
 
-        def save(self, im, fp, filename) -> None:
+        def save(self, im: Image.Image, fp: IO[bytes], filename: str) -> None:
             self.saved = True
 
     handler = TestHandler()

Tests/test_file_gif.py

@@ -53,6 +53,7 @@ def test_closed_file() -> None:
 
 def test_seek_after_close() -> None:
     im = Image.open("Tests/images/iss634.gif")
+    assert isinstance(im, GifImagePlugin.GifImageFile)
     im.load()
     im.close()
 
@@ -377,7 +378,8 @@ def test_save_netpbm_bmp_mode(tmp_path: Path) -> None:
         img = img.convert("RGB")
 
         tempfile = str(tmp_path / "temp.gif")
-        GifImagePlugin._save_netpbm(img, 0, tempfile)
+        b = BytesIO()
+        GifImagePlugin._save_netpbm(img, b, tempfile)
         with Image.open(tempfile) as reloaded:
             assert_image_similar(img, reloaded.convert("RGB"), 0)
 
@@ -388,7 +390,8 @@ def test_save_netpbm_l_mode(tmp_path: Path) -> None:
         img = img.convert("L")
 
         tempfile = str(tmp_path / "temp.gif")
-        GifImagePlugin._save_netpbm(img, 0, tempfile)
+        b = BytesIO()
+        GifImagePlugin._save_netpbm(img, b, tempfile)
         with Image.open(tempfile) as reloaded:
             assert_image_similar(img, reloaded.convert("L"), 0)
 
@@ -648,7 +651,7 @@ def test_dispose2_palette(tmp_path: Path) -> None:
             assert rgb_img.getpixel((50, 50)) == circle
 
             # Check that frame transparency wasn't added unnecessarily
-            assert img._frame_transparency is None
+            assert getattr(img, "_frame_transparency") is None
 
 
 def test_dispose2_diff(tmp_path: Path) -> None:

Tests/test_file_gribstub.py

@@ -5,7 +5,7 @@ from typing import IO
 
 import pytest
 
-from PIL import GribStubImagePlugin, Image
+from PIL import GribStubImagePlugin, Image, ImageFile
 
 from .helper import hopper
 
@@ -51,7 +51,7 @@ def test_save(tmp_path: Path) -> None:
 
 
 def test_handler(tmp_path: Path) -> None:
-    class TestHandler:
+    class TestHandler(ImageFile.StubHandler):
         opened = False
         loaded = False
         saved = False

Tests/test_file_hdf5stub.py

@@ -1,11 +1,12 @@
 from __future__ import annotations
 
+from io import BytesIO
 from pathlib import Path
 from typing import IO
 
 import pytest
 
-from PIL import Hdf5StubImagePlugin, Image
+from PIL import Hdf5StubImagePlugin, Image, ImageFile
 
 TEST_FILE = "Tests/images/hdf5.h5"
 
@@ -41,7 +42,7 @@ def test_load() -> None:
 def test_save() -> None:
     # Arrange
     with Image.open(TEST_FILE) as im:
-        dummy_fp = None
+        dummy_fp = BytesIO()
         dummy_filename = "dummy.filename"
 
         # Act / Assert: stub cannot save without an implemented handler
@@ -52,7 +53,7 @@ def test_save() -> None:
 
 
 def test_handler(tmp_path: Path) -> None:
-    class TestHandler:
+    class TestHandler(ImageFile.StubHandler):
         opened = False
         loaded = False
         saved = False

Tests/test_file_jpeg.py

@@ -171,7 +171,7 @@ class TestFileJpeg:
         [TEST_FILE, "Tests/images/pil_sample_cmyk.jpg"],
     )
     def test_dpi(self, test_image_path: str) -> None:
-        def test(xdpi: int, ydpi: int | None = None):
+        def test(xdpi: int, ydpi: int | None = None) -> tuple[int, int] | None:
             with Image.open(test_image_path) as im:
                 im = self.roundtrip(im, dpi=(xdpi, ydpi or xdpi))
             return im.info.get("dpi")

Tests/test_file_libtiff.py

@@ -54,7 +54,7 @@ class TestFileLibTiff(LibTiffTestCase):
     def test_version(self) -> None:
         version = features.version_codec("libtiff")
         assert version is not None
-        assert re.search(r"\d+\.\d+\.\d+$", version)
+        assert re.search(r"\d+\.\d+\.\d+t?$", version)
 
     def test_g4_tiff(self, tmp_path: Path) -> None:
         """Test the ordinary file path load path"""

Tests/test_file_webp.py

@@ -198,7 +198,9 @@ class TestFileWebp:
         (0, (0,), (-1, 0, 1, 2), (253, 254, 255, 256)),
     )
     @skip_unless_feature("webp_anim")
-    def test_invalid_background(self, background, tmp_path: Path) -> None:
+    def test_invalid_background(
+        self, background: int | tuple[int, ...], tmp_path: Path
+    ) -> None:
         temp_file = str(tmp_path / "temp.webp")
         im = hopper()
         with pytest.raises(OSError):

Tests/test_file_webp_animated.py

@@ -69,7 +69,7 @@ def test_write_animation_RGB(tmp_path: Path) -> None:
     are visually similar to the originals.
     """
 
-    def check(temp_file) -> None:
+    def check(temp_file: str) -> None:
         with Image.open(temp_file) as im:
             assert im.n_frames == 2
 

Tests/test_file_wmf.py

@@ -1,10 +1,11 @@
 from __future__ import annotations
 
 from pathlib import Path
+from typing import IO
 
 import pytest
 
-from PIL import Image, WmfImagePlugin
+from PIL import Image, ImageFile, WmfImagePlugin
 
 from .helper import assert_image_similar_tofile, hopper
 
@@ -34,10 +35,13 @@ def test_load() -> None:
 
 
 def test_register_handler(tmp_path: Path) -> None:
-    class TestHandler:
+    class TestHandler(ImageFile.StubHandler):
         methodCalled = False
 
-        def save(self, im, fp, filename) -> None:
+        def load(self, im: ImageFile.StubImageFile) -> Image.Image:
+            return Image.new("RGB", (1, 1))
+
+        def save(self, im: Image.Image, fp: IO[bytes], filename: str) -> None:
             self.methodCalled = True
 
     handler = TestHandler()
@@ -70,7 +74,7 @@ def test_load_set_dpi() -> None:
 
 
 @pytest.mark.parametrize("ext", (".wmf", ".emf"))
-def test_save(ext, tmp_path: Path) -> None:
+def test_save(ext: str, tmp_path: Path) -> None:
     im = hopper()
 
     tmpfile = str(tmp_path / ("temp" + ext))

Tests/test_image_access.py

@@ -259,6 +259,7 @@ class TestCffi(AccessTest):
         caccess = im.im.pixel_access(False)
         with pytest.warns(DeprecationWarning):
             access = PyAccess.new(im, False)
+        assert access is not None
 
         w, h = im.size
         for x in range(0, w, 10):
@@ -289,6 +290,7 @@ class TestCffi(AccessTest):
         caccess = im.im.pixel_access(False)
         with pytest.warns(DeprecationWarning):
             access = PyAccess.new(im, False)
+        assert access is not None
 
         w, h = im.size
         for x in range(0, w, 10):
@@ -299,6 +301,8 @@ class TestCffi(AccessTest):
         # Attempt to set the value on a read-only image
         with pytest.warns(DeprecationWarning):
             access = PyAccess.new(im, True)
+        assert access is not None
+
         with pytest.raises(ValueError):
             access[(0, 0)] = color
 
@@ -341,6 +345,8 @@ class TestCffi(AccessTest):
             im = Image.new(mode, (1, 1))
             with pytest.warns(DeprecationWarning):
                 access = PyAccess.new(im, False)
+                assert access is not None
+
                 access.putpixel((0, 0), color)
 
                 if len(color) == 3:

Tests/test_image_rotate.py

@@ -124,8 +124,8 @@ def test_fastpath_translate() -> None:
 def test_center() -> None:
     im = hopper()
     rotate(im, im.mode, 45, center=(0, 0))
-    rotate(im, im.mode, 45, translate=(im.size[0] / 2, 0))
-    rotate(im, im.mode, 45, center=(0, 0), translate=(im.size[0] / 2, 0))
+    rotate(im, im.mode, 45, translate=(im.size[0] // 2, 0))
+    rotate(im, im.mode, 45, center=(0, 0), translate=(im.size[0] // 2, 0))
 
 
 def test_rotate_no_fill() -> None:

Tests/test_image_thumbnail.py

@@ -111,7 +111,9 @@ def test_load_first_unless_jpeg() -> None:
     with Image.open("Tests/images/hopper.jpg") as im:
         draft = im.draft
 
-        def im_draft(mode: str, size: tuple[int, int]):
+        def im_draft(
+            mode: str, size: tuple[int, int]
+        ) -> tuple[str, tuple[int, int, float, float]] | None:
             result = draft(mode, size)
             assert result is not None
 

Tests/test_imagedraw.py

@@ -1624,3 +1624,8 @@ def test_incorrectly_ordered_coordinates(xy: tuple[int, int, int, int]) -> None:
         draw.rectangle(xy)
     with pytest.raises(ValueError):
         draw.rounded_rectangle(xy)
+
+
+def test_getdraw():
+    with pytest.warns(DeprecationWarning):
+        ImageDraw.getdraw(None, [])

Tests/test_imageops_usm.py

@@ -58,7 +58,6 @@ def test_blur_formats(test_images: dict[str, ImageFile.ImageFile]) -> None:
     blur = ImageFilter.GaussianBlur
     with pytest.raises(ValueError):
         im.convert("1").filter(blur)
-    blur(im.convert("L"))
     with pytest.raises(ValueError):
         im.convert("I").filter(blur)
     with pytest.raises(ValueError):

Tests/test_qt_image_qapplication.py

@@ -46,7 +46,7 @@ def roundtrip(expected: Image.Image) -> None:
 @pytest.mark.skipif(not ImageQt.qt_is_installed, reason="Qt bindings are not installed")
 def test_sanity(tmp_path: Path) -> None:
     # Segfault test
-    app = QApplication([])
+    app: QApplication | None = QApplication([])
     ex = Example()
     assert app  # Silence warning
     assert ex  # Silence warning

depends/install_imagequant.sh

@@ -2,7 +2,7 @@
 # install libimagequant
 
 archive_name=libimagequant
-archive_version=4.3.0
+archive_version=4.3.1
 
 archive=$archive_name-$archive_version
 

depends/install_webp.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 # install webp
 
-archive=libwebp-1.3.2
+archive=libwebp-1.4.0
 
 ./download-and-extract.sh $archive https://raw.githubusercontent.com/python-pillow/pillow-depends/main/$archive.tar.gz
 

docs/Makefile

@@ -9,9 +9,9 @@ PAPER         =
 BUILDDIR      = _build
 
 # Internal variables.
-PAPEROPT_a4     = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+PAPEROPT_a4     = --define latex_paper_size=a4
+PAPEROPT_letter = --define latex_paper_size=letter
+ALLSPHINXOPTS   = --doctree-dir $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
@@ -51,42 +51,42 @@ install-sphinx:
 .PHONY: html
 html:
 	$(MAKE) install-sphinx
-	$(SPHINXBUILD) -b html -W --keep-going $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	$(SPHINXBUILD) --builder html --fail-on-warning --keep-going $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
 .PHONY: dirhtml
 dirhtml:
 	$(MAKE) install-sphinx
-	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	$(SPHINXBUILD) --builder dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
 
 .PHONY: singlehtml
 singlehtml:
 	$(MAKE) install-sphinx
-	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	$(SPHINXBUILD) --builder singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
 	@echo
 	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
 
 .PHONY: pickle
 pickle:
 	$(MAKE) install-sphinx
-	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	$(SPHINXBUILD) --builder pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
 	@echo
 	@echo "Build finished; now you can process the pickle files."
 
 .PHONY: json
 json:
 	$(MAKE) install-sphinx
-	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	$(SPHINXBUILD) --builder json $(ALLSPHINXOPTS) $(BUILDDIR)/json
 	@echo
 	@echo "Build finished; now you can process the JSON files."
 
 .PHONY: htmlhelp
 htmlhelp:
 	$(MAKE) install-sphinx
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	$(SPHINXBUILD) --builder htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
 	@echo
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
 	      ".hhp project file in $(BUILDDIR)/htmlhelp."
@@ -94,7 +94,7 @@ htmlhelp:
 .PHONY: qthelp
 qthelp:
 	$(MAKE) install-sphinx
-	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	$(SPHINXBUILD) --builder qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
 	@echo
 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
 	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@@ -105,7 +105,7 @@ qthelp:
 .PHONY: devhelp
 devhelp:
 	$(MAKE) install-sphinx
-	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	$(SPHINXBUILD) --builder devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
 	@echo
 	@echo "Build finished."
 	@echo "To view the help file:"
@@ -116,14 +116,14 @@ devhelp:
 .PHONY: epub
 epub:
 	$(MAKE) install-sphinx
-	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	$(SPHINXBUILD) --builder epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
 	@echo
 	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
 
 .PHONY: latex
 latex:
 	$(MAKE) install-sphinx
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	$(SPHINXBUILD) --builder latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo
 	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
 	@echo "Run \`make' in that directory to run these through (pdf)latex" \
@@ -132,7 +132,7 @@ latex:
 .PHONY: latexpdf
 latexpdf:
 	$(MAKE) install-sphinx
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	$(SPHINXBUILD) --builder latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo "Running LaTeX files through pdflatex..."
 	$(MAKE) -C $(BUILDDIR)/latex all-pdf
 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
@@ -140,21 +140,21 @@ latexpdf:
 .PHONY: text
 text:
 	$(MAKE) install-sphinx
-	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	$(SPHINXBUILD) --builder text $(ALLSPHINXOPTS) $(BUILDDIR)/text
 	@echo
 	@echo "Build finished. The text files are in $(BUILDDIR)/text."
 
 .PHONY: man
 man:
 	$(MAKE) install-sphinx
-	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	$(SPHINXBUILD) --builder man $(ALLSPHINXOPTS) $(BUILDDIR)/man
 	@echo
 	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
 
 .PHONY: texinfo
 texinfo:
 	$(MAKE) install-sphinx
-	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	$(SPHINXBUILD) --builder texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
 	@echo
 	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
 	@echo "Run \`make' in that directory to run these through makeinfo" \
@@ -163,7 +163,7 @@ texinfo:
 .PHONY: info
 info:
 	$(MAKE) install-sphinx
-	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	$(SPHINXBUILD) --builder texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
 	@echo "Running Texinfo files through makeinfo..."
 	make -C $(BUILDDIR)/texinfo info
 	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
@@ -171,21 +171,21 @@ info:
 .PHONY: gettext
 gettext:
 	$(MAKE) install-sphinx
-	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	$(SPHINXBUILD) --builder gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
 	@echo
 	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
 
 .PHONY: changes
 changes:
 	$(MAKE) install-sphinx
-	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	$(SPHINXBUILD) --builder changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
 	@echo
 	@echo "The overview file is in $(BUILDDIR)/changes."
 
 .PHONY: linkcheck
 linkcheck:
 	$(MAKE) install-sphinx
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck -j auto
+	$(SPHINXBUILD) --builder linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck -j auto
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
 	      "or in $(BUILDDIR)/linkcheck/output.txt."
@@ -193,7 +193,7 @@ linkcheck:
 .PHONY: doctest
 doctest:
 	$(MAKE) install-sphinx
-	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	$(SPHINXBUILD) --builder doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
 	@echo "Testing of doctests in the sources finished, look at the " \
 	      "results in $(BUILDDIR)/doctest/output.txt."
 

docs/deprecations.rst

@@ -115,6 +115,13 @@ Support for LibTIFF earlier than 4
 Support for LibTIFF earlier than version 4 has been deprecated.
 Upgrade to a newer version of LibTIFF instead.
 
+ImageDraw.getdraw hints parameter
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. deprecated:: 10.4.0
+
+The ``hints`` parameter in :py:meth:`~PIL.ImageDraw.getdraw()` has been deprecated.
+
 Removed features
 ----------------
 

docs/handbook/concepts.rst

@@ -144,10 +144,12 @@ pixel, the Python Imaging Library provides different resampling *filters*.
 .. py:currentmodule:: PIL.Image
 
 .. data:: Resampling.NEAREST
+    :noindex:
 
     Pick one nearest pixel from the input image. Ignore all other input pixels.
 
 .. data:: Resampling.BOX
+    :noindex:
 
     Each pixel of source image contributes to one pixel of the
     destination image with identical weights.
@@ -158,6 +160,7 @@ pixel, the Python Imaging Library provides different resampling *filters*.
     .. versionadded:: 3.4.0
 
 .. data:: Resampling.BILINEAR
+    :noindex:
 
     For resize calculate the output pixel value using linear interpolation
     on all pixels that may contribute to the output value.
@@ -165,6 +168,7 @@ pixel, the Python Imaging Library provides different resampling *filters*.
     in the input image is used.
 
 .. data:: Resampling.HAMMING
+    :noindex:
 
     Produces a sharper image than :data:`Resampling.BILINEAR`, doesn't have
     dislocations on local level like with :data:`Resampling.BOX`.
@@ -174,6 +178,7 @@ pixel, the Python Imaging Library provides different resampling *filters*.
     .. versionadded:: 3.4.0
 
 .. data:: Resampling.BICUBIC
+    :noindex:
 
     For resize calculate the output pixel value using cubic interpolation
     on all pixels that may contribute to the output value.
@@ -181,6 +186,7 @@ pixel, the Python Imaging Library provides different resampling *filters*.
     in the input image is used.
 
 .. data:: Resampling.LANCZOS
+    :noindex:
 
     Calculate the output pixel value using a high-quality Lanczos filter (a
     truncated sinc) on all pixels that may contribute to the output value.

docs/installation/building-from-source.rst

@@ -68,7 +68,7 @@ Many of Pillow's features require external libraries:
 
 * **libimagequant** provides improved color quantization
 
-  * Pillow has been tested with libimagequant **2.6-4.3**
+  * Pillow has been tested with libimagequant **2.6-4.3.1**
   * Libimagequant is licensed GPLv3, which is more restrictive than
     the Pillow license, therefore we will not be distributing binaries
     with libimagequant support enabled.

docs/reference/Image.rst

@@ -78,8 +78,6 @@ Constructing images
 ^^^^^^^^^^^^^^^^^^^
 
 .. autofunction:: new
-.. autoclass:: SupportsArrayInterface
-    :show-inheritance:
 .. autofunction:: fromarray
 .. autofunction:: frombytes
 .. autofunction:: frombuffer
@@ -365,6 +363,14 @@ Classes
 .. autoclass:: PIL.Image.ImagePointHandler
 .. autoclass:: PIL.Image.ImageTransformHandler
 
+Protocols
+---------
+
+.. autoclass:: SupportsArrayInterface
+    :show-inheritance:
+.. autoclass:: SupportsGetData
+    :show-inheritance:
+
 Constants
 ---------
 
@@ -418,7 +424,6 @@ See :ref:`concept-filters` for details.
 .. autoclass:: Resampling
     :members:
     :undoc-members:
-    :noindex:
 
 Dither modes
 ^^^^^^^^^^^^

docs/reference/ImageFile.rst

@@ -57,6 +57,10 @@ Classes
     :undoc-members:
     :show-inheritance:
 
+.. autoclass:: PIL.ImageFile.StubHandler()
+    :members:
+    :show-inheritance:
+
 .. autoclass:: PIL.ImageFile.StubImageFile()
     :members:
     :show-inheritance:

docs/releasenotes/10.4.0.rst

@@ -34,6 +34,11 @@ Support for LibTIFF earlier than 4
 Support for LibTIFF earlier than version 4 has been deprecated.
 Upgrade to a newer version of LibTIFF instead.
 
+ImageDraw.getdraw hints parameter
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``hints`` parameter in :py:meth:`~PIL.ImageDraw.getdraw()` has been deprecated.
+
 API Changes
 ===========
 

src/PIL/BlpImagePlugin.py

@@ -31,10 +31,12 @@ BLP files come in many different flavours:
 
 from __future__ import annotations
 
+import abc
 import os
 import struct
 from enum import IntEnum
 from io import BytesIO
+from typing import IO
 
 from . import Image, ImageFile
 
@@ -55,11 +57,13 @@ class AlphaEncoding(IntEnum):
     DXT5 = 7
 
 
-def unpack_565(i):
+def unpack_565(i: int) -> tuple[int, int, int]:
     return ((i >> 11) & 0x1F) << 3, ((i >> 5) & 0x3F) << 2, (i & 0x1F) << 3
 
 
-def decode_dxt1(data, alpha=False):
+def decode_dxt1(
+    data: bytes, alpha: bool = False
+) -> tuple[bytearray, bytearray, bytearray, bytearray]:
     """
     input: one "row" of data (i.e. will produce 4*width pixels)
     """
@@ -67,9 +71,9 @@ def decode_dxt1(data, alpha=False):
     blocks = len(data) // 8  # number of blocks in row
     ret = (bytearray(), bytearray(), bytearray(), bytearray())
 
-    for block in range(blocks):
+    for block_index in range(blocks):
         # Decode next 8-byte block.
-        idx = block * 8
+        idx = block_index * 8
         color0, color1, bits = struct.unpack_from("<HHI", data, idx)
 
         r0, g0, b0 = unpack_565(color0)
@@ -114,7 +118,7 @@ def decode_dxt1(data, alpha=False):
     return ret
 
 
-def decode_dxt3(data):
+def decode_dxt3(data: bytes) -> tuple[bytearray, bytearray, bytearray, bytearray]:
     """
     input: one "row" of data (i.e. will produce 4*width pixels)
     """
@@ -122,8 +126,8 @@ def decode_dxt3(data):
     blocks = len(data) // 16  # number of blocks in row
     ret = (bytearray(), bytearray(), bytearray(), bytearray())
 
-    for block in range(blocks):
-        idx = block * 16
+    for block_index in range(blocks):
+        idx = block_index * 16
         block = data[idx : idx + 16]
         # Decode next 16-byte block.
         bits = struct.unpack_from("<8B", block)
@@ -167,7 +171,7 @@ def decode_dxt3(data):
     return ret
 
 
-def decode_dxt5(data):
+def decode_dxt5(data: bytes) -> tuple[bytearray, bytearray, bytearray, bytearray]:
     """
     input: one "row" of data (i.e. will produce 4 * width pixels)
     """
@@ -175,8 +179,8 @@ def decode_dxt5(data):
     blocks = len(data) // 16  # number of blocks in row
     ret = (bytearray(), bytearray(), bytearray(), bytearray())
 
-    for block in range(blocks):
-        idx = block * 16
+    for block_index in range(blocks):
+        idx = block_index * 16
         block = data[idx : idx + 16]
         # Decode next 16-byte block.
         a0, a1 = struct.unpack_from("<BB", block)
@@ -275,7 +279,7 @@ class BlpImageFile(ImageFile.ImageFile):
 class _BLPBaseDecoder(ImageFile.PyDecoder):
     _pulls_fd = True
 
-    def decode(self, buffer):
+    def decode(self, buffer: bytes) -> tuple[int, int]:
         try:
             self._read_blp_header()
             self._load()
@@ -284,7 +288,12 @@ class _BLPBaseDecoder(ImageFile.PyDecoder):
             raise OSError(msg) from e
         return -1, 0
 
-    def _read_blp_header(self):
+    @abc.abstractmethod
+    def _load(self) -> None:
+        pass
+
+    def _read_blp_header(self) -> None:
+        assert self.fd is not None
         self.fd.seek(4)
         (self._blp_compression,) = struct.unpack("<i", self._safe_read(4))
 
@@ -303,10 +312,10 @@ class _BLPBaseDecoder(ImageFile.PyDecoder):
         self._blp_offsets = struct.unpack("<16I", self._safe_read(16 * 4))
         self._blp_lengths = struct.unpack("<16I", self._safe_read(16 * 4))
 
-    def _safe_read(self, length):
+    def _safe_read(self, length: int) -> bytes:
         return ImageFile._safe_read(self.fd, length)
 
-    def _read_palette(self):
+    def _read_palette(self) -> list[tuple[int, int, int, int]]:
         ret = []
         for i in range(256):
             try:
@@ -316,7 +325,7 @@ class _BLPBaseDecoder(ImageFile.PyDecoder):
             ret.append((b, g, r, a))
         return ret
 
-    def _read_bgra(self, palette):
+    def _read_bgra(self, palette: list[tuple[int, int, int, int]]) -> bytearray:
         data = bytearray()
         _data = BytesIO(self._safe_read(self._blp_lengths[0]))
         while True:
@@ -325,7 +334,7 @@ class _BLPBaseDecoder(ImageFile.PyDecoder):
             except struct.error:
                 break
             b, g, r, a = palette[offset]
-            d = (r, g, b)
+            d: tuple[int, ...] = (r, g, b)
             if self._blp_alpha_depth:
                 d += (a,)
             data.extend(d)
@@ -349,29 +358,30 @@ class BLP1Decoder(_BLPBaseDecoder):
             msg = f"Unsupported BLP compression {repr(self._blp_encoding)}"
             raise BLPFormatError(msg)
 
-    def _decode_jpeg_stream(self):
+    def _decode_jpeg_stream(self) -> None:
         from .JpegImagePlugin import JpegImageFile
 
         (jpeg_header_size,) = struct.unpack("<I", self._safe_read(4))
         jpeg_header = self._safe_read(jpeg_header_size)
+        assert self.fd is not None
         self._safe_read(self._blp_offsets[0] - self.fd.tell())  # What IS this?
         data = self._safe_read(self._blp_lengths[0])
         data = jpeg_header + data
-        data = BytesIO(data)
-        image = JpegImageFile(data)
+        image = JpegImageFile(BytesIO(data))
         Image._decompression_bomb_check(image.size)
         if image.mode == "CMYK":
             decoder_name, extents, offset, args = image.tile[0]
             image.tile = [(decoder_name, extents, offset, (args[0], "CMYK"))]
         r, g, b = image.convert("RGB").split()
-        image = Image.merge("RGB", (b, g, r))
-        self.set_as_raw(image.tobytes())
+        reversed_image = Image.merge("RGB", (b, g, r))
+        self.set_as_raw(reversed_image.tobytes())
 
 
 class BLP2Decoder(_BLPBaseDecoder):
-    def _load(self):
+    def _load(self) -> None:
         palette = self._read_palette()
 
+        assert self.fd is not None
         self.fd.seek(self._blp_offsets[0])
 
         if self._blp_compression == 1:
@@ -428,7 +438,7 @@ class BLPEncoder(ImageFile.PyEncoder):
             data += b"\x00" * 4
         return data
 
-    def encode(self, bufsize):
+    def encode(self, bufsize: int) -> tuple[int, int, bytes]:
         palette_data = self._write_palette()
 
         offset = 20 + 16 * 4 * 2 + len(palette_data)
@@ -446,7 +456,7 @@ class BLPEncoder(ImageFile.PyEncoder):
         return len(data), 0, data
 
 
-def _save(im, fp, filename):
+def _save(im: Image.Image, fp: IO[bytes], filename: str | bytes) -> None:
     if im.mode != "P":
         msg = "Unsupported BLP image mode"
         raise ValueError(msg)

src/PIL/BmpImagePlugin.py

@@ -25,6 +25,7 @@
 from __future__ import annotations
 
 import os
+from typing import IO
 
 from . import Image, ImageFile, ImagePalette
 from ._binary import i16le as i16
@@ -52,7 +53,7 @@ def _accept(prefix: bytes) -> bool:
     return prefix[:2] == b"BM"
 
 
-def _dib_accept(prefix):
+def _dib_accept(prefix: bytes) -> bool:
     return i32(prefix) in [12, 40, 52, 56, 64, 108, 124]
 
 
@@ -300,7 +301,8 @@ class BmpImageFile(ImageFile.ImageFile):
 class BmpRleDecoder(ImageFile.PyDecoder):
     _pulls_fd = True
 
-    def decode(self, buffer):
+    def decode(self, buffer: bytes) -> tuple[int, int]:
+        assert self.fd is not None
         rle4 = self.args[1]
         data = bytearray()
         x = 0
@@ -394,11 +396,13 @@ SAVE = {
 }
 
 
-def _dib_save(im, fp, filename):
+def _dib_save(im: Image.Image, fp: IO[bytes], filename: str | bytes) -> None:
     _save(im, fp, filename, False)
 
 
-def _save(im, fp, filename, bitmap_header=True):
+def _save(
+    im: Image.Image, fp: IO[bytes], filename: str | bytes, bitmap_header: bool = True
+) -> None:
     try:
         rawmode, bits, colors = SAVE[im.mode]
     except KeyError as e:

src/PIL/BufrStubImagePlugin.py

@@ -10,12 +10,14 @@
 #
 from __future__ import annotations
 
+from typing import IO
+
 from . import Image, ImageFile
 
 _handler = None
 
 
-def register_handler(handler):
+def register_handler(handler: ImageFile.StubHandler | None) -> None:
     """
     Install application-specific BUFR image handler.
 
@@ -54,11 +56,11 @@ class BufrStubImageFile(ImageFile.StubImageFile):
         if loader:
             loader.open(self)
 
-    def _load(self):
+    def _load(self) -> ImageFile.StubHandler | None:
         return _handler
 
 
-def _save(im, fp, filename):
+def _save(im: Image.Image, fp: IO[bytes], filename: str | bytes) -> None:
     if _handler is None or not hasattr(_handler, "save"):
         msg = "BUFR save handler not installed"
         raise OSError(msg)

src/PIL/DcxImagePlugin.py

@@ -42,7 +42,7 @@ class DcxImageFile(PcxImageFile):
     format_description = "Intel DCX"
     _close_exclusive_fp_after_loading = False
 
-    def _open(self):
+    def _open(self) -> None:
         # Header
         s = self.fp.read(4)
         if not _accept(s):
@@ -58,7 +58,7 @@ class DcxImageFile(PcxImageFile):
             self._offset.append(offset)
 
         self._fp = self.fp
-        self.frame = None
+        self.frame = -1
         self.n_frames = len(self._offset)
         self.is_animated = self.n_frames > 1
         self.seek(0)

src/PIL/DdsImagePlugin.py

@@ -16,6 +16,7 @@ import io
 import struct
 import sys
 from enum import IntEnum, IntFlag
+from typing import IO
 
 from . import Image, ImageFile, ImagePalette
 from ._binary import i32le as i32
@@ -479,7 +480,8 @@ class DdsImageFile(ImageFile.ImageFile):
 class DdsRgbDecoder(ImageFile.PyDecoder):
     _pulls_fd = True
 
-    def decode(self, buffer):
+    def decode(self, buffer: bytes) -> tuple[int, int]:
+        assert self.fd is not None
         bitcount, masks = self.args
 
         # Some masks will be padded with zeros, e.g. R 0b11 G 0b1100
@@ -510,7 +512,7 @@ class DdsRgbDecoder(ImageFile.PyDecoder):
         return -1, 0
 
 
-def _save(im, fp, filename):
+def _save(im: Image.Image, fp: IO[bytes], filename: str | bytes) -> None:
     if im.mode not in ("RGB", "RGBA", "L", "LA"):
         msg = f"cannot write mode {im.mode} as DDS"
         raise OSError(msg)

src/PIL/EpsImagePlugin.py

@@ -27,6 +27,7 @@ import re
 import subprocess
 import sys
 import tempfile
+from typing import IO
 
 from . import Image, ImageFile
 from ._binary import i32le as i32
@@ -228,7 +229,7 @@ class EpsImageFile(ImageFile.ImageFile):
         reading_trailer_comments = False
         trailer_reached = False
 
-        def check_required_header_comments():
+        def check_required_header_comments() -> None:
             if "PS-Adobe" not in self.info:
                 msg = 'EPS header missing "%!PS-Adobe" comment'
                 raise SyntaxError(msg)
@@ -236,7 +237,7 @@ class EpsImageFile(ImageFile.ImageFile):
                 msg = 'EPS header missing "%%BoundingBox" comment'
                 raise SyntaxError(msg)
 
-        def _read_comment(s):
+        def _read_comment(s: str) -> bool:
             nonlocal reading_trailer_comments
             try:
                 m = split.match(s)
@@ -244,27 +245,25 @@ class EpsImageFile(ImageFile.ImageFile):
                 msg = "not an EPS file"
                 raise SyntaxError(msg) from e
 
-            if m:
-                k, v = m.group(1, 2)
-                self.info[k] = v
-                if k == "BoundingBox":
-                    if v == "(atend)":
-                        reading_trailer_comments = True
-                    elif not self._size or (
-                        trailer_reached and reading_trailer_comments
-                    ):
-                        try:
-                            # Note: The DSC spec says that BoundingBox
-                            # fields should be integers, but some drivers
-                            # put floating point values there anyway.
-                            box = [int(float(i)) for i in v.split()]
-                            self._size = box[2] - box[0], box[3] - box[1]
-                            self.tile = [
-                                ("eps", (0, 0) + self.size, offset, (length, box))
-                            ]
-                        except Exception:
-                            pass
-                return True
+            if not m:
+                return False
+
+            k, v = m.group(1, 2)
+            self.info[k] = v
+            if k == "BoundingBox":
+                if v == "(atend)":
+                    reading_trailer_comments = True
+                elif not self._size or (trailer_reached and reading_trailer_comments):
+                    try:
+                        # Note: The DSC spec says that BoundingBox
+                        # fields should be integers, but some drivers
+                        # put floating point values there anyway.
+                        box = [int(float(i)) for i in v.split()]
+                        self._size = box[2] - box[0], box[3] - box[1]
+                        self.tile = [("eps", (0, 0) + self.size, offset, (length, box))]
+                    except Exception:
+                        pass
+            return True
 
         while True:
             byte = self.fp.read(1)
@@ -413,7 +412,7 @@ class EpsImageFile(ImageFile.ImageFile):
 # --------------------------------------------------------------------
 
 
-def _save(im, fp, filename, eps=1):
+def _save(im: Image.Image, fp: IO[bytes], filename: str | bytes, eps: int = 1) -> None:
     """EPS Writer for the Python Imaging Library."""
 
     # make sure image data is available

src/PIL/FitsImagePlugin.py

@@ -122,7 +122,7 @@ class FitsImageFile(ImageFile.ImageFile):
 class FitsGzipDecoder(ImageFile.PyDecoder):
     _pulls_fd = True
 
-    def decode(self, buffer):
+    def decode(self, buffer: bytes) -> tuple[int, int]:
         assert self.fd is not None
         value = gzip.decompress(self.fd.read())
 

src/PIL/FpxImagePlugin.py

@@ -70,7 +70,7 @@ class FpxImageFile(ImageFile.ImageFile):
 
         self._open_index(1)
 
-    def _open_index(self, index=1):
+    def _open_index(self, index: int = 1) -> None:
         #
         # get the Image Contents Property Set
 
@@ -85,7 +85,7 @@ class FpxImageFile(ImageFile.ImageFile):
         size = max(self.size)
         i = 1
         while size > 64:
-            size = size / 2
+            size = size // 2
             i += 1
         self.maxid = i - 1
 
@@ -118,7 +118,7 @@ class FpxImageFile(ImageFile.ImageFile):
 
         self._open_subimage(1, self.maxid)
 
-    def _open_subimage(self, index=1, subimage=0):
+    def _open_subimage(self, index: int = 1, subimage: int = 0) -> None:
         #
         # setup tile descriptors for a given subimage
 
@@ -241,7 +241,7 @@ class FpxImageFile(ImageFile.ImageFile):
         self.ole.close()
         super().close()
 
-    def __exit__(self, *args):
+    def __exit__(self, *args: object) -> None:
         self.ole.close()
         super().__exit__()
 

src/PIL/GifImagePlugin.py

@@ -29,8 +29,10 @@ import itertools
 import math
 import os
 import subprocess
+import sys
 from enum import IntEnum
 from functools import cached_property
+from typing import IO, TYPE_CHECKING, Any, List, Literal, NamedTuple, Union
 
 from . import (
     Image,
@@ -45,6 +47,9 @@ from ._binary import i16le as i16
 from ._binary import o8
 from ._binary import o16le as o16
 
+if TYPE_CHECKING:
+    from . import _imaging
+
 
 class LoadingStrategy(IntEnum):
     """.. versionadded:: 9.1.0"""
@@ -117,7 +122,7 @@ class GifImageFile(ImageFile.ImageFile):
         self._seek(0)  # get ready to read first frame
 
     @property
-    def n_frames(self):
+    def n_frames(self) -> int:
         if self._n_frames is None:
             current = self.tell()
             try:
@@ -162,11 +167,11 @@ class GifImageFile(ImageFile.ImageFile):
                 msg = "no more images in GIF file"
                 raise EOFError(msg) from e
 
-    def _seek(self, frame, update_image=True):
+    def _seek(self, frame: int, update_image: bool = True) -> None:
         if frame == 0:
             # rewind
             self.__offset = 0
-            self.dispose = None
+            self.dispose: _imaging.ImagingCore | None = None
             self.__frame = -1
             self._fp.seek(self.__rewind)
             self.disposal_method = 0
@@ -194,9 +199,9 @@ class GifImageFile(ImageFile.ImageFile):
             msg = "no more images in GIF file"
             raise EOFError(msg)
 
-        palette = None
+        palette: ImagePalette.ImagePalette | Literal[False] | None = None
 
-        info = {}
+        info: dict[str, Any] = {}
         frame_transparency = None
         interlace = None
         frame_dispose_extent = None
@@ -212,7 +217,7 @@ class GifImageFile(ImageFile.ImageFile):
                 #
                 s = self.fp.read(1)
                 block = self.data()
-                if s[0] == 249:
+                if s[0] == 249 and block is not None:
                     #
                     # graphic control extension
                     #
@@ -248,14 +253,14 @@ class GifImageFile(ImageFile.ImageFile):
                         info["comment"] = comment
                     s = None
                     continue
-                elif s[0] == 255 and frame == 0:
+                elif s[0] == 255 and frame == 0 and block is not None:
                     #
                     # application extension
                     #
                     info["extension"] = block, self.fp.tell()
                     if block[:11] == b"NETSCAPE2.0":
                         block = self.data()
-                        if len(block) >= 3 and block[0] == 1:
+                        if block and len(block) >= 3 and block[0] == 1:
                             self.info["loop"] = i16(block, 1)
                 while self.data():
                     pass
@@ -336,60 +341,60 @@ class GifImageFile(ImageFile.ImageFile):
                         self._mode = "RGB"
                         self.im = self.im.convert("RGB", Image.Dither.FLOYDSTEINBERG)
 
-        def _rgb(color):
+        def _rgb(color: int) -> tuple[int, int, int]:
             if self._frame_palette:
                 if color * 3 + 3 > len(self._frame_palette.palette):
                     color = 0
-                color = tuple(self._frame_palette.palette[color * 3 : color * 3 + 3])
+                return tuple(self._frame_palette.palette[color * 3 : color * 3 + 3])
             else:
-                color = (color, color, color)
-            return color
+                return (color, color, color)
 
+        self.dispose = None
         self.dispose_extent = frame_dispose_extent
-        try:
-            if self.disposal_method < 2:
-                # do not dispose or none specified
-                self.dispose = None
-            elif self.disposal_method == 2:
-                # replace with background colour
+        if self.dispose_extent and self.disposal_method >= 2:
+            try:
+                if self.disposal_method == 2:
+                    # replace with background colour
 
-                # only dispose the extent in this frame
-                x0, y0, x1, y1 = self.dispose_extent
-                dispose_size = (x1 - x0, y1 - y0)
-
-                Image._decompression_bomb_check(dispose_size)
-
-                # by convention, attempt to use transparency first
-                dispose_mode = "P"
-                color = self.info.get("transparency", frame_transparency)
-                if color is not None:
-                    if self.mode in ("RGB", "RGBA"):
-                        dispose_mode = "RGBA"
-                        color = _rgb(color) + (0,)
-                else:
-                    color = self.info.get("background", 0)
-                    if self.mode in ("RGB", "RGBA"):
-                        dispose_mode = "RGB"
-                        color = _rgb(color)
-                self.dispose = Image.core.fill(dispose_mode, dispose_size, color)
-            else:
-                # replace with previous contents
-                if self.im is not None:
                     # only dispose the extent in this frame
-                    self.dispose = self._crop(self.im, self.dispose_extent)
-                elif frame_transparency is not None:
                     x0, y0, x1, y1 = self.dispose_extent
                     dispose_size = (x1 - x0, y1 - y0)
 
                     Image._decompression_bomb_check(dispose_size)
+
+                    # by convention, attempt to use transparency first
                     dispose_mode = "P"
-                    color = frame_transparency
-                    if self.mode in ("RGB", "RGBA"):
-                        dispose_mode = "RGBA"
-                        color = _rgb(frame_transparency) + (0,)
+                    color = self.info.get("transparency", frame_transparency)
+                    if color is not None:
+                        if self.mode in ("RGB", "RGBA"):
+                            dispose_mode = "RGBA"
+                            color = _rgb(color) + (0,)
+                    else:
+                        color = self.info.get("background", 0)
+                        if self.mode in ("RGB", "RGBA"):
+                            dispose_mode = "RGB"
+                            color = _rgb(color)
                     self.dispose = Image.core.fill(dispose_mode, dispose_size, color)
-        except AttributeError:
-            pass
+                else:
+                    # replace with previous contents
+                    if self.im is not None:
+                        # only dispose the extent in this frame
+                        self.dispose = self._crop(self.im, self.dispose_extent)
+                    elif frame_transparency is not None:
+                        x0, y0, x1, y1 = self.dispose_extent
+                        dispose_size = (x1 - x0, y1 - y0)
+
+                        Image._decompression_bomb_check(dispose_size)
+                        dispose_mode = "P"
+                        color = frame_transparency
+                        if self.mode in ("RGB", "RGBA"):
+                            dispose_mode = "RGBA"
+                            color = _rgb(frame_transparency) + (0,)
+                        self.dispose = Image.core.fill(
+                            dispose_mode, dispose_size, color
+                        )
+            except AttributeError:
+                pass
 
         if interlace is not None:
             transparency = -1
@@ -498,7 +503,12 @@ def _normalize_mode(im: Image.Image) -> Image.Image:
     return im.convert("L")
 
 
-def _normalize_palette(im, palette, info):
+_Palette = Union[bytes, bytearray, List[int], ImagePalette.ImagePalette]
+
+
+def _normalize_palette(
+    im: Image.Image, palette: _Palette | None, info: dict[str, Any]
+) -> Image.Image:
     """
     Normalizes the palette for image.
       - Sets the palette to the incoming palette, if provided.
@@ -526,8 +536,10 @@ def _normalize_palette(im, palette, info):
             source_palette = bytearray(i // 3 for i in range(768))
         im.palette = ImagePalette.ImagePalette("RGB", palette=source_palette)
 
+    used_palette_colors: list[int] | None
     if palette:
         used_palette_colors = []
+        assert source_palette is not None
         for i in range(0, len(source_palette), 3):
             source_color = tuple(source_palette[i : i + 3])
             index = im.palette.colors.get(source_color)
@@ -558,7 +570,11 @@ def _normalize_palette(im, palette, info):
     return im
 
 
-def _write_single_frame(im, fp, palette):
+def _write_single_frame(
+    im: Image.Image,
+    fp: IO[bytes],
+    palette: _Palette | None,
+) -> None:
     im_out = _normalize_mode(im)
     for k, v in im_out.info.items():
         im.encoderinfo.setdefault(k, v)
@@ -579,7 +595,9 @@ def _write_single_frame(im, fp, palette):
     fp.write(b"\0")  # end of image data
 
 
-def _getbbox(base_im, im_frame):
+def _getbbox(
+    base_im: Image.Image, im_frame: Image.Image
+) -> tuple[Image.Image, tuple[int, int, int, int] | None]:
     if _get_palette_bytes(im_frame) != _get_palette_bytes(base_im):
         im_frame = im_frame.convert("RGBA")
         base_im = base_im.convert("RGBA")
@@ -587,12 +605,20 @@ def _getbbox(base_im, im_frame):
     return delta, delta.getbbox(alpha_only=False)
 
 
-def _write_multiple_frames(im, fp, palette):
+class _Frame(NamedTuple):
+    im: Image.Image
+    bbox: tuple[int, int, int, int] | None
+    encoderinfo: dict[str, Any]
+
+
+def _write_multiple_frames(
+    im: Image.Image, fp: IO[bytes], palette: _Palette | None
+) -> bool:
     duration = im.encoderinfo.get("duration")
     disposal = im.encoderinfo.get("disposal", im.info.get("disposal"))
 
-    im_frames = []
-    previous_im = None
+    im_frames: list[_Frame] = []
+    previous_im: Image.Image | None = None
     frame_count = 0
     background_im = None
     for imSequence in itertools.chain([im], im.encoderinfo.get("append_images", [])):
@@ -618,24 +644,22 @@ def _write_multiple_frames(im, fp, palette):
             frame_count += 1
 
             diff_frame = None
-            if im_frames:
+            if im_frames and previous_im:
                 # delta frame
                 delta, bbox = _getbbox(previous_im, im_frame)
                 if not bbox:
                     # This frame is identical to the previous frame
                     if encoderinfo.get("duration"):
-                        im_frames[-1]["encoderinfo"]["duration"] += encoderinfo[
-                            "duration"
-                        ]
+                        im_frames[-1].encoderinfo["duration"] += encoderinfo["duration"]
                     continue
-                if im_frames[-1]["encoderinfo"].get("disposal") == 2:
+                if im_frames[-1].encoderinfo.get("disposal") == 2:
                     if background_im is None:
                         color = im.encoderinfo.get(
                             "transparency", im.info.get("transparency", (0, 0, 0))
                         )
                         background = _get_background(im_frame, color)
                         background_im = Image.new("P", im_frame.size, background)
-                        background_im.putpalette(im_frames[0]["im"].palette)
+                        background_im.putpalette(im_frames[0].im.palette)
                     bbox = _getbbox(background_im, im_frame)[1]
                 elif encoderinfo.get("optimize") and im_frame.mode != "1":
                     if "transparency" not in encoderinfo:
@@ -681,39 +705,39 @@ def _write_multiple_frames(im, fp, palette):
             else:
                 bbox = None
             previous_im = im_frame
-            im_frames.append(
-                {"im": diff_frame or im_frame, "bbox": bbox, "encoderinfo": encoderinfo}
-            )
+            im_frames.append(_Frame(diff_frame or im_frame, bbox, encoderinfo))
 
     if len(im_frames) == 1:
         if "duration" in im.encoderinfo:
             # Since multiple frames will not be written, use the combined duration
-            im.encoderinfo["duration"] = im_frames[0]["encoderinfo"]["duration"]
-        return
+            im.encoderinfo["duration"] = im_frames[0].encoderinfo["duration"]
+        return False
 
     for frame_data in im_frames:
-        im_frame = frame_data["im"]
-        if not frame_data["bbox"]:
+        im_frame = frame_data.im
+        if not frame_data.bbox:
             # global header
-            for s in _get_global_header(im_frame, frame_data["encoderinfo"]):
+            for s in _get_global_header(im_frame, frame_data.encoderinfo):
                 fp.write(s)
             offset = (0, 0)
         else:
             # compress difference
             if not palette:
-                frame_data["encoderinfo"]["include_color_table"] = True
+                frame_data.encoderinfo["include_color_table"] = True
 
-            im_frame = im_frame.crop(frame_data["bbox"])
-            offset = frame_data["bbox"][:2]
-        _write_frame_data(fp, im_frame, offset, frame_data["encoderinfo"])
+            im_frame = im_frame.crop(frame_data.bbox)
+            offset = frame_data.bbox[:2]
+        _write_frame_data(fp, im_frame, offset, frame_data.encoderinfo)
     return True
 
 
-def _save_all(im, fp, filename):
+def _save_all(im: Image.Image, fp: IO[bytes], filename: str | bytes) -> None:
     _save(im, fp, filename, save_all=True)
 
 
-def _save(im, fp, filename, save_all=False):
+def _save(
+    im: Image.Image, fp: IO[bytes], filename: str | bytes, save_all: bool = False
+) -> None:
     # header
     if "palette" in im.encoderinfo or "palette" in im.info:
         palette = im.encoderinfo.get("palette", im.info.get("palette"))
@@ -730,7 +754,7 @@ def _save(im, fp, filename, save_all=False):
         fp.flush()
 
 
-def get_interlace(im):
+def get_interlace(im: Image.Image) -> int:
     interlace = im.encoderinfo.get("interlace", 1)
 
     # workaround for @PIL153
@@ -740,7 +764,9 @@ def get_interlace(im):
     return interlace
 
 
-def _write_local_header(fp, im, offset, flags):
+def _write_local_header(
+    fp: IO[bytes], im: Image.Image, offset: tuple[int, int], flags: int
+) -> None:
     try:
         transparency = im.encoderinfo["transparency"]
     except KeyError:
@@ -788,7 +814,7 @@ def _write_local_header(fp, im, offset, flags):
     fp.write(o8(8))  # bits
 
 
-def _save_netpbm(im, fp, filename):
+def _save_netpbm(im: Image.Image, fp: IO[bytes], filename: str | bytes) -> None:
     # Unused by default.
     # To use, uncomment the register_save call at the end of the file.
     #
@@ -819,6 +845,7 @@ def _save_netpbm(im, fp, filename):
                 )
 
                 # Allow ppmquant to receive SIGPIPE if ppmtogif exits
+                assert quant_proc.stdout is not None
                 quant_proc.stdout.close()
 
                 retcode = quant_proc.wait()
@@ -840,7 +867,7 @@ def _save_netpbm(im, fp, filename):
 _FORCE_OPTIMIZE = False
 
 
-def _get_optimize(im, info):
+def _get_optimize(im: Image.Image, info: dict[str, Any]) -> list[int] | None:
     """
     Palette optimization is a potentially expensive operation.
 
@@ -884,6 +911,7 @@ def _get_optimize(im, info):
                 and current_palette_size > 2
             ):
                 return used_palette_colors
+    return None
 
 
 def _get_color_table_size(palette_bytes: bytes) -> int:
@@ -924,7 +952,10 @@ def _get_palette_bytes(im: Image.Image) -> bytes:
     return im.palette.palette if im.palette else b""
 
 
-def _get_background(im, info_background):
+def _get_background(
+    im: Image.Image,
+    info_background: int | tuple[int, int, int] | tuple[int, int, int, int] | None,
+) -> int:
     background = 0
     if info_background:
         if isinstance(info_background, tuple):
@@ -947,7 +978,7 @@ def _get_background(im, info_background):
     return background
 
 
-def _get_global_header(im, info):
+def _get_global_header(im: Image.Image, info: dict[str, Any]) -> list[bytes]:
     """Return a list of strings representing a GIF header"""
 
     # Header Block
@@ -1009,7 +1040,12 @@ def _get_global_header(im, info):
     return header
 
 
-def _write_frame_data(fp, im_frame, offset, params):
+def _write_frame_data(
+    fp: IO[bytes],
+    im_frame: Image.Image,
+    offset: tuple[int, int],
+    params: dict[str, Any],
+) -> None:
     try:
         im_frame.encoderinfo = params
 
@@ -1029,7 +1065,9 @@ def _write_frame_data(fp, im_frame, offset, params):
 # Legacy GIF utilities
 
 
-def getheader(im, palette=None, info=None):
+def getheader(
+    im: Image.Image, palette: _Palette | None = None, info: dict[str, Any] | None = None
+) -> tuple[list[bytes], list[int] | None]:
     """
     Legacy Method to get Gif data from image.
 
@@ -1041,11 +1079,11 @@ def getheader(im, palette=None, info=None):
     :returns: tuple of(list of header items, optimized palette)
 
     """
-    used_palette_colors = _get_optimize(im, info)
-
     if info is None:
         info = {}
 
+    used_palette_colors = _get_optimize(im, info)
+
     if "background" not in info and "background" in im.info:
         info["background"] = im.info["background"]
 
@@ -1057,7 +1095,9 @@ def getheader(im, palette=None, info=None):
     return header, used_palette_colors
 
 
-def getdata(im, offset=(0, 0), **params):
+def getdata(
+    im: Image.Image, offset: tuple[int, int] = (0, 0), **params: Any
+) -> list[bytes]:
     """
     Legacy Method
 
@@ -1074,12 +1114,23 @@ def getdata(im, offset=(0, 0), **params):
     :returns: List of bytes containing GIF encoded frame data
 
     """
+    from io import BytesIO
 
-    class Collector:
+    class Collector(BytesIO):
         data = []
 
-        def write(self, data):
-            self.data.append(data)
+        if sys.version_info >= (3, 12):
+            from collections.abc import Buffer
+
+            def write(self, data: Buffer) -> int:
+                self.data.append(data)
+                return len(data)
+
+        else:
+
+            def write(self, data: Any) -> int:
+                self.data.append(data)
+                return len(data)
 
     im.load()  # make sure raster data is available
 

src/PIL/GimpGradientFile.py

@@ -21,6 +21,7 @@ See the GIMP distribution for more information.)
 from __future__ import annotations
 
 from math import log, pi, sin, sqrt
+from typing import IO, Callable
 
 from ._binary import o8
 
@@ -28,7 +29,7 @@ EPSILON = 1e-10
 """"""  # Enable auto-doc for data member
 
 
-def linear(middle, pos):
+def linear(middle: float, pos: float) -> float:
     if pos <= middle:
         if middle < EPSILON:
             return 0.0
@@ -43,19 +44,19 @@ def linear(middle, pos):
             return 0.5 + 0.5 * pos / middle
 
 
-def curved(middle, pos):
+def curved(middle: float, pos: float) -> float:
     return pos ** (log(0.5) / log(max(middle, EPSILON)))
 
 
-def sine(middle, pos):
+def sine(middle: float, pos: float) -> float:
     return (sin((-pi / 2.0) + pi * linear(middle, pos)) + 1.0) / 2.0
 
 
-def sphere_increasing(middle, pos):
+def sphere_increasing(middle: float, pos: float) -> float:
     return sqrt(1.0 - (linear(middle, pos) - 1.0) ** 2)
 
 
-def sphere_decreasing(middle, pos):
+def sphere_decreasing(middle: float, pos: float) -> float:
     return 1.0 - sqrt(1.0 - linear(middle, pos) ** 2)
 
 
@@ -64,9 +65,22 @@ SEGMENTS = [linear, curved, sine, sphere_increasing, sphere_decreasing]
 
 
 class GradientFile:
-    gradient = None
+    gradient: (
+        list[
+            tuple[
+                float,
+                float,
+                float,
+                list[float],
+                list[float],
+                Callable[[float, float], float],
+            ]
+        ]
+        | None
+    ) = None
 
-    def getpalette(self, entries=256):
+    def getpalette(self, entries: int = 256) -> tuple[bytes, str]:
+        assert self.gradient is not None
         palette = []
 
         ix = 0
@@ -101,7 +115,7 @@ class GradientFile:
 class GimpGradientFile(GradientFile):
     """File handler for GIMP's gradient format."""
 
-    def __init__(self, fp):
+    def __init__(self, fp: IO[bytes]) -> None:
         if fp.readline()[:13] != b"GIMP Gradient":
             msg = "not a GIMP gradient file"
             raise SyntaxError(msg)
@@ -114,7 +128,7 @@ class GimpGradientFile(GradientFile):
 
         count = int(line)
 
-        gradient = []
+        self.gradient = []
 
         for i in range(count):
             s = fp.readline().split()
@@ -132,6 +146,4 @@ class GimpGradientFile(GradientFile):
                 msg = "cannot handle HSV colour space"
                 raise OSError(msg)
 
-            gradient.append((x0, x1, xm, rgb0, rgb1, segment))
-
-        self.gradient = gradient
+            self.gradient.append((x0, x1, xm, rgb0, rgb1, segment))

src/PIL/GimpPaletteFile.py

@@ -16,6 +16,7 @@
 from __future__ import annotations
 
 import re
+from typing import IO
 
 from ._binary import o8
 
@@ -25,8 +26,8 @@ class GimpPaletteFile:
 
     rawmode = "RGB"
 
-    def __init__(self, fp):
-        self.palette = [o8(i) * 3 for i in range(256)]
+    def __init__(self, fp: IO[bytes]) -> None:
+        palette = [o8(i) * 3 for i in range(256)]
 
         if fp.readline()[:12] != b"GIMP Palette":
             msg = "not a GIMP palette file"
@@ -49,9 +50,9 @@ class GimpPaletteFile:
                 msg = "bad palette entry"
                 raise ValueError(msg)
 
-            self.palette[i] = o8(v[0]) + o8(v[1]) + o8(v[2])
+            palette[i] = o8(v[0]) + o8(v[1]) + o8(v[2])
 
-        self.palette = b"".join(self.palette)
+        self.palette = b"".join(palette)
 
     def getpalette(self) -> tuple[bytes, str]:
         return self.palette, self.rawmode

src/PIL/GribStubImagePlugin.py

@@ -10,12 +10,14 @@
 #
 from __future__ import annotations
 
+from typing import IO
+
 from . import Image, ImageFile
 
 _handler = None
 
 
-def register_handler(handler):
+def register_handler(handler: ImageFile.StubHandler | None) -> None:
     """
     Install application-specific GRIB image handler.
 
@@ -54,11 +56,11 @@ class GribStubImageFile(ImageFile.StubImageFile):
         if loader:
             loader.open(self)
 
-    def _load(self):
+    def _load(self) -> ImageFile.StubHandler | None:
         return _handler
 
 
-def _save(im, fp, filename):
+def _save(im: Image.Image, fp: IO[bytes], filename: str | bytes) -> None:
     if _handler is None or not hasattr(_handler, "save"):
         msg = "GRIB save handler not installed"
         raise OSError(msg)

src/PIL/Hdf5StubImagePlugin.py

@@ -10,12 +10,14 @@
 #
 from __future__ import annotations
 
+from typing import IO
+
 from . import Image, ImageFile
 
 _handler = None
 
 
-def register_handler(handler):
+def register_handler(handler: ImageFile.StubHandler | None) -> None:
     """
     Install application-specific HDF5 image handler.
 
@@ -54,11 +56,11 @@ class HDF5StubImageFile(ImageFile.StubImageFile):
         if loader:
             loader.open(self)
 
-    def _load(self):
+    def _load(self) -> ImageFile.StubHandler | None:
         return _handler
 
 
-def _save(im, fp, filename):
+def _save(im: Image.Image, fp: IO[bytes], filename: str | bytes) -> None:
     if _handler is None or not hasattr(_handler, "save"):
         msg = "HDF5 save handler not installed"
         raise OSError(msg)

src/PIL/IcnsImagePlugin.py

@@ -22,6 +22,7 @@ import io
 import os
 import struct
 import sys
+from typing import IO
 
 from . import Image, ImageFile, PngImagePlugin, features
 
@@ -312,7 +313,7 @@ class IcnsImageFile(ImageFile.ImageFile):
         return px
 
 
-def _save(im, fp, filename):
+def _save(im: Image.Image, fp: IO[bytes], filename: str | bytes) -> None:
     """
     Saves the image as a series of PNG files,
     that are then combined into a .icns file.
@@ -346,29 +347,27 @@ def _save(im, fp, filename):
     entries = []
     for type, size in sizes.items():
         stream = size_streams[size]
-        entries.append(
-            {"type": type, "size": HEADERSIZE + len(stream), "stream": stream}
-        )
+        entries.append((type, HEADERSIZE + len(stream), stream))
 
     # Header
     fp.write(MAGIC)
     file_length = HEADERSIZE  # Header
     file_length += HEADERSIZE + 8 * len(entries)  # TOC
-    file_length += sum(entry["size"] for entry in entries)
+    file_length += sum(entry[1] for entry in entries)
     fp.write(struct.pack(">i", file_length))
 
     # TOC
     fp.write(b"TOC ")
     fp.write(struct.pack(">i", HEADERSIZE + len(entries) * HEADERSIZE))
     for entry in entries:
-        fp.write(entry["type"])
-        fp.write(struct.pack(">i", entry["size"]))
+        fp.write(entry[0])
+        fp.write(struct.pack(">i", entry[1]))
 
     # Data
     for entry in entries:
-        fp.write(entry["type"])
-        fp.write(struct.pack(">i", entry["size"]))
-        fp.write(entry["stream"])
+        fp.write(entry[0])
+        fp.write(struct.pack(">i", entry[1]))
+        fp.write(entry[2])
 
     if hasattr(fp, "flush"):
         fp.flush()

src/PIL/IcoImagePlugin.py

@@ -25,6 +25,7 @@ from __future__ import annotations
 import warnings
 from io import BytesIO
 from math import ceil, log
+from typing import IO
 
 from . import BmpImagePlugin, Image, ImageFile, PngImagePlugin
 from ._binary import i16le as i16
@@ -39,7 +40,7 @@ from ._binary import o32le as o32
 _MAGIC = b"\0\0\1\0"
 
 
-def _save(im, fp, filename):
+def _save(im: Image.Image, fp: IO[bytes], filename: str | bytes) -> None:
     fp.write(_MAGIC)  # (2+2)
     bmp = im.encoderinfo.get("bitmap_format") == "bmp"
     sizes = im.encoderinfo.get(
@@ -194,7 +195,7 @@ class IcoFile:
         """
         return self.frame(self.getentryindex(size, bpp))
 
-    def frame(self, idx):
+    def frame(self, idx: int) -> Image.Image:
         """
         Get an image from frame idx
         """
@@ -205,6 +206,7 @@ class IcoFile:
         data = self.buf.read(8)
         self.buf.seek(header["offset"])
 
+        im: Image.Image
         if data[:8] == PngImagePlugin._MAGIC:
             # png frame
             im = PngImagePlugin.PngImageFile(self.buf)

src/PIL/ImImagePlugin.py

@@ -28,6 +28,7 @@ from __future__ import annotations
 
 import os
 import re
+from typing import IO, Any
 
 from . import Image, ImageFile, ImagePalette
 
@@ -103,7 +104,7 @@ for j in range(2, 33):
 split = re.compile(rb"^([A-Za-z][^:]*):[ \t]*(.*)[ \t]*$")
 
 
-def number(s):
+def number(s: Any) -> float:
     try:
         return int(s)
     except ValueError:
@@ -325,7 +326,7 @@ SAVE = {
 }
 
 
-def _save(im, fp, filename):
+def _save(im: Image.Image, fp: IO[bytes], filename: str | bytes) -> None:
     try:
         image_type, rawmode = SAVE[im.mode]
     except KeyError as e:
@@ -340,6 +341,8 @@ def _save(im, fp, filename):
         # or: SyntaxError("not an IM file")
         # 8 characters are used for "Name: " and "\r\n"
         # Keep just the filename, ditch the potentially overlong path
+        if isinstance(filename, bytes):
+            filename = filename.decode("ascii")
         name, ext = os.path.splitext(os.path.basename(filename))
         name = "".join([name[: 92 - len(ext)], ext])
 

src/PIL/Image.py

@@ -49,6 +49,7 @@ from typing import (
     Protocol,
     Sequence,
     SupportsInt,
+    Tuple,
     cast,
 )
 
@@ -537,6 +538,12 @@ class PixelAccess(Protocol):
         raise NotImplementedError()
 
 
+class SupportsGetData(Protocol):
+    def getdata(
+        self,
+    ) -> tuple[Transform, Sequence[int]]: ...
+
+
 class Image:
     """
     This class represents an image object.  To create
@@ -654,7 +661,7 @@ class Image:
             self.load()
 
     def _dump(
-        self, file: str | None = None, format: str | None = None, **options
+        self, file: str | None = None, format: str | None = None, **options: Any
     ) -> str:
         suffix = ""
         if format:
@@ -677,10 +684,12 @@ class Image:
 
         return filename
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
+        if self.__class__ is not other.__class__:
+            return False
+        assert isinstance(other, Image)
         return (
-            self.__class__ is other.__class__
-            and self.mode == other.mode
+            self.mode == other.mode
             and self.size == other.size
             and self.info == other.info
             and self.getpalette() == other.getpalette()
@@ -1324,7 +1333,7 @@ class Image:
         return im.crop((x0, y0, x1, y1))
 
     def draft(
-        self, mode: str, size: tuple[int, int]
+        self, mode: str | None, size: tuple[int, int]
     ) -> tuple[str, tuple[int, int, float, float]] | None:
         """
         Configures the image file loader so it returns a version of the
@@ -1394,7 +1403,7 @@ class Image:
         """
         return ImageMode.getmode(self.mode).bands
 
-    def getbbox(self, *, alpha_only: bool = True) -> tuple[int, int, int, int]:
+    def getbbox(self, *, alpha_only: bool = True) -> tuple[int, int, int, int] | None:
         """
         Calculates the bounding box of the non-zero regions in the
         image.
@@ -1746,7 +1755,12 @@ class Image:
             return self.im.entropy(extrema)
         return self.im.entropy()
 
-    def paste(self, im, box=None, mask=None) -> None:
+    def paste(
+        self,
+        im: Image | str | float | tuple[float, ...],
+        box: tuple[int, int, int, int] | tuple[int, int] | None = None,
+        mask: Image | None = None,
+    ) -> None:
         """
         Pastes another image into this image. The box argument is either
         a 2-tuple giving the upper left corner, a 4-tuple defining the
@@ -1774,7 +1788,7 @@ class Image:
         See :py:meth:`~PIL.Image.Image.alpha_composite` if you want to
         combine images with respect to their alpha channels.
 
-        :param im: Source image or pixel value (integer or tuple).
+        :param im: Source image or pixel value (integer, float or tuple).
         :param box: An optional 4-tuple giving the region to paste into.
            If a 2-tuple is used instead, it's treated as the upper left
            corner.  If omitted or None, the source is pasted into the
@@ -1983,7 +1997,9 @@ class Image:
 
         self.im.putband(alpha.im, band)
 
-    def putdata(self, data, scale=1.0, offset=0.0):
+    def putdata(
+        self, data: Sequence[float], scale: float = 1.0, offset: float = 0.0
+    ) -> None:
         """
         Copies pixel data from a flattened sequence object into the image. The
         values should start at the upper left corner (0, 0), continue to the
@@ -2180,7 +2196,13 @@ class Image:
             min(self.size[1], math.ceil(box[3] + support_y)),
         )
 
-    def resize(self, size, resample=None, box=None, reducing_gap=None) -> Image:
+    def resize(
+        self,
+        size: tuple[int, int],
+        resample: int | None = None,
+        box: tuple[float, float, float, float] | None = None,
+        reducing_gap: float | None = None,
+    ) -> Image:
         """
         Returns a resized copy of this image.
 
@@ -2245,13 +2267,9 @@ class Image:
             msg = "reducing_gap must be 1.0 or greater"
             raise ValueError(msg)
 
-        size = tuple(size)
-
         self.load()
         if box is None:
             box = (0, 0) + self.size
-        else:
-            box = tuple(box)
 
         if self.size == size and box == (0, 0) + self.size:
             return self.copy()
@@ -2286,7 +2304,11 @@ class Image:
 
         return self._new(self.im.resize(size, resample, box))
 
-    def reduce(self, factor, box=None):
+    def reduce(
+        self,
+        factor: int | tuple[int, int],
+        box: tuple[int, int, int, int] | None = None,
+    ) -> Image:
         """
         Returns a copy of the image reduced ``factor`` times.
         If the size of the image is not dividable by ``factor``,
@@ -2304,8 +2326,6 @@ class Image:
 
         if box is None:
             box = (0, 0) + self.size
-        else:
-            box = tuple(box)
 
         if factor == (1, 1) and box == (0, 0) + self.size:
             return self.copy()
@@ -2321,13 +2341,13 @@ class Image:
 
     def rotate(
         self,
-        angle,
-        resample=Resampling.NEAREST,
-        expand=0,
-        center=None,
-        translate=None,
-        fillcolor=None,
-    ):
+        angle: float,
+        resample: Resampling = Resampling.NEAREST,
+        expand: int | bool = False,
+        center: tuple[int, int] | None = None,
+        translate: tuple[int, int] | None = None,
+        fillcolor: float | tuple[float, ...] | str | None = None,
+    ) -> Image:
         """
         Returns a rotated copy of this image.  This method returns a
         copy of this image, rotated the given number of degrees counter
@@ -2489,7 +2509,7 @@ class Image:
 
         save_all = params.pop("save_all", False)
         self.encoderinfo = params
-        self.encoderconfig = ()
+        self.encoderconfig: tuple[Any, ...] = ()
 
         preinit()
 
@@ -2634,7 +2654,12 @@ class Image:
         """
         return 0
 
-    def thumbnail(self, size, resample=Resampling.BICUBIC, reducing_gap=2.0):
+    def thumbnail(
+        self,
+        size: tuple[float, float],
+        resample: Resampling = Resampling.BICUBIC,
+        reducing_gap: float = 2.0,
+    ) -> None:
         """
         Make this image into a thumbnail.  This method modifies the
         image to contain a thumbnail version of itself, no larger than
@@ -2695,20 +2720,24 @@ class Image:
 
         box = None
         if reducing_gap is not None:
-            size = preserve_aspect_ratio()
-            if size is None:
+            preserved_size = preserve_aspect_ratio()
+            if preserved_size is None:
                 return
+            size = preserved_size
 
-            res = self.draft(None, (size[0] * reducing_gap, size[1] * reducing_gap))
+            res = self.draft(
+                None, (int(size[0] * reducing_gap), int(size[1] * reducing_gap))
+            )
             if res is not None:
                 box = res[1]
         if box is None:
             self.load()
 
             # load() may have changed the size of the image
-            size = preserve_aspect_ratio()
-            if size is None:
+            preserved_size = preserve_aspect_ratio()
+            if preserved_size is None:
                 return
+            size = preserved_size
 
         if self.size != size:
             im = self.resize(size, resample, box=box, reducing_gap=reducing_gap)
@@ -2724,12 +2753,12 @@ class Image:
     # instead of bloating the method docs, add a separate chapter.
     def transform(
         self,
-        size,
-        method,
-        data=None,
-        resample=Resampling.NEAREST,
-        fill=1,
-        fillcolor=None,
+        size: tuple[int, int],
+        method: Transform | ImageTransformHandler | SupportsGetData,
+        data: Sequence[Any] | None = None,
+        resample: int = Resampling.NEAREST,
+        fill: int = 1,
+        fillcolor: float | tuple[float, ...] | str | None = None,
     ) -> Image:
         """
         Transforms this image.  This method creates a new image with the
@@ -2893,7 +2922,7 @@ class Image:
         if image.mode in ("1", "P"):
             resample = Resampling.NEAREST
 
-        self.im.transform2(box, image.im, method, data, resample, fill)
+        self.im.transform(box, image.im, method, data, resample, fill)
 
     def transpose(self, method: Transpose) -> Image:
         """
@@ -2909,7 +2938,7 @@ class Image:
         self.load()
         return self._new(self.im.transpose(method))
 
-    def effect_spread(self, distance):
+    def effect_spread(self, distance: int) -> Image:
         """
         Randomly spread pixels in an image.
 
@@ -2963,7 +2992,7 @@ class ImageTransformHandler:
         self,
         size: tuple[int, int],
         image: Image,
-        **options: dict[str, str | int | tuple[int, ...] | list[int]],
+        **options: Any,
     ) -> Image:
         pass
 
@@ -2975,7 +3004,7 @@ class ImageTransformHandler:
 # Debugging
 
 
-def _wedge():
+def _wedge() -> Image:
     """Create grayscale wedge (for debugging only)"""
 
     return Image()._new(core.wedge("L"))
@@ -3037,16 +3066,22 @@ def new(
         color = ImageColor.getcolor(color, mode)
 
     im = Image()
-    if mode == "P" and isinstance(color, (list, tuple)) and len(color) in [3, 4]:
-        # RGB or RGBA value for a P image
-        from . import ImagePalette
+    if (
+        mode == "P"
+        and isinstance(color, (list, tuple))
+        and all(isinstance(i, int) for i in color)
+    ):
+        color_ints: tuple[int, ...] = cast(Tuple[int, ...], tuple(color))
+        if len(color_ints) == 3 or len(color_ints) == 4:
+            # RGB or RGBA value for a P image
+            from . import ImagePalette
 
-        im.palette = ImagePalette.ImagePalette()
-        color = im.palette.getcolor(color)
+            im.palette = ImagePalette.ImagePalette()
+            color = im.palette.getcolor(color_ints)
     return im._new(core.fill(mode, size, color))
 
 
-def frombytes(mode, size, data, decoder_name="raw", *args) -> Image:
+def frombytes(mode, size, data, decoder_name: str = "raw", *args) -> Image:
     """
     Creates a copy of an image memory from pixel data in a buffer.
 
@@ -3085,7 +3120,7 @@ def frombytes(mode, size, data, decoder_name="raw", *args) -> Image:
     return im
 
 
-def frombuffer(mode, size, data, decoder_name="raw", *args) -> Image:
+def frombuffer(mode: str, size, data, decoder_name: str = "raw", *args) -> Image:
     """
     Creates an image memory referencing pixel data in a byte buffer.
 
@@ -3576,7 +3611,9 @@ def register_mime(id: str, mimetype: str) -> None:
     MIME[id.upper()] = mimetype
 
 
-def register_save(id: str, driver) -> None:
+def register_save(
+    id: str, driver: Callable[[Image, IO[bytes], str | bytes], None]
+) -> None:
     """
     Registers an image save function.  This function should not be
     used in application code.
@@ -3587,7 +3624,9 @@ def register_save(id: str, driver) -> None:
     SAVE[id.upper()] = driver
 
 
-def register_save_all(id, driver) -> None:
+def register_save_all(
+    id: str, driver: Callable[[Image, IO[bytes], str | bytes], None]
+) -> None:
     """
     Registers an image function to save all the frames
     of a multiframe format.  This function should not be
@@ -3599,7 +3638,7 @@ def register_save_all(id, driver) -> None:
     SAVE_ALL[id.upper()] = driver
 
 
-def register_extension(id, extension) -> None:
+def register_extension(id: str, extension: str) -> None:
     """
     Registers an image extension.  This function should not be
     used in application code.
@@ -3610,7 +3649,7 @@ def register_extension(id, extension) -> None:
     EXTENSION[extension.lower()] = id.upper()
 
 
-def register_extensions(id, extensions) -> None:
+def register_extensions(id: str, extensions: list[str]) -> None:
     """
     Registers image extensions.  This function should not be
     used in application code.
@@ -3622,7 +3661,7 @@ def register_extensions(id, extensions) -> None:
         register_extension(id, extension)
 
 
-def registered_extensions():
+def registered_extensions() -> dict[str, str]:
     """
     Returns a dictionary containing all file extensions belonging
     to registered plugins
@@ -3661,7 +3700,7 @@ def register_encoder(name: str, encoder: type[ImageFile.PyEncoder]) -> None:
 # Simple display support.
 
 
-def _show(image, **options) -> None:
+def _show(image: Image, **options: Any) -> None:
     from . import ImageShow
 
     ImageShow.show(image, **options)
@@ -3671,7 +3710,9 @@ def _show(image, **options) -> None:
 # Effects
 
 
-def effect_mandelbrot(size, extent, quality):
+def effect_mandelbrot(
+    size: tuple[int, int], extent: tuple[int, int, int, int], quality: int
+) -> Image:
     """
     Generate a Mandelbrot set covering the given extent.
 
@@ -3684,7 +3725,7 @@ def effect_mandelbrot(size, extent, quality):
     return Image()._new(core.effect_mandelbrot(size, extent, quality))
 
 
-def effect_noise(size, sigma):
+def effect_noise(size: tuple[int, int], sigma: float) -> Image:
     """
     Generate Gaussian noise centered around 128.
 
@@ -3695,7 +3736,7 @@ def effect_noise(size, sigma):
     return Image()._new(core.effect_noise(size, sigma))
 
 
-def linear_gradient(mode):
+def linear_gradient(mode: str) -> Image:
     """
     Generate 256x256 linear gradient from black to white, top to bottom.
 
@@ -3704,7 +3745,7 @@ def linear_gradient(mode):
     return Image()._new(core.linear_gradient(mode))
 
 
-def radial_gradient(mode):
+def radial_gradient(mode: str) -> Image:
     """
     Generate 256x256 radial gradient from black to white, centre to edge.
 

src/PIL/ImageColor.py

@@ -25,7 +25,7 @@ from . import Image
 
 
 @lru_cache
-def getrgb(color):
+def getrgb(color: str) -> tuple[int, int, int] | tuple[int, int, int, int]:
     """
      Convert a color string to an RGB or RGBA tuple. If the string cannot be
      parsed, this function raises a :py:exc:`ValueError` exception.
@@ -44,8 +44,10 @@ def getrgb(color):
     if rgb:
         if isinstance(rgb, tuple):
             return rgb
-        colormap[color] = rgb = getrgb(rgb)
-        return rgb
+        rgb_tuple = getrgb(rgb)
+        assert len(rgb_tuple) == 3
+        colormap[color] = rgb_tuple
+        return rgb_tuple
 
     # check for known string formats
     if re.match("#[a-f0-9]{3}$", color):
@@ -88,15 +90,15 @@ def getrgb(color):
     if m:
         from colorsys import hls_to_rgb
 
-        rgb = hls_to_rgb(
+        rgb_floats = hls_to_rgb(
             float(m.group(1)) / 360.0,
             float(m.group(3)) / 100.0,
             float(m.group(2)) / 100.0,
         )
         return (
-            int(rgb[0] * 255 + 0.5),
-            int(rgb[1] * 255 + 0.5),
-            int(rgb[2] * 255 + 0.5),
+            int(rgb_floats[0] * 255 + 0.5),
+            int(rgb_floats[1] * 255 + 0.5),
+            int(rgb_floats[2] * 255 + 0.5),
         )
 
     m = re.match(
@@ -105,15 +107,15 @@ def getrgb(color):
     if m:
         from colorsys import hsv_to_rgb
 
-        rgb = hsv_to_rgb(
+        rgb_floats = hsv_to_rgb(
             float(m.group(1)) / 360.0,
             float(m.group(2)) / 100.0,
             float(m.group(3)) / 100.0,
         )
         return (
-            int(rgb[0] * 255 + 0.5),
-            int(rgb[1] * 255 + 0.5),
-            int(rgb[2] * 255 + 0.5),
+            int(rgb_floats[0] * 255 + 0.5),
+            int(rgb_floats[1] * 255 + 0.5),
+            int(rgb_floats[2] * 255 + 0.5),
         )
 
     m = re.match(r"rgba\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*\)$", color)
@@ -124,7 +126,7 @@ def getrgb(color):
 
 
 @lru_cache
-def getcolor(color, mode: str) -> tuple[int, ...]:
+def getcolor(color: str, mode: str) -> int | tuple[int, ...]:
     """
     Same as :py:func:`~PIL.ImageColor.getrgb` for most modes. However, if
     ``mode`` is HSV, converts the RGB value to a HSV value, or if ``mode`` is
@@ -136,33 +138,34 @@ def getcolor(color, mode: str) -> tuple[int, ...]:
 
     :param color: A color string
     :param mode: Convert result to this mode
-    :return: ``(graylevel[, alpha]) or (red, green, blue[, alpha])``
+    :return: ``graylevel, (graylevel, alpha) or (red, green, blue[, alpha])``
     """
     # same as getrgb, but converts the result to the given mode
-    color, alpha = getrgb(color), 255
-    if len(color) == 4:
-        color, alpha = color[:3], color[3]
+    rgb, alpha = getrgb(color), 255
+    if len(rgb) == 4:
+        alpha = rgb[3]
+        rgb = rgb[:3]
 
     if mode == "HSV":
         from colorsys import rgb_to_hsv
 
-        r, g, b = color
+        r, g, b = rgb
         h, s, v = rgb_to_hsv(r / 255, g / 255, b / 255)
         return int(h * 255), int(s * 255), int(v * 255)
     elif Image.getmodebase(mode) == "L":
-        r, g, b = color
+        r, g, b = rgb
         # ITU-R Recommendation 601-2 for nonlinear RGB
         # scaled to 24 bits to match the convert's implementation.
-        color = (r * 19595 + g * 38470 + b * 7471 + 0x8000) >> 16
+        graylevel = (r * 19595 + g * 38470 + b * 7471 + 0x8000) >> 16
         if mode[-1] == "A":
-            return color, alpha
-    else:
-        if mode[-1] == "A":
-            return color + (alpha,)
-    return color
+            return graylevel, alpha
+        return graylevel
+    elif mode[-1] == "A":
+        return rgb + (alpha,)
+    return rgb
 
 
-colormap = {
+colormap: dict[str, str | tuple[int, int, int]] = {
     # X11 colour table from https://drafts.csswg.org/css-color-4/, with
     # gray/grey spelling issues fixed.  This is a superset of HTML 4.0
     # colour names used in CSS 1.

src/PIL/ImageDraw.py

@@ -34,9 +34,10 @@ from __future__ import annotations
 import math
 import numbers
 import struct
-from typing import TYPE_CHECKING, Sequence, cast
+from typing import TYPE_CHECKING, AnyStr, Sequence, cast
 
 from . import Image, ImageColor
+from ._deprecate import deprecate
 from ._typing import Coords
 
 """
@@ -95,7 +96,9 @@ class ImageDraw:
     if TYPE_CHECKING:
         from . import ImageFont
 
-    def getfont(self) -> ImageFont.FreeTypeFont | ImageFont.ImageFont:
+    def getfont(
+        self,
+    ) -> ImageFont.ImageFont | ImageFont.FreeTypeFont | ImageFont.TransposedFont:
         """
         Get the current default font.
 
@@ -120,14 +123,15 @@ class ImageDraw:
             self.font = ImageFont.load_default()
         return self.font
 
-    def _getfont(self, font_size: float | None):
+    def _getfont(
+        self, font_size: float | None
+    ) -> ImageFont.ImageFont | ImageFont.FreeTypeFont | ImageFont.TransposedFont:
         if font_size is not None:
             from . import ImageFont
 
-            font = ImageFont.load_default(font_size)
+            return ImageFont.load_default(font_size)
         else:
-            font = self.getfont()
-        return font
+            return self.getfont()
 
     def _getink(self, ink, fill=None) -> tuple[int | None, int | None]:
         if ink is None and fill is None:
@@ -216,7 +220,9 @@ class ImageDraw:
                         # This is a straight line, so no joint is required
                         continue
 
-                    def coord_at_angle(coord, angle):
+                    def coord_at_angle(
+                        coord: Sequence[float], angle: float
+                    ) -> tuple[float, float]:
                         x, y = coord
                         angle -= 90
                         distance = width / 2 - 1
@@ -460,15 +466,13 @@ class ImageDraw:
                     right[3] -= r + 1
                 self.draw.draw_rectangle(right, ink, 1)
 
-    def _multiline_check(self, text) -> bool:
+    def _multiline_check(self, text: AnyStr) -> bool:
         split_character = "\n" if isinstance(text, str) else b"\n"
 
         return split_character in text
 
-    def _multiline_split(self, text) -> list[str | bytes]:
-        split_character = "\n" if isinstance(text, str) else b"\n"
-
-        return text.split(split_character)
+    def _multiline_split(self, text: AnyStr) -> list[AnyStr]:
+        return text.split("\n" if isinstance(text, str) else b"\n")
 
     def _multiline_spacing(self, font, spacing, stroke_width):
         return (
@@ -479,10 +483,15 @@ class ImageDraw:
 
     def text(
         self,
-        xy,
-        text,
+        xy: tuple[float, float],
+        text: str,
         fill=None,
-        font=None,
+        font: (
+            ImageFont.ImageFont
+            | ImageFont.FreeTypeFont
+            | ImageFont.TransposedFont
+            | None
+        ) = None,
         anchor=None,
         spacing=4,
         align="left",
@@ -536,7 +545,7 @@ class ImageDraw:
                 coord.append(int(xy[i]))
                 start.append(math.modf(xy[i])[0])
             try:
-                mask, offset = font.getmask2(
+                mask, offset = font.getmask2(  # type: ignore[union-attr,misc]
                     text,
                     mode,
                     direction=direction,
@@ -552,7 +561,7 @@ class ImageDraw:
                 coord = [coord[0] + offset[0], coord[1] + offset[1]]
             except AttributeError:
                 try:
-                    mask = font.getmask(
+                    mask = font.getmask(  # type: ignore[misc]
                         text,
                         mode,
                         direction,
@@ -601,10 +610,15 @@ class ImageDraw:
 
     def multiline_text(
         self,
-        xy,
-        text,
+        xy: tuple[float, float],
+        text: str,
         fill=None,
-        font=None,
+        font: (
+            ImageFont.ImageFont
+            | ImageFont.FreeTypeFont
+            | ImageFont.TransposedFont
+            | None
+        ) = None,
         anchor=None,
         spacing=4,
         align="left",
@@ -634,7 +648,7 @@ class ImageDraw:
             font = self._getfont(font_size)
 
         widths = []
-        max_width = 0
+        max_width: float = 0
         lines = self._multiline_split(text)
         line_spacing = self._multiline_spacing(font, spacing, stroke_width)
         for line in lines:
@@ -688,15 +702,20 @@ class ImageDraw:
 
     def textlength(
         self,
-        text,
-        font=None,
+        text: str,
+        font: (
+            ImageFont.ImageFont
+            | ImageFont.FreeTypeFont
+            | ImageFont.TransposedFont
+            | None
+        ) = None,
         direction=None,
         features=None,
         language=None,
         embedded_color=False,
         *,
         font_size=None,
-    ):
+    ) -> float:
         """Get the length of a given string, in pixels with 1/64 precision."""
         if self._multiline_check(text):
             msg = "can't measure length of multiline text"
@@ -788,7 +807,7 @@ class ImageDraw:
             font = self._getfont(font_size)
 
         widths = []
-        max_width = 0
+        max_width: float = 0
         lines = self._multiline_split(text)
         line_spacing = self._multiline_spacing(font, spacing, stroke_width)
         for line in lines:
@@ -886,26 +905,17 @@ except AttributeError:
 
 def getdraw(im=None, hints=None):
     """
-    (Experimental) A more advanced 2D drawing interface for PIL images,
-    based on the WCK interface.
-
     :param im: The image to draw in.
-    :param hints: An optional list of hints.
+    :param hints: An optional list of hints. Deprecated.
     :returns: A (drawing context, drawing resource factory) tuple.
     """
-    # FIXME: this needs more work!
-    # FIXME: come up with a better 'hints' scheme.
-    handler = None
-    if not hints or "nicest" in hints:
-        try:
-            from . import _imagingagg as handler
-        except ImportError:
-            pass
-    if handler is None:
-        from . import ImageDraw2 as handler
+    if hints is not None:
+        deprecate("'hints' parameter", 12)
+    from . import ImageDraw2
+
     if im:
-        im = handler.Draw(im)
-    return im, handler
+        im = ImageDraw2.Draw(im)
+    return im, ImageDraw2
 
 
 def floodfill(
@@ -1096,11 +1106,13 @@ def _compute_regular_polygon_vertices(
     return [_compute_polygon_vertex(angle) for angle in angles]
 
 
-def _color_diff(color1, color2: float | tuple[int, ...]) -> float:
+def _color_diff(
+    color1: float | tuple[int, ...], color2: float | tuple[int, ...]
+) -> float:
     """
     Uses 1-norm distance to calculate difference between two values.
     """
-    if isinstance(color2, tuple):
-        return sum(abs(color1[i] - color2[i]) for i in range(0, len(color2)))
-    else:
-        return abs(color1 - color2)
+    first = color1 if isinstance(color1, tuple) else (color1,)
+    second = color2 if isinstance(color2, tuple) else (color2,)
+
+    return sum(abs(first[i] - second[i]) for i in range(0, len(second)))

src/PIL/ImageDraw2.py

@@ -30,7 +30,7 @@ from . import Image, ImageColor, ImageDraw, ImageFont, ImagePath
 class Pen:
     """Stores an outline color and width."""
 
-    def __init__(self, color, width=1, opacity=255):
+    def __init__(self, color: str, width: int = 1, opacity: int = 255) -> None:
         self.color = ImageColor.getrgb(color)
         self.width = width
 
@@ -38,7 +38,7 @@ class Pen:
 class Brush:
     """Stores a fill color"""
 
-    def __init__(self, color, opacity=255):
+    def __init__(self, color: str, opacity: int = 255) -> None:
         self.color = ImageColor.getrgb(color)
 
 
@@ -63,7 +63,7 @@ class Draw:
         self.image = image
         self.transform = None
 
-    def flush(self):
+    def flush(self) -> Image.Image:
         return self.image
 
     def render(self, op, xy, pen, brush=None):

src/PIL/ImageEnhance.py

@@ -23,7 +23,10 @@ from . import Image, ImageFilter, ImageStat
 
 
 class _Enhance:
-    def enhance(self, factor):
+    image: Image.Image
+    degenerate: Image.Image
+
+    def enhance(self, factor: float) -> Image.Image:
         """
         Returns an enhanced image.
 
@@ -46,7 +49,7 @@ class Color(_Enhance):
     the original image.
     """
 
-    def __init__(self, image):
+    def __init__(self, image: Image.Image) -> None:
         self.image = image
         self.intermediate_mode = "L"
         if "A" in image.getbands():
@@ -63,7 +66,7 @@ class Contrast(_Enhance):
     gives a solid gray image. A factor of 1.0 gives the original image.
     """
 
-    def __init__(self, image):
+    def __init__(self, image: Image.Image) -> None:
         self.image = image
         mean = int(ImageStat.Stat(image.convert("L")).mean[0] + 0.5)
         self.degenerate = Image.new("L", image.size, mean).convert(image.mode)
@@ -80,7 +83,7 @@ class Brightness(_Enhance):
     original image.
     """
 
-    def __init__(self, image):
+    def __init__(self, image: Image.Image) -> None:
         self.image = image
         self.degenerate = Image.new(image.mode, image.size, 0)
 
@@ -96,7 +99,7 @@ class Sharpness(_Enhance):
     original image, and a factor of 2.0 gives a sharpened image.
     """
 
-    def __init__(self, image):
+    def __init__(self, image: Image.Image) -> None:
         self.image = image
         self.degenerate = image.filter(ImageFilter.SMOOTH)
 

src/PIL/ImageFile.py

@@ -28,6 +28,7 @@
 #
 from __future__ import annotations
 
+import abc
 import io
 import itertools
 import struct
@@ -347,6 +348,15 @@ class ImageFile(Image.Image):
         return self.tell() != frame
 
 
+class StubHandler:
+    def open(self, im: StubImageFile) -> None:
+        pass
+
+    @abc.abstractmethod
+    def load(self, im: StubImageFile) -> Image.Image:
+        pass
+
+
 class StubImageFile(ImageFile):
     """
     Base class for stub image loaders.
@@ -477,7 +487,7 @@ class Parser:
     def __enter__(self):
         return self
 
-    def __exit__(self, *args):
+    def __exit__(self, *args: object) -> None:
         self.close()
 
     def close(self):
@@ -753,7 +763,7 @@ class PyEncoder(PyCodec):
     def pushes_fd(self):
         return self._pushes_fd
 
-    def encode(self, bufsize):
+    def encode(self, bufsize: int) -> tuple[int, int, bytes]:
         """
         Override to perform the encoding process.
 

src/PIL/ImageFilter.py

@@ -18,6 +18,8 @@ from __future__ import annotations
 
 import abc
 import functools
+from types import ModuleType
+from typing import Any, Sequence
 
 
 class Filter:
@@ -56,7 +58,13 @@ class Kernel(BuiltinFilter):
 
     name = "Kernel"
 
-    def __init__(self, size, kernel, scale=None, offset=0):
+    def __init__(
+        self,
+        size: tuple[int, int],
+        kernel: Sequence[float],
+        scale: float | None = None,
+        offset: float = 0,
+    ) -> None:
         if scale is None:
             # default scale is sum of kernel
             scale = functools.reduce(lambda a, b: a + b, kernel)
@@ -79,7 +87,7 @@ class RankFilter(Filter):
 
     name = "Rank"
 
-    def __init__(self, size, rank):
+    def __init__(self, size: int, rank: int) -> None:
         self.size = size
         self.rank = rank
 
@@ -101,7 +109,7 @@ class MedianFilter(RankFilter):
 
     name = "Median"
 
-    def __init__(self, size=3):
+    def __init__(self, size: int = 3) -> None:
         self.size = size
         self.rank = size * size // 2
 
@@ -116,7 +124,7 @@ class MinFilter(RankFilter):
 
     name = "Min"
 
-    def __init__(self, size=3):
+    def __init__(self, size: int = 3) -> None:
         self.size = size
         self.rank = 0
 
@@ -131,7 +139,7 @@ class MaxFilter(RankFilter):
 
     name = "Max"
 
-    def __init__(self, size=3):
+    def __init__(self, size: int = 3) -> None:
         self.size = size
         self.rank = size * size - 1
 
@@ -147,7 +155,7 @@ class ModeFilter(Filter):
 
     name = "Mode"
 
-    def __init__(self, size=3):
+    def __init__(self, size: int = 3) -> None:
         self.size = size
 
     def filter(self, image):
@@ -165,7 +173,7 @@ class GaussianBlur(MultibandFilter):
 
     name = "GaussianBlur"
 
-    def __init__(self, radius=2):
+    def __init__(self, radius: float | Sequence[float] = 2) -> None:
         self.radius = radius
 
     def filter(self, image):
@@ -193,10 +201,8 @@ class BoxBlur(MultibandFilter):
 
     name = "BoxBlur"
 
-    def __init__(self, radius):
-        xy = radius
-        if not isinstance(xy, (tuple, list)):
-            xy = (xy, xy)
+    def __init__(self, radius: float | Sequence[float]) -> None:
+        xy = radius if isinstance(radius, (tuple, list)) else (radius, radius)
         if xy[0] < 0 or xy[1] < 0:
             msg = "radius must be >= 0"
             raise ValueError(msg)
@@ -228,7 +234,9 @@ class UnsharpMask(MultibandFilter):
 
     name = "UnsharpMask"
 
-    def __init__(self, radius=2, percent=150, threshold=3):
+    def __init__(
+        self, radius: float = 2, percent: int = 150, threshold: int = 3
+    ) -> None:
         self.radius = radius
         self.percent = percent
         self.threshold = threshold
@@ -378,7 +386,9 @@ class Color3DLUT(MultibandFilter):
 
     name = "Color 3D LUT"
 
-    def __init__(self, size, table, channels=3, target_mode=None, **kwargs):
+    def __init__(
+        self, size, table, channels: int = 3, target_mode: str | None = None, **kwargs
+    ):
         if channels not in (3, 4):
             msg = "Only 3 or 4 output channels are supported"
             raise ValueError(msg)
@@ -392,7 +402,7 @@ class Color3DLUT(MultibandFilter):
         items = size[0] * size[1] * size[2]
         wrong_size = False
 
-        numpy = None
+        numpy: ModuleType | None = None
         if hasattr(table, "shape"):
             try:
                 import numpy
@@ -439,7 +449,7 @@ class Color3DLUT(MultibandFilter):
         self.table = table
 
     @staticmethod
-    def _check_size(size):
+    def _check_size(size: Any) -> list[int]:
         try:
             _, _, _ = size
         except ValueError as e:

src/PIL/ImageFont.py

@@ -33,11 +33,16 @@ import sys
 import warnings
 from enum import IntEnum
 from io import BytesIO
-from typing import BinaryIO
+from typing import IO, TYPE_CHECKING, Any, BinaryIO
 
 from . import Image
 from ._typing import StrOrBytesPath
-from ._util import is_directory, is_path
+from ._util import is_path
+
+if TYPE_CHECKING:
+    from . import ImageFile
+    from ._imaging import ImagingFont
+    from ._imagingft import Font
 
 
 class Layout(IntEnum):
@@ -56,7 +61,7 @@ except ImportError as ex:
     core = DeferredError.new(ex)
 
 
-def _string_length_check(text):
+def _string_length_check(text: str | bytes | bytearray) -> None:
     if MAX_STRING_LENGTH is not None and len(text) > MAX_STRING_LENGTH:
         msg = "too many characters in string"
         raise ValueError(msg)
@@ -81,9 +86,11 @@ def _string_length_check(text):
 class ImageFont:
     """PIL font wrapper"""
 
-    def _load_pilfont(self, filename):
+    font: ImagingFont
+
+    def _load_pilfont(self, filename: str) -> None:
         with open(filename, "rb") as fp:
-            image = None
+            image: ImageFile.ImageFile | None = None
             for ext in (".png", ".gif", ".pbm"):
                 if image:
                     image.close()
@@ -106,7 +113,7 @@ class ImageFont:
             self._load_pilfont_data(fp, image)
             image.close()
 
-    def _load_pilfont_data(self, file, image):
+    def _load_pilfont_data(self, file: IO[bytes], image: Image.Image) -> None:
         # read PILfont header
         if file.readline() != b"PILfont\n":
             msg = "Not a PILfont file"
@@ -153,7 +160,9 @@ class ImageFont:
         Image._decompression_bomb_check(self.font.getsize(text))
         return self.font.getmask(text, mode)
 
-    def getbbox(self, text, *args, **kwargs):
+    def getbbox(
+        self, text: str | bytes | bytearray, *args: Any, **kwargs: Any
+    ) -> tuple[int, int, int, int]:
         """
         Returns bounding box (in pixels) of given text.
 
@@ -167,7 +176,9 @@ class ImageFont:
         width, height = self.font.getsize(text)
         return 0, 0, width, height
 
-    def getlength(self, text, *args, **kwargs):
+    def getlength(
+        self, text: str | bytes | bytearray, *args: Any, **kwargs: Any
+    ) -> int:
         """
         Returns length (in pixels) of given text.
         This is the amount by which following text should be offset.
@@ -187,6 +198,8 @@ class ImageFont:
 class FreeTypeFont:
     """FreeType font wrapper (requires _imagingft service)"""
 
+    font: Font
+
     def __init__(
         self,
         font: StrOrBytesPath | BinaryIO | None = None,
@@ -250,14 +263,14 @@ class FreeTypeFont:
         path, size, index, encoding, layout_engine = state
         self.__init__(path, size, index, encoding, layout_engine)
 
-    def getname(self):
+    def getname(self) -> tuple[str | None, str | None]:
         """
         :return: A tuple of the font family (e.g. Helvetica) and the font style
             (e.g. Bold)
         """
         return self.font.family, self.font.style
 
-    def getmetrics(self):
+    def getmetrics(self) -> tuple[int, int]:
         """
         :return: A tuple of the font ascent (the distance from the baseline to
             the highest outline point) and descent (the distance from the
@@ -265,7 +278,9 @@ class FreeTypeFont:
         """
         return self.font.ascent, self.font.descent
 
-    def getlength(self, text, mode="", direction=None, features=None, language=None):
+    def getlength(
+        self, text: str, mode="", direction=None, features=None, language=None
+    ) -> float:
         """
         Returns length (in pixels with 1/64 precision) of given text when rendered
         in font with provided direction, features, and language.
@@ -339,14 +354,14 @@ class FreeTypeFont:
 
     def getbbox(
         self,
-        text,
-        mode="",
-        direction=None,
-        features=None,
-        language=None,
-        stroke_width=0,
-        anchor=None,
-    ):
+        text: str,
+        mode: str = "",
+        direction: str | None = None,
+        features: list[str] | None = None,
+        language: str | None = None,
+        stroke_width: float = 0,
+        anchor: str | None = None,
+    ) -> tuple[float, float, float, float]:
         """
         Returns bounding box (in pixels) of given text relative to given anchor
         when rendered in font with provided direction, features, and language.
@@ -496,7 +511,7 @@ class FreeTypeFont:
 
     def getmask2(
         self,
-        text,
+        text: str,
         mode="",
         direction=None,
         features=None,
@@ -624,7 +639,7 @@ class FreeTypeFont:
             layout_engine=layout_engine or self.layout_engine,
         )
 
-    def get_variation_names(self):
+    def get_variation_names(self) -> list[bytes]:
         """
         :returns: A list of the named styles in a variation font.
         :exception OSError: If the font is not a variation font.
@@ -666,10 +681,11 @@ class FreeTypeFont:
             msg = "FreeType 2.9.1 or greater is required"
             raise NotImplementedError(msg) from e
         for axis in axes:
-            axis["name"] = axis["name"].replace(b"\x00", b"")
+            if axis["name"]:
+                axis["name"] = axis["name"].replace(b"\x00", b"")
         return axes
 
-    def set_variation_by_axes(self, axes):
+    def set_variation_by_axes(self, axes: list[float]) -> None:
         """
         :param axes: A list of values for each axis.
         :exception OSError: If the font is not a variation font.
@@ -714,14 +730,14 @@ class TransposedFont:
             return 0, 0, height, width
         return 0, 0, width, height
 
-    def getlength(self, text, *args, **kwargs):
+    def getlength(self, text: str, *args, **kwargs) -> float:
         if self.orientation in (Image.Transpose.ROTATE_90, Image.Transpose.ROTATE_270):
             msg = "text length is undefined for text rotated by 90 or 270 degrees"
             raise ValueError(msg)
         return self.font.getlength(text, *args, **kwargs)
 
 
-def load(filename):
+def load(filename: str) -> ImageFont:
     """
     Load a font file.  This function loads a font object from the given
     bitmap font file, and returns the corresponding font object.
@@ -735,7 +751,13 @@ def load(filename):
     return f
 
 
-def truetype(font=None, size=10, index=0, encoding="", layout_engine=None):
+def truetype(
+    font: StrOrBytesPath | BinaryIO | None = None,
+    size: float = 10,
+    index: int = 0,
+    encoding: str = "",
+    layout_engine: Layout | None = None,
+) -> FreeTypeFont:
     """
     Load a TrueType or OpenType font from a file or file-like object,
     and create a font object.
@@ -796,7 +818,7 @@ def truetype(font=None, size=10, index=0, encoding="", layout_engine=None):
     :exception ValueError: If the font size is not greater than zero.
     """
 
-    def freetype(font):
+    def freetype(font: StrOrBytesPath | BinaryIO | None) -> FreeTypeFont:
         return FreeTypeFont(font, size, index, encoding, layout_engine)
 
     try:
@@ -846,7 +868,7 @@ def truetype(font=None, size=10, index=0, encoding="", layout_engine=None):
         raise
 
 
-def load_path(filename):
+def load_path(filename: str | bytes) -> ImageFont:
     """
     Load font file. Same as :py:func:`~PIL.ImageFont.load`, but searches for a
     bitmap font along the Python path.
@@ -855,14 +877,13 @@ def load_path(filename):
     :return: A font object.
     :exception OSError: If the file could not be read.
     """
+    if not isinstance(filename, str):
+        filename = filename.decode("utf-8")
     for directory in sys.path:
-        if is_directory(directory):
-            if not isinstance(filename, str):
-                filename = filename.decode("utf-8")
-            try:
-                return load(os.path.join(directory, filename))
-            except OSError:
-                pass
+        try:
+            return load(os.path.join(directory, filename))
+        except OSError:
+            pass
     msg = "cannot find font file"
     raise OSError(msg)
 
@@ -881,6 +902,7 @@ def load_default(size: float | None = None) -> FreeTypeFont | ImageFont:
 
     :return: A font object.
     """
+    f: FreeTypeFont | ImageFont
     if core.__class__.__name__ == "module" or size is not None:
         f = truetype(
             BytesIO(

src/PIL/ImageMorph.py

@@ -200,7 +200,7 @@ class MorphOp:
         elif patterns is not None:
             self.lut = LutBuilder(patterns=patterns).build_lut()
 
-    def apply(self, image: Image.Image):
+    def apply(self, image: Image.Image) -> tuple[int, Image.Image]:
         """Run a single morphological operation on an image
 
         Returns a tuple of the number of changed pixels and the
@@ -216,7 +216,7 @@ class MorphOp:
         count = _imagingmorph.apply(bytes(self.lut), image.im.id, outimage.im.id)
         return count, outimage
 
-    def match(self, image: Image.Image):
+    def match(self, image: Image.Image) -> list[tuple[int, int]]:
         """Get a list of coordinates matching the morphological operation on
         an image.
 
@@ -231,7 +231,7 @@ class MorphOp:
             raise ValueError(msg)
         return _imagingmorph.match(bytes(self.lut), image.im.id)
 
-    def get_on_pixels(self, image: Image.Image):
+    def get_on_pixels(self, image: Image.Image) -> list[tuple[int, int]]:
         """Get a list of all turned on pixels in a binary image
 
         Returns a list of tuples of (x,y) coordinates

src/PIL/ImageOps.py

@@ -497,7 +497,7 @@ def expand(
     color = _color(fill, image.mode)
     if image.palette:
         palette = ImagePalette.ImagePalette(palette=image.getpalette())
-        if isinstance(color, tuple):
+        if isinstance(color, tuple) and (len(color) == 3 or len(color) == 4):
             color = palette.getcolor(color)
     else:
         palette = None

src/PIL/ImagePalette.py

@@ -18,10 +18,13 @@
 from __future__ import annotations
 
 import array
-from typing import Sequence
+from typing import IO, TYPE_CHECKING, Sequence
 
 from . import GimpGradientFile, GimpPaletteFile, ImageColor, PaletteFile
 
+if TYPE_CHECKING:
+    from . import Image
+
 
 class ImagePalette:
     """
@@ -128,7 +131,11 @@ class ImagePalette:
                 raise ValueError(msg) from e
         return index
 
-    def getcolor(self, color, image=None) -> int:
+    def getcolor(
+        self,
+        color: tuple[int, int, int] | tuple[int, int, int, int],
+        image: Image.Image | None = None,
+    ) -> int:
         """Given an rgb tuple, allocate palette entry.
 
         .. warning:: This method is experimental.
@@ -163,10 +170,10 @@ class ImagePalette:
                 self.dirty = 1
                 return index
         else:
-            msg = f"unknown color specifier: {repr(color)}"
+            msg = f"unknown color specifier: {repr(color)}"  # type: ignore[unreachable]
             raise ValueError(msg)
 
-    def save(self, fp):
+    def save(self, fp: str | IO[str]) -> None:
         """Save palette to text file.
 
         .. warning:: This method is experimental.
@@ -213,29 +220,29 @@ def make_linear_lut(black, white):
     raise NotImplementedError(msg)  # FIXME
 
 
-def make_gamma_lut(exp):
+def make_gamma_lut(exp: float) -> list[int]:
     return [int(((i / 255.0) ** exp) * 255.0 + 0.5) for i in range(256)]
 
 
-def negative(mode="RGB"):
+def negative(mode: str = "RGB") -> ImagePalette:
     palette = list(range(256 * len(mode)))
     palette.reverse()
     return ImagePalette(mode, [i // len(mode) for i in palette])
 
 
-def random(mode="RGB"):
+def random(mode: str = "RGB") -> ImagePalette:
     from random import randint
 
     palette = [randint(0, 255) for _ in range(256 * len(mode))]
     return ImagePalette(mode, palette)
 
 
-def sepia(white="#fff0c0"):
+def sepia(white: str = "#fff0c0") -> ImagePalette:
     bands = [make_linear_lut(0, band) for band in ImageColor.getrgb(white)]
     return ImagePalette("RGB", [bands[i % 3][i // 3] for i in range(256 * 3)])
 
 
-def wedge(mode="RGB"):
+def wedge(mode: str = "RGB") -> ImagePalette:
     palette = list(range(256 * len(mode)))
     return ImagePalette(mode, [i // len(mode) for i in palette])
 

src/PIL/ImageTk.py

@@ -37,7 +37,7 @@ from . import Image
 _pilbitmap_ok = None
 
 
-def _pilbitmap_check():
+def _pilbitmap_check() -> int:
     global _pilbitmap_ok
     if _pilbitmap_ok is None:
         try:
@@ -162,7 +162,7 @@ class PhotoImage:
         """
         return self.__size[1]
 
-    def paste(self, im):
+    def paste(self, im: Image.Image) -> None:
         """
         Paste a PIL image into the photo image.  Note that this can
         be very slow if the photo image is displayed.
@@ -254,7 +254,7 @@ class BitmapImage:
         return str(self.__photo)
 
 
-def getimage(photo):
+def getimage(photo: PhotoImage) -> Image.Image:
     """Copies the contents of a PhotoImage to a PIL image memory."""
     im = Image.new("RGBA", (photo.width(), photo.height()))
     block = im.im

src/PIL/ImageTransform.py

@@ -14,7 +14,7 @@
 #
 from __future__ import annotations
 
-from typing import Sequence
+from typing import Any, Sequence
 
 from . import Image
 
@@ -34,7 +34,7 @@ class Transform(Image.ImageTransformHandler):
         self,
         size: tuple[int, int],
         image: Image.Image,
-        **options: dict[str, str | int | tuple[int, ...] | list[int]],
+        **options: Any,
     ) -> Image.Image:
         """Perform the transform. Called from :py:meth:`.Image.transform`."""
         # can be overridden

src/PIL/ImageWin.py

@@ -28,10 +28,10 @@ class HDC:
     methods.
     """
 
-    def __init__(self, dc):
+    def __init__(self, dc: int) -> None:
         self.dc = dc
 
-    def __int__(self):
+    def __int__(self) -> int:
         return self.dc
 
 
@@ -42,10 +42,10 @@ class HWND:
     methods, instead of a DC.
     """
 
-    def __init__(self, wnd):
+    def __init__(self, wnd: int) -> None:
         self.wnd = wnd
 
-    def __int__(self):
+    def __int__(self) -> int:
         return self.wnd
 
 
@@ -149,7 +149,9 @@ class Dib:
             result = self.image.query_palette(handle)
         return result
 
-    def paste(self, im, box=None):
+    def paste(
+        self, im: Image.Image, box: tuple[int, int, int, int] | None = None
+    ) -> None:
         """
         Paste a PIL image into the bitmap image.
 
@@ -169,16 +171,16 @@ class Dib:
         else:
             self.image.paste(im.im)
 
-    def frombytes(self, buffer):
+    def frombytes(self, buffer: bytes) -> None:
         """
         Load display memory contents from byte data.
 
         :param buffer: A buffer containing display data (usually
                        data returned from :py:func:`~PIL.ImageWin.Dib.tobytes`)
         """
-        return self.image.frombytes(buffer)
+        self.image.frombytes(buffer)
 
-    def tobytes(self):
+    def tobytes(self) -> bytes:
         """
         Copy display memory contents to bytes object.
 
@@ -190,7 +192,9 @@ class Dib:
 class Window:
     """Create a Window with the given title size."""
 
-    def __init__(self, title="PIL", width=None, height=None):
+    def __init__(
+        self, title: str = "PIL", width: int | None = None, height: int | None = None
+    ) -> None:
         self.hwnd = Image.core.createwindow(
             title, self.__dispatcher, width or 0, height or 0
         )

src/PIL/Jpeg2KImagePlugin.py

@@ -18,6 +18,7 @@ from __future__ import annotations
 import io
 import os
 import struct
+from typing import IO, Tuple, cast
 
 from . import Image, ImageFile, ImagePalette, _binary
 
@@ -34,7 +35,7 @@ class BoxReader:
         self.length = length
         self.remaining_in_box = -1
 
-    def _can_read(self, num_bytes):
+    def _can_read(self, num_bytes: int) -> bool:
         if self.has_length and self.fp.tell() + num_bytes > self.length:
             # Outside box: ensure we don't read past the known file length
             return False
@@ -44,7 +45,7 @@ class BoxReader:
         else:
             return True  # No length known, just read
 
-    def _read_bytes(self, num_bytes):
+    def _read_bytes(self, num_bytes: int) -> bytes:
         if not self._can_read(num_bytes):
             msg = "Not enough data in header"
             raise SyntaxError(msg)
@@ -58,7 +59,7 @@ class BoxReader:
             self.remaining_in_box -= num_bytes
         return data
 
-    def read_fields(self, field_format):
+    def read_fields(self, field_format: str) -> tuple[int | bytes, ...]:
         size = struct.calcsize(field_format)
         data = self._read_bytes(size)
         return struct.unpack(field_format, data)
@@ -74,16 +75,16 @@ class BoxReader:
         else:
             return True
 
-    def next_box_type(self):
+    def next_box_type(self) -> bytes:
         # Skip the rest of the box if it has not been read
         if self.remaining_in_box > 0:
             self.fp.seek(self.remaining_in_box, os.SEEK_CUR)
         self.remaining_in_box = -1
 
         # Read the length and type of the next box
-        lbox, tbox = self.read_fields(">I4s")
+        lbox, tbox = cast(Tuple[int, bytes], self.read_fields(">I4s"))
         if lbox == 1:
-            lbox = self.read_fields(">Q")[0]
+            lbox = cast(int, self.read_fields(">Q")[0])
             hlen = 16
         else:
             hlen = 8
@@ -126,12 +127,13 @@ def _parse_codestream(fp):
     return size, mode
 
 
-def _res_to_dpi(num, denom, exp):
+def _res_to_dpi(num: int, denom: int, exp: int) -> float | None:
     """Convert JPEG2000's (numerator, denominator, exponent-base-10) resolution,
     calculated as (num / denom) * 10^exp and stored in dots per meter,
     to floating-point dots per inch."""
-    if denom != 0:
-        return (254 * num * (10**exp)) / (10000 * denom)
+    if denom == 0:
+        return None
+    return (254 * num * (10**exp)) / (10000 * denom)
 
 
 def _parse_jp2_header(fp):
@@ -328,11 +330,13 @@ def _accept(prefix: bytes) -> bool:
 # Save support
 
 
-def _save(im, fp, filename):
+def _save(im: Image.Image, fp: IO[bytes], filename: str | bytes) -> None:
     # Get the keyword arguments
     info = im.encoderinfo
 
-    if filename.endswith(".j2k") or info.get("no_jp2", False):
+    if isinstance(filename, str):
+        filename = filename.encode()
+    if filename.endswith(b".j2k") or info.get("no_jp2", False):
         kind = "j2k"
     else:
         kind = "jp2"

src/PIL/JpegImagePlugin.py

@@ -42,6 +42,7 @@ import subprocess
 import sys
 import tempfile
 import warnings
+from typing import IO, Any
 
 from . import Image, ImageFile
 from ._binary import i16be as i16
@@ -54,7 +55,7 @@ from .JpegPresets import presets
 # Parser
 
 
-def Skip(self, marker):
+def Skip(self: JpegImageFile, marker: int) -> None:
     n = i16(self.fp.read(2)) - 2
     ImageFile._safe_read(self.fp, n)
 
@@ -191,7 +192,7 @@ def APP(self, marker):
             self.info["dpi"] = 72, 72
 
 
-def COM(self, marker):
+def COM(self: JpegImageFile, marker: int) -> None:
     #
     # Comment marker.  Store these in the APP dictionary.
     n = i16(self.fp.read(2)) - 2
@@ -202,7 +203,7 @@ def COM(self, marker):
     self.applist.append(("COM", s))
 
 
-def SOF(self, marker):
+def SOF(self: JpegImageFile, marker: int) -> None:
     #
     # Start of frame marker.  Defines the size and mode of the
     # image.  JPEG is colour blind, so we use some simple
@@ -250,7 +251,7 @@ def SOF(self, marker):
         self.layer.append((t[0], t[1] // 16, t[1] & 15, t[2]))
 
 
-def DQT(self, marker):
+def DQT(self: JpegImageFile, marker: int) -> None:
     #
     # Define quantization table.  Note that there might be more
     # than one table in each marker.
@@ -425,7 +426,7 @@ class JpegImageFile(ImageFile.ImageFile):
         return s
 
     def draft(
-        self, mode: str, size: tuple[int, int]
+        self, mode: str | None, size: tuple[int, int]
     ) -> tuple[str, tuple[int, int, float, float]] | None:
         if len(self.tile) != 1:
             return None
@@ -493,13 +494,13 @@ class JpegImageFile(ImageFile.ImageFile):
 
         self.tile = []
 
-    def _getexif(self):
+    def _getexif(self) -> dict[str, Any] | None:
         return _getexif(self)
 
     def _getmp(self):
         return _getmp(self)
 
-    def getxmp(self):
+    def getxmp(self) -> dict[str, Any]:
         """
         Returns a dictionary containing the XMP tags.
         Requires defusedxml to be installed.
@@ -515,7 +516,7 @@ class JpegImageFile(ImageFile.ImageFile):
         return {}
 
 
-def _getexif(self):
+def _getexif(self) -> dict[str, Any] | None:
     if "exif" not in self.info:
         return None
     return self.getexif()._get_merged_dict()
@@ -643,7 +644,7 @@ def get_sampling(im):
     return samplings.get(sampling, -1)
 
 
-def _save(im, fp, filename):
+def _save(im: Image.Image, fp: IO[bytes], filename: str | bytes) -> None:
     if im.width == 0 or im.height == 0:
         msg = "cannot write empty image as JPEG"
         raise ValueError(msg)
@@ -826,7 +827,7 @@ def _save(im, fp, filename):
     ImageFile._save(im, fp, [("jpeg", (0, 0) + im.size, 0, rawmode)], bufsize)
 
 
-def _save_cjpeg(im, fp, filename):
+def _save_cjpeg(im: Image.Image, fp: IO[bytes], filename: str | bytes) -> None:
     # ALTERNATIVE: handle JPEGs via the IJG command line utilities.
     tempfile = im._dump()
     subprocess.check_call(["cjpeg", "-outfile", filename, tempfile])

src/PIL/MicImagePlugin.py

@@ -93,7 +93,7 @@ class MicImageFile(TiffImagePlugin.TiffImageFile):
         self.ole.close()
         super().close()
 
-    def __exit__(self, *args):
+    def __exit__(self, *args: object) -> None:
         self.__fp.close()
         self.ole.close()
         super().__exit__()

src/PIL/MpoImagePlugin.py

@@ -22,6 +22,7 @@ from __future__ import annotations
 import itertools
 import os
 import struct
+from typing import IO
 
 from . import (
     Image,
@@ -32,23 +33,18 @@ from . import (
 from ._binary import o32le
 
 
-def _save(im, fp, filename):
+def _save(im: Image.Image, fp: IO[bytes], filename: str | bytes) -> None:
     JpegImagePlugin._save(im, fp, filename)
 
 
-def _save_all(im, fp, filename):
+def _save_all(im: Image.Image, fp: IO[bytes], filename: str | bytes) -> None:
     append_images = im.encoderinfo.get("append_images", [])
-    if not append_images:
-        try:
-            animated = im.is_animated
-        except AttributeError:
-            animated = False
-        if not animated:
-            _save(im, fp, filename)
-            return
+    if not append_images and not getattr(im, "is_animated", False):
+        _save(im, fp, filename)
+        return
 
     mpf_offset = 28
-    offsets = []
+    offsets: list[int] = []
     for imSequence in itertools.chain([im], append_images):
         for im_frame in ImageSequence.Iterator(imSequence):
             if not offsets:

src/PIL/MspImagePlugin.py

@@ -164,7 +164,7 @@ Image.register_decoder("MSP", MspDecoder)
 # write MSP files (uncompressed only)
 
 
-def _save(im: Image.Image, fp: IO[bytes], filename: str) -> None:
+def _save(im: Image.Image, fp: IO[bytes], filename: str | bytes) -> None:
     if im.mode != "1":
         msg = f"cannot write mode {im.mode} as MSP"
         raise OSError(msg)

src/PIL/PSDraw.py

@@ -17,6 +17,7 @@
 from __future__ import annotations
 
 import sys
+from typing import TYPE_CHECKING
 
 from . import EpsImagePlugin
 
@@ -38,7 +39,7 @@ class PSDraw:
                 fp = sys.stdout
         self.fp = fp
 
-    def begin_document(self, id=None):
+    def begin_document(self, id: str | None = None) -> None:
         """Set up printing of a document. (Write PostScript DSC header.)"""
         # FIXME: incomplete
         self.fp.write(
@@ -52,7 +53,7 @@ class PSDraw:
         self.fp.write(EDROFF_PS)
         self.fp.write(VDI_PS)
         self.fp.write(b"%%EndProlog\n")
-        self.isofont = {}
+        self.isofont: dict[bytes, int] = {}
 
     def end_document(self) -> None:
         """Ends printing. (Write PostScript DSC footer.)"""
@@ -60,22 +61,24 @@ class PSDraw:
         if hasattr(self.fp, "flush"):
             self.fp.flush()
 
-    def setfont(self, font, size):
+    def setfont(self, font: str, size: int) -> None:
         """
         Selects which font to use.
 
         :param font: A PostScript font name
         :param size: Size in points.
         """
-        font = bytes(font, "UTF-8")
-        if font not in self.isofont:
+        font_bytes = bytes(font, "UTF-8")
+        if font_bytes not in self.isofont:
             # reencode font
-            self.fp.write(b"/PSDraw-%s ISOLatin1Encoding /%s E\n" % (font, font))
-            self.isofont[font] = 1
+            self.fp.write(
+                b"/PSDraw-%s ISOLatin1Encoding /%s E\n" % (font_bytes, font_bytes)
+            )
+            self.isofont[font_bytes] = 1
         # rough
-        self.fp.write(b"/F0 %d /PSDraw-%s F\n" % (size, font))
+        self.fp.write(b"/F0 %d /PSDraw-%s F\n" % (size, font_bytes))
 
-    def line(self, xy0, xy1):
+    def line(self, xy0: tuple[int, int], xy1: tuple[int, int]) -> None:
         """
         Draws a line between the two points. Coordinates are given in
         PostScript point coordinates (72 points per inch, (0, 0) is the lower
@@ -83,7 +86,7 @@ class PSDraw:
         """
         self.fp.write(b"%d %d %d %d Vl\n" % (*xy0, *xy1))
 
-    def rectangle(self, box):
+    def rectangle(self, box: tuple[int, int, int, int]) -> None:
         """
         Draws a rectangle.
 
@@ -92,18 +95,22 @@ class PSDraw:
         """
         self.fp.write(b"%d %d M 0 %d %d Vr\n" % box)
 
-    def text(self, xy, text):
+    def text(self, xy: tuple[int, int], text: str) -> None:
         """
         Draws text at the given position. You must use
         :py:meth:`~PIL.PSDraw.PSDraw.setfont` before calling this method.
         """
-        text = bytes(text, "UTF-8")
-        text = b"\\(".join(text.split(b"("))
-        text = b"\\)".join(text.split(b")"))
-        xy += (text,)
-        self.fp.write(b"%d %d M (%s) S\n" % xy)
+        text_bytes = bytes(text, "UTF-8")
+        text_bytes = b"\\(".join(text_bytes.split(b"("))
+        text_bytes = b"\\)".join(text_bytes.split(b")"))
+        self.fp.write(b"%d %d M (%s) S\n" % (xy + (text_bytes,)))
 
-    def image(self, box, im, dpi=None):
+    if TYPE_CHECKING:
+        from . import Image
+
+    def image(
+        self, box: tuple[int, int, int, int], im: Image.Image, dpi: int | None = None
+    ) -> None:
         """Draw a PIL image, centered in the given box."""
         # default resolution depends on mode
         if not dpi:
@@ -131,7 +138,7 @@ class PSDraw:
             sx = x / im.size[0]
             sy = y / im.size[1]
             self.fp.write(b"%f %f scale\n" % (sx, sy))
-        EpsImagePlugin._save(im, self.fp, None, 0)
+        EpsImagePlugin._save(im, self.fp, "", 0)
         self.fp.write(b"\ngrestore\n")
 
 

src/PIL/PaletteFile.py

@@ -14,6 +14,8 @@
 #
 from __future__ import annotations
 
+from typing import IO
+
 from ._binary import o8
 
 
@@ -22,8 +24,8 @@ class PaletteFile:
 
     rawmode = "RGB"
 
-    def __init__(self, fp):
-        self.palette = [(i, i, i) for i in range(256)]
+    def __init__(self, fp: IO[bytes]) -> None:
+        palette = [o8(i) * 3 for i in range(256)]
 
         while True:
             s = fp.readline()
@@ -44,9 +46,9 @@ class PaletteFile:
                 g = b = r
 
             if 0 <= i <= 255:
-                self.palette[i] = o8(r) + o8(g) + o8(b)
+                palette[i] = o8(r) + o8(g) + o8(b)
 
-        self.palette = b"".join(self.palette)
+        self.palette = b"".join(palette)
 
-    def getpalette(self):
+    def getpalette(self) -> tuple[bytes, str]:
         return self.palette, self.rawmode

src/PIL/PalmImagePlugin.py

@@ -8,6 +8,8 @@
 ##
 from __future__ import annotations
 
+from typing import IO
+
 from . import Image, ImageFile
 from ._binary import o8
 from ._binary import o16be as o16b
@@ -82,10 +84,10 @@ _Palm8BitColormapValues = (
 
 
 # so build a prototype image to be used for palette resampling
-def build_prototype_image():
+def build_prototype_image() -> Image.Image:
     image = Image.new("L", (1, len(_Palm8BitColormapValues)))
     image.putdata(list(range(len(_Palm8BitColormapValues))))
-    palettedata = ()
+    palettedata: tuple[int, ...] = ()
     for colormapValue in _Palm8BitColormapValues:
         palettedata += colormapValue
     palettedata += (0, 0, 0) * (256 - len(_Palm8BitColormapValues))
@@ -112,7 +114,7 @@ _COMPRESSION_TYPES = {"none": 0xFF, "rle": 0x01, "scanline": 0x00}
 # (Internal) Image save plugin for the Palm format.
 
 
-def _save(im, fp, filename):
+def _save(im: Image.Image, fp: IO[bytes], filename: str | bytes) -> None:
     if im.mode == "P":
         # we assume this is a color Palm image with the standard colormap,
         # unless the "info" dict has a "custom-colormap" field
@@ -141,7 +143,7 @@ def _save(im, fp, filename):
             raise OSError(msg)
 
         # we ignore the palette here
-        im.mode = "P"
+        im._mode = "P"
         rawmode = f"P;{bpp}"
         version = 1
 

src/PIL/PcxImagePlugin.py

@@ -144,7 +144,7 @@ SAVE = {
 }
 
 
-def _save(im: Image.Image, fp: IO[bytes], filename: str) -> None:
+def _save(im: Image.Image, fp: IO[bytes], filename: str | bytes) -> None:
     try:
         version, bits, planes, rawmode = SAVE[im.mode]
     except KeyError as e:

src/PIL/PdfImagePlugin.py

@@ -25,6 +25,7 @@ import io
 import math
 import os
 import time
+from typing import IO
 
 from . import Image, ImageFile, ImageSequence, PdfParser, __version__, features
 
@@ -39,7 +40,7 @@ from . import Image, ImageFile, ImageSequence, PdfParser, __version__, features
 #  5. page contents
 
 
-def _save_all(im, fp, filename):
+def _save_all(im: Image.Image, fp: IO[bytes], filename: str | bytes) -> None:
     _save(im, fp, filename, save_all=True)
 
 

src/PIL/PdfParser.py

@@ -13,7 +13,7 @@ from typing import TYPE_CHECKING, Any, List, NamedTuple, Union
 
 # see 7.9.2.2 Text String Type on page 86 and D.3 PDFDocEncoding Character Set
 # on page 656
-def encode_text(s):
+def encode_text(s: str) -> bytes:
     return codecs.BOM_UTF16_BE + s.encode("utf_16_be")
 
 
@@ -76,7 +76,7 @@ class PdfFormatError(RuntimeError):
     pass
 
 
-def check_format_condition(condition, error_message):
+def check_format_condition(condition: bool, error_message: str) -> None:
     if not condition:
         raise PdfFormatError(error_message)
 
@@ -93,17 +93,16 @@ class IndirectReference(IndirectReferenceTuple):
     def __bytes__(self) -> bytes:
         return self.__str__().encode("us-ascii")
 
-    def __eq__(self, other):
-        return (
-            other.__class__ is self.__class__
-            and other.object_id == self.object_id
-            and other.generation == self.generation
-        )
+    def __eq__(self, other: object) -> bool:
+        if self.__class__ is not other.__class__:
+            return False
+        assert isinstance(other, IndirectReference)
+        return other.object_id == self.object_id and other.generation == self.generation
 
     def __ne__(self, other):
         return not (self == other)
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         return hash((self.object_id, self.generation))
 
 
@@ -219,7 +218,7 @@ class PdfName:
             isinstance(other, PdfName) and other.name == self.name
         ) or other == self.name
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         return hash(self.name)
 
     def __repr__(self) -> str:
@@ -402,12 +401,11 @@ class PdfParser:
         if f:
             self.seek_end()
 
-    def __enter__(self):
+    def __enter__(self) -> PdfParser:
         return self
 
-    def __exit__(self, exc_type, exc_value, traceback):
+    def __exit__(self, *args: object) -> None:
         self.close()
-        return False  # do not suppress exceptions
 
     def start_writing(self) -> None:
         self.close_buf()
@@ -436,7 +434,7 @@ class PdfParser:
     def write_comment(self, s):
         self.f.write(f"% {s}\n".encode())
 
-    def write_catalog(self):
+    def write_catalog(self) -> IndirectReference:
         self.del_root()
         self.root_ref = self.next_object_id(self.f.tell())
         self.pages_ref = self.next_object_id(0)

src/PIL/PngImagePlugin.py

@@ -39,7 +39,7 @@ import struct
 import warnings
 import zlib
 from enum import IntEnum
-from typing import IO
+from typing import IO, Any
 
 from . import Image, ImageChops, ImageFile, ImagePalette, ImageSequence
 from ._binary import i16be as i16
@@ -178,7 +178,7 @@ class ChunkStream:
     def __enter__(self) -> ChunkStream:
         return self
 
-    def __exit__(self, *args):
+    def __exit__(self, *args: object) -> None:
         self.close()
 
     def close(self) -> None:
@@ -1019,7 +1019,7 @@ class PngImageFile(ImageFile.ImageFile):
                 if self.pyaccess:
                     self.pyaccess = None
 
-    def _getexif(self):
+    def _getexif(self) -> dict[str, Any] | None:
         if "exif" not in self.info:
             self.load()
         if "exif" not in self.info and "Raw profile type exif" not in self.info:
@@ -1032,7 +1032,7 @@ class PngImageFile(ImageFile.ImageFile):
 
         return super().getexif()
 
-    def getxmp(self):
+    def getxmp(self) -> dict[str, Any]:
         """
         Returns a dictionary containing the XMP tags.
         Requires defusedxml to be installed.
@@ -1234,7 +1234,7 @@ def _write_multiple_frames(im, fp, chunk, rawmode, default_image, append_images)
             seq_num = fdat_chunks.seq_num
 
 
-def _save_all(im, fp, filename):
+def _save_all(im: Image.Image, fp: IO[bytes], filename: str | bytes) -> None:
     _save(im, fp, filename, save_all=True)
 
 

src/PIL/PpmImagePlugin.py

@@ -328,7 +328,7 @@ class PpmDecoder(ImageFile.PyDecoder):
 # --------------------------------------------------------------------
 
 
-def _save(im: Image.Image, fp: IO[bytes], filename: str) -> None:
+def _save(im: Image.Image, fp: IO[bytes], filename: str | bytes) -> None:
     if im.mode == "1":
         rawmode, head = "1;I", b"P4"
     elif im.mode == "L":

src/PIL/QoiImagePlugin.py

@@ -37,17 +37,20 @@ class QoiImageFile(ImageFile.ImageFile):
 
 class QoiDecoder(ImageFile.PyDecoder):
     _pulls_fd = True
+    _previous_pixel: bytes | bytearray | None = None
+    _previously_seen_pixels: dict[int, bytes | bytearray] = {}
 
-    def _add_to_previous_pixels(self, value):
+    def _add_to_previous_pixels(self, value: bytes | bytearray) -> None:
         self._previous_pixel = value
 
         r, g, b, a = value
         hash_value = (r * 3 + g * 5 + b * 7 + a * 11) % 64
         self._previously_seen_pixels[hash_value] = value
 
-    def decode(self, buffer):
+    def decode(self, buffer: bytes) -> tuple[int, int]:
+        assert self.fd is not None
+
         self._previously_seen_pixels = {}
-        self._previous_pixel = None
         self._add_to_previous_pixels(bytearray((0, 0, 0, 255)))
 
         data = bytearray()
@@ -55,7 +58,8 @@ class QoiDecoder(ImageFile.PyDecoder):
         dest_length = self.state.xsize * self.state.ysize * bands
         while len(data) < dest_length:
             byte = self.fd.read(1)[0]
-            if byte == 0b11111110:  # QOI_OP_RGB
+            value: bytes | bytearray
+            if byte == 0b11111110 and self._previous_pixel:  # QOI_OP_RGB
                 value = bytearray(self.fd.read(3)) + self._previous_pixel[3:]
             elif byte == 0b11111111:  # QOI_OP_RGBA
                 value = self.fd.read(4)
@@ -66,7 +70,7 @@ class QoiDecoder(ImageFile.PyDecoder):
                     value = self._previously_seen_pixels.get(
                         op_index, bytearray((0, 0, 0, 0))
                     )
-                elif op == 1:  # QOI_OP_DIFF
+                elif op == 1 and self._previous_pixel:  # QOI_OP_DIFF
                     value = bytearray(
                         (
                             (self._previous_pixel[0] + ((byte & 0b00110000) >> 4) - 2)
@@ -77,7 +81,7 @@ class QoiDecoder(ImageFile.PyDecoder):
                             self._previous_pixel[3],
                         )
                     )
-                elif op == 2:  # QOI_OP_LUMA
+                elif op == 2 and self._previous_pixel:  # QOI_OP_LUMA
                     second_byte = self.fd.read(1)[0]
                     diff_green = (byte & 0b00111111) - 32
                     diff_red = ((second_byte & 0b11110000) >> 4) - 8
@@ -90,7 +94,7 @@ class QoiDecoder(ImageFile.PyDecoder):
                         )
                     )
                     value += self._previous_pixel[3:]
-                elif op == 3:  # QOI_OP_RUN
+                elif op == 3 and self._previous_pixel:  # QOI_OP_RUN
                     run_length = (byte & 0b00111111) + 1
                     value = self._previous_pixel
                     if bands == 3:

src/PIL/SgiImagePlugin.py

@@ -125,7 +125,7 @@ class SgiImageFile(ImageFile.ImageFile):
             ]
 
 
-def _save(im: Image.Image, fp: IO[bytes], filename: str) -> None:
+def _save(im: Image.Image, fp: IO[bytes], filename: str | bytes) -> None:
     if im.mode not in {"RGB", "RGBA", "L"}:
         msg = "Unsupported SGI image mode"
         raise ValueError(msg)
@@ -171,8 +171,9 @@ def _save(im: Image.Image, fp: IO[bytes], filename: str) -> None:
     # Maximum Byte value (255 = 8bits per pixel)
     pinmax = 255
     # Image name (79 characters max, truncated below in write)
-    filename = os.path.basename(filename)
-    img_name = os.path.splitext(filename)[0].encode("ascii", "ignore")
+    img_name = os.path.splitext(os.path.basename(filename))[0]
+    if isinstance(img_name, str):
+        img_name = img_name.encode("ascii", "ignore")
     # Standard representation of pixel in the file
     colormap = 0
     fp.write(struct.pack(">h", magic_number))

src/PIL/SpiderImagePlugin.py

@@ -37,7 +37,7 @@ from __future__ import annotations
 import os
 import struct
 import sys
-from typing import TYPE_CHECKING
+from typing import IO, TYPE_CHECKING
 
 from . import Image, ImageFile
 
@@ -233,7 +233,7 @@ def loadImageSeries(filelist=None):
 # For saving images in Spider format
 
 
-def makeSpiderHeader(im):
+def makeSpiderHeader(im: Image.Image) -> list[bytes]:
     nsam, nrow = im.size
     lenbyt = nsam * 4  # There are labrec records in the header
     labrec = int(1024 / lenbyt)
@@ -263,7 +263,7 @@ def makeSpiderHeader(im):
     return [struct.pack("f", v) for v in hdr]
 
 
-def _save(im, fp, filename):
+def _save(im: Image.Image, fp: IO[bytes], filename: str | bytes) -> None:
     if im.mode[0] != "F":
         im = im.convert("F")
 
@@ -279,9 +279,10 @@ def _save(im, fp, filename):
     ImageFile._save(im, fp, [("raw", (0, 0) + im.size, 0, (rawmode, 0, 1))])
 
 
-def _save_spider(im, fp, filename):
+def _save_spider(im: Image.Image, fp: IO[bytes], filename: str | bytes) -> None:
     # get the filename extension and register it with Image
-    ext = os.path.splitext(filename)[1]
+    filename_ext = os.path.splitext(filename)[1]
+    ext = filename_ext.decode() if isinstance(filename_ext, bytes) else filename_ext
     Image.register_extension(SpiderImageFile.format, ext)
     _save(im, fp, filename)
 

src/PIL/TarIO.py

@@ -16,7 +16,6 @@
 from __future__ import annotations
 
 import io
-from types import TracebackType
 
 from . import ContainerIO
 
@@ -61,12 +60,7 @@ class TarIO(ContainerIO.ContainerIO[bytes]):
     def __enter__(self) -> TarIO:
         return self
 
-    def __exit__(
-        self,
-        exc_type: type[BaseException] | None,
-        exc_val: BaseException | None,
-        exc_tb: TracebackType | None,
-    ) -> None:
+    def __exit__(self, *args: object) -> None:
         self.close()
 
     def close(self) -> None:

src/PIL/TgaImagePlugin.py

@@ -178,7 +178,7 @@ SAVE = {
 }
 
 
-def _save(im: Image.Image, fp: IO[bytes], filename: str) -> None:
+def _save(im: Image.Image, fp: IO[bytes], filename: str | bytes) -> None:
     try:
         rawmode, bits, colormaptype, imagetype = SAVE[im.mode]
     except KeyError as e:

src/PIL/TiffImagePlugin.py

@@ -50,7 +50,7 @@ import warnings
 from collections.abc import MutableMapping
 from fractions import Fraction
 from numbers import Number, Rational
-from typing import TYPE_CHECKING, Any, Callable
+from typing import IO, TYPE_CHECKING, Any, Callable
 
 from . import ExifTags, Image, ImageFile, ImageOps, ImagePalette, TiffTags
 from ._binary import i16be as i16
@@ -387,7 +387,7 @@ class IFDRational(Rational):
     def __hash__(self):
         return self._val.__hash__()
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
         val = self._val
         if isinstance(other, IFDRational):
             other = other._val
@@ -717,7 +717,7 @@ class ImageFileDirectory_v2(_IFDv2Base):
             # Unspec'd, and length > 1
             dest[tag] = values
 
-    def __delitem__(self, tag):
+    def __delitem__(self, tag: int) -> None:
         self._tags_v2.pop(tag, None)
         self._tags_v1.pop(tag, None)
         self._tagdata.pop(tag, None)
@@ -1106,7 +1106,7 @@ class TiffImageFile(ImageFile.ImageFile):
 
         super().__init__(fp, filename)
 
-    def _open(self):
+    def _open(self) -> None:
         """Open the first image in a TIFF file"""
 
         # Header
@@ -1123,8 +1123,8 @@ class TiffImageFile(ImageFile.ImageFile):
         self.__first = self.__next = self.tag_v2.next
         self.__frame = -1
         self._fp = self.fp
-        self._frame_pos = []
-        self._n_frames = None
+        self._frame_pos: list[int] = []
+        self._n_frames: int | None = None
 
         logger.debug("*** TiffImageFile._open ***")
         logger.debug("- __first: %s", self.__first)
@@ -1202,7 +1202,7 @@ class TiffImageFile(ImageFile.ImageFile):
         """Return the current frame number"""
         return self.__frame
 
-    def getxmp(self):
+    def getxmp(self) -> dict[str, Any]:
         """
         Returns a dictionary containing the XMP tags.
         Requires defusedxml to be installed.
@@ -1995,13 +1995,12 @@ class AppendingTiffWriter:
         self.finalize()
         self.setup()
 
-    def __enter__(self):
+    def __enter__(self) -> AppendingTiffWriter:
         return self
 
-    def __exit__(self, exc_type, exc_value, traceback):
+    def __exit__(self, *args: object) -> None:
         if self.close_fp:
             self.close()
-        return False
 
     def tell(self) -> int:
         return self.f.tell() - self.offsetOfNewPage
@@ -2023,7 +2022,7 @@ class AppendingTiffWriter:
             self.f.write(bytes(pad_bytes))
         self.offsetOfNewPage = self.f.tell()
 
-    def setEndian(self, endian):
+    def setEndian(self, endian: str) -> None:
         self.endian = endian
         self.longFmt = f"{self.endian}L"
         self.shortFmt = f"{self.endian}H"
@@ -2043,42 +2042,42 @@ class AppendingTiffWriter:
     def write(self, data):
         return self.f.write(data)
 
-    def readShort(self):
+    def readShort(self) -> int:
         (value,) = struct.unpack(self.shortFmt, self.f.read(2))
         return value
 
-    def readLong(self):
+    def readLong(self) -> int:
         (value,) = struct.unpack(self.longFmt, self.f.read(4))
         return value
 
-    def rewriteLastShortToLong(self, value):
+    def rewriteLastShortToLong(self, value: int) -> None:
         self.f.seek(-2, os.SEEK_CUR)
         bytes_written = self.f.write(struct.pack(self.longFmt, value))
         if bytes_written is not None and bytes_written != 4:
             msg = f"wrote only {bytes_written} bytes but wanted 4"
             raise RuntimeError(msg)
 
-    def rewriteLastShort(self, value):
+    def rewriteLastShort(self, value: int) -> None:
         self.f.seek(-2, os.SEEK_CUR)
         bytes_written = self.f.write(struct.pack(self.shortFmt, value))
         if bytes_written is not None and bytes_written != 2:
             msg = f"wrote only {bytes_written} bytes but wanted 2"
             raise RuntimeError(msg)
 
-    def rewriteLastLong(self, value):
+    def rewriteLastLong(self, value: int) -> None:
         self.f.seek(-4, os.SEEK_CUR)
         bytes_written = self.f.write(struct.pack(self.longFmt, value))
         if bytes_written is not None and bytes_written != 4:
             msg = f"wrote only {bytes_written} bytes but wanted 4"
             raise RuntimeError(msg)
 
-    def writeShort(self, value):
+    def writeShort(self, value: int) -> None:
         bytes_written = self.f.write(struct.pack(self.shortFmt, value))
         if bytes_written is not None and bytes_written != 2:
             msg = f"wrote only {bytes_written} bytes but wanted 2"
             raise RuntimeError(msg)
 
-    def writeLong(self, value):
+    def writeLong(self, value: int) -> None:
         bytes_written = self.f.write(struct.pack(self.longFmt, value))
         if bytes_written is not None and bytes_written != 4:
             msg = f"wrote only {bytes_written} bytes but wanted 4"
@@ -2097,9 +2096,9 @@ class AppendingTiffWriter:
             field_size = self.fieldSizes[field_type]
             total_size = field_size * count
             is_local = total_size <= 4
+            offset: int | None
             if not is_local:
-                offset = self.readLong()
-                offset += self.offsetOfNewPage
+                offset = self.readLong() + self.offsetOfNewPage
                 self.rewriteLastLong(offset)
 
             if tag in self.Tags:
@@ -2149,7 +2148,7 @@ class AppendingTiffWriter:
                 self.rewriteLastLong(offset)
 
 
-def _save_all(im, fp, filename):
+def _save_all(im: Image.Image, fp: IO[bytes], filename: str | bytes) -> None:
     encoderinfo = im.encoderinfo.copy()
     encoderconfig = im.encoderconfig
     append_images = list(encoderinfo.get("append_images", []))

src/PIL/WebPImagePlugin.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from io import BytesIO
+from typing import IO, Any
 
 from . import Image, ImageFile
 
@@ -95,12 +96,12 @@ class WebPImageFile(ImageFile.ImageFile):
         # Initialize seek state
         self._reset(reset=False)
 
-    def _getexif(self):
+    def _getexif(self) -> dict[str, Any] | None:
         if "exif" not in self.info:
             return None
         return self.getexif()._get_merged_dict()
 
-    def getxmp(self):
+    def getxmp(self) -> dict[str, Any]:
         """
         Returns a dictionary containing the XMP tags.
         Requires defusedxml to be installed.
@@ -116,7 +117,7 @@ class WebPImageFile(ImageFile.ImageFile):
         # Set logical frame to requested position
         self.__logical_frame = frame
 
-    def _reset(self, reset=True):
+    def _reset(self, reset: bool = True) -> None:
         if reset:
             self._decoder.reset()
         self.__physical_frame = 0
@@ -181,7 +182,7 @@ class WebPImageFile(ImageFile.ImageFile):
         return self.__logical_frame
 
 
-def _save_all(im, fp, filename):
+def _save_all(im: Image.Image, fp: IO[bytes], filename: str | bytes) -> None:
     encoderinfo = im.encoderinfo.copy()
     append_images = list(encoderinfo.get("append_images", []))
 
@@ -194,7 +195,7 @@ def _save_all(im, fp, filename):
         _save(im, fp, filename)
         return
 
-    background = (0, 0, 0, 0)
+    background: int | tuple[int, ...] = (0, 0, 0, 0)
     if "background" in encoderinfo:
         background = encoderinfo["background"]
     elif "background" in im.info:
@@ -324,7 +325,7 @@ def _save_all(im, fp, filename):
     fp.write(data)
 
 
-def _save(im, fp, filename):
+def _save(im: Image.Image, fp: IO[bytes], filename: str | bytes) -> None:
     lossless = im.encoderinfo.get("lossless", False)
     quality = im.encoderinfo.get("quality", 80)
     alpha_quality = im.encoderinfo.get("alpha_quality", 100)

src/PIL/WmfImagePlugin.py

@@ -20,6 +20,8 @@
 # http://wvware.sourceforge.net/caolan/ora-wmf.html
 from __future__ import annotations
 
+from typing import IO
+
 from . import Image, ImageFile
 from ._binary import i16le as word
 from ._binary import si16le as short
@@ -28,7 +30,7 @@ from ._binary import si32le as _long
 _handler = None
 
 
-def register_handler(handler):
+def register_handler(handler: ImageFile.StubHandler | None) -> None:
     """
     Install application-specific WMF image handler.
 
@@ -41,12 +43,12 @@ def register_handler(handler):
 if hasattr(Image.core, "drawwmf"):
     # install default handler (windows only)
 
-    class WmfHandler:
-        def open(self, im):
+    class WmfHandler(ImageFile.StubHandler):
+        def open(self, im: ImageFile.StubImageFile) -> None:
             im._mode = "RGB"
             self.bbox = im.info["wmf_bbox"]
 
-        def load(self, im):
+        def load(self, im: ImageFile.StubImageFile) -> Image.Image:
             im.fp.seek(0)  # rewind
             return Image.frombytes(
                 "RGB",
@@ -147,7 +149,7 @@ class WmfStubImageFile(ImageFile.StubImageFile):
         if loader:
             loader.open(self)
 
-    def _load(self):
+    def _load(self) -> ImageFile.StubHandler | None:
         return _handler
 
     def load(self, dpi=None):
@@ -161,7 +163,7 @@ class WmfStubImageFile(ImageFile.StubImageFile):
         return super().load()
 
 
-def _save(im, fp, filename):
+def _save(im: Image.Image, fp: IO[bytes], filename: str | bytes) -> None:
     if _handler is None or not hasattr(_handler, "save"):
         msg = "WMF save handler not installed"
         raise OSError(msg)

src/PIL/XbmImagePlugin.py

@@ -70,7 +70,7 @@ class XbmImageFile(ImageFile.ImageFile):
         self.tile = [("xbm", (0, 0) + self.size, m.end(), None)]
 
 
-def _save(im: Image.Image, fp: IO[bytes], filename: str) -> None:
+def _save(im: Image.Image, fp: IO[bytes], filename: str | bytes) -> None:
     if im.mode != "1":
         msg = f"cannot write mode {im.mode} as XBM"
         raise OSError(msg)

src/PIL/_imaging.pyi

@@ -1,3 +1,16 @@
 from typing import Any
 
+class ImagingCore:
+    def __getattr__(self, name: str) -> Any: ...
+
+class ImagingFont:
+    def __getattr__(self, name: str) -> Any: ...
+
+class ImagingDraw:
+    def __getattr__(self, name: str) -> Any: ...
+
+class PixelAccess:
+    def __getattr__(self, name: str) -> Any: ...
+
+def font(image, glyphdata: bytes) -> ImagingFont: ...
 def __getattr__(name: str) -> Any: ...

src/PIL/_imagingft.pyi

@@ -1,3 +1,69 @@
-from typing import Any
+from typing import Any, TypedDict
 
+from . import _imaging
+
+class _Axis(TypedDict):
+    minimum: int | None
+    default: int | None
+    maximum: int | None
+    name: bytes | None
+
+class Font:
+    @property
+    def family(self) -> str | None: ...
+    @property
+    def style(self) -> str | None: ...
+    @property
+    def ascent(self) -> int: ...
+    @property
+    def descent(self) -> int: ...
+    @property
+    def height(self) -> int: ...
+    @property
+    def x_ppem(self) -> int: ...
+    @property
+    def y_ppem(self) -> int: ...
+    @property
+    def glyphs(self) -> int: ...
+    def render(
+        self,
+        string: str,
+        fill,
+        mode=...,
+        dir=...,
+        features=...,
+        lang=...,
+        stroke_width=...,
+        anchor=...,
+        foreground_ink_long=...,
+        x_start=...,
+        y_start=...,
+        /,
+    ) -> tuple[_imaging.ImagingCore, tuple[int, int]]: ...
+    def getsize(
+        self,
+        string: str | bytes | bytearray,
+        mode=...,
+        dir=...,
+        features=...,
+        lang=...,
+        anchor=...,
+        /,
+    ) -> tuple[tuple[int, int], tuple[int, int]]: ...
+    def getlength(
+        self, string: str, mode=..., dir=..., features=..., lang=..., /
+    ) -> float: ...
+    def getvarnames(self) -> list[bytes]: ...
+    def getvaraxes(self) -> list[_Axis] | None: ...
+    def setvarname(self, instance_index: int, /) -> None: ...
+    def setvaraxes(self, axes: list[float], /) -> None: ...
+
+def getfont(
+    filename: str | bytes,
+    size: float,
+    index=...,
+    encoding=...,
+    font_bytes=...,
+    layout_engine=...,
+) -> Font: ...
 def __getattr__(name: str) -> Any: ...

src/_imaging.c

@@ -2028,7 +2028,7 @@ im_setmode(ImagingObject *self, PyObject *args) {
 }
 
 static PyObject *
-_transform2(ImagingObject *self, PyObject *args) {
+_transform(ImagingObject *self, PyObject *args) {
     static const char *wrong_number = "wrong number of matrix entries";
 
     Imaging imOut;
@@ -3647,7 +3647,7 @@ static struct PyMethodDef methods[] = {
     {"resize", (PyCFunction)_resize, METH_VARARGS},
     {"reduce", (PyCFunction)_reduce, METH_VARARGS},
     {"transpose", (PyCFunction)_transpose, METH_VARARGS},
-    {"transform2", (PyCFunction)_transform2, METH_VARARGS},
+    {"transform", (PyCFunction)_transform, METH_VARARGS},
 
     {"isblock", (PyCFunction)_isblock, METH_NOARGS},
 

winbuild/build_prepare.py

@@ -112,12 +112,12 @@ ARCHITECTURES = {
 V = {
     "BROTLI": "1.1.0",
     "FREETYPE": "2.13.2",
-    "FRIBIDI": "1.0.13",
-    "HARFBUZZ": "8.4.0",
-    "JPEGTURBO": "3.0.2",
+    "FRIBIDI": "1.0.15",
+    "HARFBUZZ": "8.5.0",
+    "JPEGTURBO": "3.0.3",
     "LCMS2": "2.16",
     "LIBPNG": "1.6.43",
-    "LIBWEBP": "1.3.2",
+    "LIBWEBP": "1.4.0",
     "OPENJPEG": "2.5.2",
     "TIFF": "4.6.0",
     "XZ": "5.4.5",