From 231d54b9df90dcce1cdbb9928f8d21899eed8153 Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Date: Mon, 22 Jan 2024 21:37:37 +0200
Subject: [PATCH 01/14] Replace io.BytesIO in type hints

---
 docs/reference/internal_design.rst  |  4 ++--
 docs/reference/internal_modules.rst | 12 ++++++++++++
 src/PIL/GdImageFile.py              |  7 +++++--
 src/PIL/MpegImagePlugin.py          |  5 ++---
 src/PIL/_typing.py                  | 16 +++++++++++++++-
 src/PIL/_util.py                    |  4 ++--
 6 files changed, 38 insertions(+), 10 deletions(-)

diff --git a/docs/reference/internal_design.rst b/docs/reference/internal_design.rst
index 2e2d3322f75..99a18e9ea99 100644
--- a/docs/reference/internal_design.rst
+++ b/docs/reference/internal_design.rst
@@ -1,5 +1,5 @@
-Internal Reference Docs
-=======================
+Internal Reference
+==================
 
 .. toctree::
   :maxdepth: 2
diff --git a/docs/reference/internal_modules.rst b/docs/reference/internal_modules.rst
index f2932c32200..c3cc700607f 100644
--- a/docs/reference/internal_modules.rst
+++ b/docs/reference/internal_modules.rst
@@ -33,6 +33,18 @@ Internal Modules
 Provides a convenient way to import type hints that are not available
 on some Python versions.
 
+.. py:class:: FileDescriptor
+
+    Typing alias.
+
+.. py:class:: StrOrBytesPath
+
+    Typing alias.
+
+.. py:class:: SupportsRead
+
+    An object that supports the read method.
+
 .. py:data:: TypeGuard
     :value: typing.TypeGuard
 
diff --git a/src/PIL/GdImageFile.py b/src/PIL/GdImageFile.py
index 7bb4736af13..315ac6d6c1a 100644
--- a/src/PIL/GdImageFile.py
+++ b/src/PIL/GdImageFile.py
@@ -27,11 +27,12 @@ class is not registered for use with :py:func:`PIL.Image.open()`.  To open a
 """
 from __future__ import annotations
 
-from io import BytesIO
+from typing import IO
 
 from . import ImageFile, ImagePalette, UnidentifiedImageError
 from ._binary import i16be as i16
 from ._binary import i32be as i32
+from ._typing import FileDescriptor, StrOrBytesPath
 
 
 class GdImageFile(ImageFile.ImageFile):
@@ -80,7 +81,9 @@ def _open(self) -> None:
         ]
 
 
-def open(fp: BytesIO, mode: str = "r") -> GdImageFile:
+def open(
+    fp: StrOrBytesPath | FileDescriptor | IO[bytes], mode: str = "r"
+) -> GdImageFile:
     """
     Load texture from a GD image file.
 
diff --git a/src/PIL/MpegImagePlugin.py b/src/PIL/MpegImagePlugin.py
index b9e9243e59f..1565612f869 100644
--- a/src/PIL/MpegImagePlugin.py
+++ b/src/PIL/MpegImagePlugin.py
@@ -14,17 +14,16 @@
 #
 from __future__ import annotations
 
-from io import BytesIO
-
 from . import Image, ImageFile
 from ._binary import i8
+from ._typing import SupportsRead
 
 #
 # Bitstream parser
 
 
 class BitStream:
-    def __init__(self, fp: BytesIO) -> None:
+    def __init__(self, fp: SupportsRead[bytes]) -> None:
         self.fp = fp
         self.bits = 0
         self.bitbuffer = 0
diff --git a/src/PIL/_typing.py b/src/PIL/_typing.py
index 608b2b41fa8..6eb25c1c171 100644
--- a/src/PIL/_typing.py
+++ b/src/PIL/_typing.py
@@ -1,6 +1,8 @@
 from __future__ import annotations
 
+import os
 import sys
+from typing import Protocol, TypeVar, Union
 
 if sys.version_info >= (3, 10):
     from typing import TypeGuard
@@ -15,4 +17,16 @@ def __class_getitem__(cls, item: Any) -> type[bool]:
                 return bool
 
 
-__all__ = ["TypeGuard"]
+_T_co = TypeVar("_T_co", covariant=True)
+
+
+class SupportsRead(Protocol[_T_co]):
+    def read(self, __length: int = ...) -> _T_co:
+        ...
+
+
+FileDescriptor = int
+StrOrBytesPath = Union[str, bytes, "os.PathLike[str]", "os.PathLike[bytes]"]
+
+
+__all__ = ["FileDescriptor", "TypeGuard", "StrOrBytesPath", "SupportsRead"]
diff --git a/src/PIL/_util.py b/src/PIL/_util.py
index 13f369cca1d..4ecdc4bd307 100644
--- a/src/PIL/_util.py
+++ b/src/PIL/_util.py
@@ -4,10 +4,10 @@
 from pathlib import Path
 from typing import Any, NoReturn
 
-from ._typing import TypeGuard
+from ._typing import StrOrBytesPath, TypeGuard
 
 
-def is_path(f: Any) -> TypeGuard[bytes | str | Path]:
+def is_path(f: Any) -> TypeGuard[StrOrBytesPath]:
     return isinstance(f, (bytes, str, Path))
 
 

From e3932b7dbaf6aff8ef4b7a24007f4de07477ec91 Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Date: Tue, 23 Jan 2024 23:58:41 +0200
Subject: [PATCH 02/14] Exclude from coverage: empty bodies in protocols or
 abstract methods

---
 .coveragerc | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/.coveragerc b/.coveragerc
index 46df3f90d27..5678e45661a 100644
--- a/.coveragerc
+++ b/.coveragerc
@@ -10,6 +10,9 @@ exclude_also =
     if DEBUG:
     # Don't complain about compatibility code for missing optional dependencies
     except ImportError
+    # Empty bodies in protocols or abstract methods
+    ^\s*def [a-zA-Z0-9_]+\(.*\)(\s*->.*)?:\s*\.\.\.(\s*#.*)?$
+    ^\s*\.\.\.(\s*#.*)?$
 
 [run]
 omit =

From 945253672a74415807b5f685f54ebb1533ff468e Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Date: Fri, 26 Jan 2024 19:11:18 +0200
Subject: [PATCH 03/14] Handle os.PathLike in is_path

---
 src/PIL/ImageFont.py | 2 +-
 src/PIL/_util.py     | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/PIL/ImageFont.py b/src/PIL/ImageFont.py
index a63b73b33f5..9eecad1ca3a 100644
--- a/src/PIL/ImageFont.py
+++ b/src/PIL/ImageFont.py
@@ -230,7 +230,7 @@ def load_from_bytes(f):
             )
 
         if is_path(font):
-            if isinstance(font, Path):
+            if isinstance(font, os.PathLike):
                 font = str(font)
             if sys.platform == "win32":
                 font_bytes_path = font if isinstance(font, bytes) else font.encode()
diff --git a/src/PIL/_util.py b/src/PIL/_util.py
index 4ecdc4bd307..b649500abb5 100644
--- a/src/PIL/_util.py
+++ b/src/PIL/_util.py
@@ -8,7 +8,7 @@
 
 
 def is_path(f: Any) -> TypeGuard[StrOrBytesPath]:
-    return isinstance(f, (bytes, str, Path))
+    return isinstance(f, (bytes, str, os.PathLike))
 
 
 def is_directory(f: Any) -> TypeGuard[bytes | str | Path]:

From f613a9213f4edc7b58ac84a4793223c8e4fd9191 Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Date: Fri, 26 Jan 2024 19:15:19 +0200
Subject: [PATCH 04/14] Parameterise test

---
 Tests/test_util.py | 21 ++++-----------------
 1 file changed, 4 insertions(+), 17 deletions(-)

diff --git a/Tests/test_util.py b/Tests/test_util.py
index 3395ef753d7..71a862569b7 100644
--- a/Tests/test_util.py
+++ b/Tests/test_util.py
@@ -1,27 +1,14 @@
 from __future__ import annotations
 
+from pathlib import Path
+
 import pytest
 
 from PIL import _util
 
 
-def test_is_path():
-    # Arrange
-    fp = "filename.ext"
-
-    # Act
-    it_is = _util.is_path(fp)
-
-    # Assert
-    assert it_is
-
-
-def test_path_obj_is_path():
-    # Arrange
-    from pathlib import Path
-
-    test_path = Path("filename.ext")
-
+@pytest.mark.parametrize("test_path", ["filename.ext", Path("filename.ext")])
+def test_is_path(test_path):
     # Act
     it_is = _util.is_path(test_path)
 

From 16d4068b42f0a6069e14b2327302df713dabbfed Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Date: Fri, 26 Jan 2024 19:17:13 +0200
Subject: [PATCH 05/14] Test os.PathLike that's not pathlib.Path

---
 Tests/test_util.py | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/Tests/test_util.py b/Tests/test_util.py
index 71a862569b7..617e5f7c6da 100644
--- a/Tests/test_util.py
+++ b/Tests/test_util.py
@@ -1,13 +1,15 @@
 from __future__ import annotations
 
-from pathlib import Path
+from pathlib import Path, PurePath
 
 import pytest
 
 from PIL import _util
 
 
-@pytest.mark.parametrize("test_path", ["filename.ext", Path("filename.ext")])
+@pytest.mark.parametrize(
+    "test_path", ["filename.ext", Path("filename.ext"), PurePath("filename.ext")]
+)
 def test_is_path(test_path):
     # Act
     it_is = _util.is_path(test_path)

From d631afc266c3c1214e12373d3ad0d16978867a7f Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Date: Fri, 26 Jan 2024 20:46:58 +0200
Subject: [PATCH 06/14] Use os.fspath instead of isinstance and str

---
 src/PIL/ImageFont.py | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/src/PIL/ImageFont.py b/src/PIL/ImageFont.py
index 9eecad1ca3a..1feaf447a17 100644
--- a/src/PIL/ImageFont.py
+++ b/src/PIL/ImageFont.py
@@ -230,8 +230,7 @@ def load_from_bytes(f):
             )
 
         if is_path(font):
-            if isinstance(font, os.PathLike):
-                font = str(font)
+            font = os.fspath(font)
             if sys.platform == "win32":
                 font_bytes_path = font if isinstance(font, bytes) else font.encode()
                 try:

From 61d47c3dfa200b186ecacd7b9a5090cedb5523b6 Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Date: Sat, 27 Jan 2024 14:06:06 +0200
Subject: [PATCH 07/14] More support for arbitrary os.PathLike

---
 Tests/test_image.py           |  3 +--
 docs/reference/open_files.rst |  2 +-
 src/PIL/Image.py              | 16 ++++++----------
 3 files changed, 8 insertions(+), 13 deletions(-)

diff --git a/Tests/test_image.py b/Tests/test_image.py
index dd989ad99b5..84189df5477 100644
--- a/Tests/test_image.py
+++ b/Tests/test_image.py
@@ -7,6 +7,7 @@
 import sys
 import tempfile
 import warnings
+from pathlib import Path
 
 import pytest
 
@@ -161,8 +162,6 @@ def test_stringio(self):
                 pass
 
     def test_pathlib(self, tmp_path):
-        from PIL.Image import Path
-
         with Image.open(Path("Tests/images/multipage-mmap.tiff")) as im:
             assert im.mode == "P"
             assert im.size == (10, 10)
diff --git a/docs/reference/open_files.rst b/docs/reference/open_files.rst
index f31941c9abb..730c8da5b80 100644
--- a/docs/reference/open_files.rst
+++ b/docs/reference/open_files.rst
@@ -3,7 +3,7 @@
 File Handling in Pillow
 =======================
 
-When opening a file as an image, Pillow requires a filename, ``pathlib.Path``
+When opening a file as an image, Pillow requires a filename, ``os.PathLike``
 object, or a file-like object. Pillow uses the filename or ``Path`` to open a
 file, so for the rest of this article, they will all be treated as a file-like
 object.
diff --git a/src/PIL/Image.py b/src/PIL/Image.py
index 553f36703b3..48125b3173b 100644
--- a/src/PIL/Image.py
+++ b/src/PIL/Image.py
@@ -39,7 +39,6 @@
 import warnings
 from collections.abc import Callable, MutableMapping
 from enum import IntEnum
-from pathlib import Path
 
 try:
     from defusedxml import ElementTree
@@ -2370,7 +2369,7 @@ def save(self, fp, format=None, **params) -> None:
         implement the ``seek``, ``tell``, and ``write``
         methods, and be opened in binary mode.
 
-        :param fp: A filename (string), pathlib.Path object or file object.
+        :param fp: A filename (string), os.PathLike object or file object.
         :param format: Optional format override.  If omitted, the
            format to use is determined from the filename extension.
            If a file object was used instead of a filename, this
@@ -2385,11 +2384,8 @@ def save(self, fp, format=None, **params) -> None:
 
         filename = ""
         open_fp = False
-        if isinstance(fp, Path):
-            filename = str(fp)
-            open_fp = True
-        elif is_path(fp):
-            filename = fp
+        if is_path(fp):
+            filename = os.fspath(fp)
             open_fp = True
         elif fp == sys.stdout:
             try:
@@ -3206,7 +3202,7 @@ def open(fp, mode="r", formats=None) -> Image:
     :py:meth:`~PIL.Image.Image.load` method).  See
     :py:func:`~PIL.Image.new`. See :ref:`file-handling`.
 
-    :param fp: A filename (string), pathlib.Path object or a file object.
+    :param fp: A filename (string), os.PathLike object or a file object.
        The file object must implement ``file.read``,
        ``file.seek``, and ``file.tell`` methods,
        and be opened in binary mode. The file object will also seek to zero
@@ -3244,8 +3240,8 @@ def open(fp, mode="r", formats=None) -> Image:
 
     exclusive_fp = False
     filename = ""
-    if isinstance(fp, Path):
-        filename = str(fp.resolve())
+    if isinstance(fp, os.PathLike):
+        filename = os.path.realpath(os.fspath(fp))
     elif is_path(fp):
         filename = fp
 

From f2228e0a7c19d74c83b99f92edc113ba0cac7625 Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Date: Wed, 31 Jan 2024 12:37:53 -0700
Subject: [PATCH 08/14] Replace bytes | str | Path with StrOrBytesPath
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Ondrej Baranovič <nulano@nulano.eu>
---
 src/PIL/_util.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/PIL/_util.py b/src/PIL/_util.py
index b649500abb5..f7a69fae15d 100644
--- a/src/PIL/_util.py
+++ b/src/PIL/_util.py
@@ -11,7 +11,7 @@ def is_path(f: Any) -> TypeGuard[StrOrBytesPath]:
     return isinstance(f, (bytes, str, os.PathLike))
 
 
-def is_directory(f: Any) -> TypeGuard[bytes | str | Path]:
+def is_directory(f: Any) -> TypeGuard[StrOrBytesPath]:
     """Checks if an object is a string, and that it points to a directory."""
     return is_path(f) and os.path.isdir(f)
 

From 256f3f1966d6b56f178d0a9bb2bc4b0b334c77b1 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Wed, 31 Jan 2024 19:38:49 +0000
Subject: [PATCH 09/14] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 src/PIL/_util.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/PIL/_util.py b/src/PIL/_util.py
index f7a69fae15d..6bc76281616 100644
--- a/src/PIL/_util.py
+++ b/src/PIL/_util.py
@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import os
-from pathlib import Path
 from typing import Any, NoReturn
 
 from ._typing import StrOrBytesPath, TypeGuard

From a276cf2c9fadf39cc5e663e44bc160c566d7c050 Mon Sep 17 00:00:00 2001
From: Andrew Murray <radarhere@users.noreply.github.com>
Date: Thu, 8 Feb 2024 18:48:38 +1100
Subject: [PATCH 10/14] Use _typing alias

---
 src/PIL/ImageFont.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/PIL/ImageFont.py b/src/PIL/ImageFont.py
index 9f8394d63b4..7be2fdf0445 100644
--- a/src/PIL/ImageFont.py
+++ b/src/PIL/ImageFont.py
@@ -33,10 +33,10 @@
 import warnings
 from enum import IntEnum
 from io import BytesIO
-from pathlib import Path
 from typing import BinaryIO
 
 from . import Image
+from ._typing import StrOrBytesPath
 from ._util import is_directory, is_path
 
 
@@ -193,7 +193,7 @@ class FreeTypeFont:
 
     def __init__(
         self,
-        font: bytes | str | Path | BinaryIO | None = None,
+        font: StrOrBytesPath | BinaryIO | None = None,
         size: float = 10,
         index: int = 0,
         encoding: str = "",

From a118a82c30acf6427653b129fab263fde3bdbbac Mon Sep 17 00:00:00 2001
From: Andrew Murray <radarhere@users.noreply.github.com>
Date: Thu, 8 Feb 2024 18:35:37 +1100
Subject: [PATCH 11/14] Use os.path.realpath consistently when os.fspath is
 used

---
 src/PIL/Image.py     | 2 +-
 src/PIL/ImageFont.py | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/PIL/Image.py b/src/PIL/Image.py
index d7d0a1ae7f0..adb63b07f79 100644
--- a/src/PIL/Image.py
+++ b/src/PIL/Image.py
@@ -2385,7 +2385,7 @@ def save(self, fp, format=None, **params) -> None:
         filename = ""
         open_fp = False
         if is_path(fp):
-            filename = os.fspath(fp)
+            filename = os.path.realpath(os.fspath(fp))
             open_fp = True
         elif fp == sys.stdout:
             try:
diff --git a/src/PIL/ImageFont.py b/src/PIL/ImageFont.py
index 7be2fdf0445..256c581df0c 100644
--- a/src/PIL/ImageFont.py
+++ b/src/PIL/ImageFont.py
@@ -230,7 +230,7 @@ def load_from_bytes(f):
             )
 
         if is_path(font):
-            font = os.fspath(font)
+            font = os.path.realpath(os.fspath(font))
             if sys.platform == "win32":
                 font_bytes_path = font if isinstance(font, bytes) else font.encode()
                 try:

From 152a24e13abfe099d4cf75dc7982290feb200ad2 Mon Sep 17 00:00:00 2001
From: Andrew Murray <radarhere@users.noreply.github.com>
Date: Sat, 10 Feb 2024 16:48:02 +1100
Subject: [PATCH 12/14] Simplified code

---
 src/PIL/Image.py | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/src/PIL/Image.py b/src/PIL/Image.py
index adb63b07f79..231674f5448 100644
--- a/src/PIL/Image.py
+++ b/src/PIL/Image.py
@@ -3240,10 +3240,8 @@ def open(fp, mode="r", formats=None) -> Image:
 
     exclusive_fp = False
     filename = ""
-    if isinstance(fp, os.PathLike):
+    if is_path(fp):
         filename = os.path.realpath(os.fspath(fp))
-    elif is_path(fp):
-        filename = fp
 
     if filename:
         fp = builtins.open(filename, "rb")

From 517b797132a65a8a873d0c22008d760d2a706ff6 Mon Sep 17 00:00:00 2001
From: Andrew Murray <radarhere@users.noreply.github.com>
Date: Sat, 10 Feb 2024 20:47:32 +1100
Subject: [PATCH 13/14] Removed FileDescriptor

---
 src/PIL/GdImageFile.py | 6 ++----
 src/PIL/_typing.py     | 3 +--
 2 files changed, 3 insertions(+), 6 deletions(-)

diff --git a/src/PIL/GdImageFile.py b/src/PIL/GdImageFile.py
index 315ac6d6c1a..88b87a22cd6 100644
--- a/src/PIL/GdImageFile.py
+++ b/src/PIL/GdImageFile.py
@@ -32,7 +32,7 @@ class is not registered for use with :py:func:`PIL.Image.open()`.  To open a
 from . import ImageFile, ImagePalette, UnidentifiedImageError
 from ._binary import i16be as i16
 from ._binary import i32be as i32
-from ._typing import FileDescriptor, StrOrBytesPath
+from ._typing import StrOrBytesPath
 
 
 class GdImageFile(ImageFile.ImageFile):
@@ -81,9 +81,7 @@ def _open(self) -> None:
         ]
 
 
-def open(
-    fp: StrOrBytesPath | FileDescriptor | IO[bytes], mode: str = "r"
-) -> GdImageFile:
+def open(fp: StrOrBytesPath | IO[bytes], mode: str = "r") -> GdImageFile:
     """
     Load texture from a GD image file.
 
diff --git a/src/PIL/_typing.py b/src/PIL/_typing.py
index 346702037d2..7075e86726a 100644
--- a/src/PIL/_typing.py
+++ b/src/PIL/_typing.py
@@ -27,8 +27,7 @@ class SupportsRead(Protocol[_T_co]):
     def read(self, __length: int = ...) -> _T_co: ...
 
 
-FileDescriptor = int
 StrOrBytesPath = Union[str, bytes, "os.PathLike[str]", "os.PathLike[bytes]"]
 
 
-__all__ = ["FileDescriptor", "TypeGuard", "StrOrBytesPath", "SupportsRead"]
+__all__ = ["TypeGuard", "StrOrBytesPath", "SupportsRead"]

From 3977124908b934a9b037d1e8ba5549393bed9dda Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Date: Sat, 10 Feb 2024 14:54:20 +0200
Subject: [PATCH 14/14] Update docs/reference/internal_modules.rst

Co-authored-by: Andrew Murray <3112309+radarhere@users.noreply.github.com>
---
 docs/reference/internal_modules.rst | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/docs/reference/internal_modules.rst b/docs/reference/internal_modules.rst
index c3cc700607f..899e4966ff2 100644
--- a/docs/reference/internal_modules.rst
+++ b/docs/reference/internal_modules.rst
@@ -33,10 +33,6 @@ Internal Modules
 Provides a convenient way to import type hints that are not available
 on some Python versions.
 
-.. py:class:: FileDescriptor
-
-    Typing alias.
-
 .. py:class:: StrOrBytesPath
 
     Typing alias.