Merge pull request #7642 from nulano/types-util

Add type hints to _util

Tests/test_util.py

@@ -66,7 +66,7 @@ def test_deferred_error():
     # Arrange
 
     # Act
-    thing = _util.DeferredError(ValueError("Some error text"))
+    thing = _util.DeferredError.new(ValueError("Some error text"))
 
     # Assert
     with pytest.raises(ValueError):

docs/reference/internal_modules.rst

@@ -25,6 +25,19 @@ Internal Modules
     :undoc-members:
     :show-inheritance:
 
+:mod:`~PIL._typing` Module
+--------------------------
+
+.. module:: PIL._typing
+
+Provides a convenient way to import type hints that are not available
+on some Python versions.
+
+.. py:data:: TypeGuard
+    :value: typing.TypeGuard
+
+    See :py:obj:`typing.TypeGuard`.
+
 :mod:`~PIL._util` Module
 ------------------------
 

pyproject.toml

@@ -65,6 +65,9 @@ tests = [
   "pytest-cov",
   "pytest-timeout",
 ]
+typing = [
+  'typing-extensions; python_version < "3.10"',
+]
 xmp = [
   "defusedxml",
 ]
@@ -143,9 +146,6 @@ exclude = [
   '^src/PIL/DdsImagePlugin.py$',
   '^src/PIL/FpxImagePlugin.py$',
   '^src/PIL/Image.py$',
-  '^src/PIL/ImageCms.py$',
-  '^src/PIL/ImageFile.py$',
-  '^src/PIL/ImageFont.py$',
   '^src/PIL/ImageMath.py$',
   '^src/PIL/ImageMorph.py$',
   '^src/PIL/ImageQt.py$',

src/PIL/Image.py

@@ -92,7 +92,7 @@ try:
         raise ImportError(msg)
 
 except ImportError as v:
-    core = DeferredError(ImportError("The _imaging C module is not installed."))
+    core = DeferredError.new(ImportError("The _imaging C module is not installed."))
     # Explanations for ways that we know we might have an import error
     if str(v).startswith("Module use of python"):
         # The _imaging C module is present, but not compiled for

src/PIL/ImageCms.py

@@ -28,7 +28,7 @@ except ImportError as ex:
     # anything in core.
     from ._util import DeferredError
 
-    _imagingcms = DeferredError(ex)
+    _imagingcms = DeferredError.new(ex)
 
 DESCRIPTION = """
 pyCMS

src/PIL/ImageFile.py

@@ -32,7 +32,7 @@ import io
 import itertools
 import struct
 import sys
-from typing import NamedTuple
+from typing import Any, NamedTuple
 
 from . import Image
 from ._deprecate import deprecate
@@ -94,7 +94,7 @@ class _Tile(NamedTuple):
     encoder_name: str
     extents: tuple[int, int, int, int]
     offset: int
-    args: tuple | str | None
+    args: tuple[Any, ...] | str | None
 
 
 #

src/PIL/ImageFont.py

@@ -34,7 +34,7 @@ import warnings
 from enum import IntEnum
 from io import BytesIO
 from pathlib import Path
-from typing import IO
+from typing import BinaryIO
 
 from . import Image
 from ._util import is_directory, is_path
@@ -53,7 +53,7 @@ try:
 except ImportError as ex:
     from ._util import DeferredError
 
-    core = DeferredError(ex)
+    core = DeferredError.new(ex)
 
 
 def _string_length_check(text):
@@ -193,7 +193,7 @@ class FreeTypeFont:
 
     def __init__(
         self,
-        font: bytes | str | Path | IO | None = None,
+        font: bytes | str | Path | BinaryIO | None = None,
         size: float = 10,
         index: int = 0,
         encoding: str = "",

src/PIL/PyAccess.py

@@ -43,7 +43,7 @@ except ImportError as ex:
     # anything in core.
     from ._util import DeferredError
 
-    FFI = ffi = DeferredError(ex)
+    FFI = ffi = DeferredError.new(ex)
 
 logger = logging.getLogger(__name__)
 

src/PIL/_imagingcms.pyi

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from typing import Any
+
+def __getattr__(name: str) -> Any: ...

src/PIL/_imagingft.pyi

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from typing import Any
+
+def __getattr__(name: str) -> Any: ...

src/PIL/_typing.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import sys
+
+if sys.version_info >= (3, 10):
+    from typing import TypeGuard
+else:
+    try:
+        from typing_extensions import TypeGuard
+    except ImportError:
+        from typing import Any
+
+        class TypeGuard:  # type: ignore[no-redef]
+            def __class_getitem__(cls, item: Any) -> type[bool]:
+                return bool
+
+
+__all__ = ["TypeGuard"]

src/PIL/_util.py

@@ -2,20 +2,31 @@ from __future__ import annotations
 
 import os
 from pathlib import Path
+from typing import Any, NoReturn
+
+from ._typing import TypeGuard
 
 
-def is_path(f):
+def is_path(f: Any) -> TypeGuard[bytes | str | Path]:
     return isinstance(f, (bytes, str, Path))
 
 
-def is_directory(f):
+def is_directory(f: Any) -> TypeGuard[bytes | str | Path]:
     """Checks if an object is a string, and that it points to a directory."""
     return is_path(f) and os.path.isdir(f)
 
 
 class DeferredError:
-    def __init__(self, ex):
+    def __init__(self, ex: BaseException):
         self.ex = ex
 
-    def __getattr__(self, elt):
+    def __getattr__(self, elt: str) -> NoReturn:
         raise self.ex
+
+    @staticmethod
+    def new(ex: BaseException) -> Any:
+        """
+        Creates an object that raises the wrapped exception ``ex`` when used,
+        and casts it to :py:obj:`~typing.Any` type.
+        """
+        return DeferredError(ex)

tox.ini

@@ -35,5 +35,7 @@ skip_install = true
 deps =
     mypy==1.7.1
     numpy
+extras =
+    typing
 commands =
     mypy src {posargs}