Type annotate the public API

.github/workflows/ci.yml

@@ -25,7 +25,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11"]
+        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11", "3.12"]
         os: [Ubuntu, macOS, Windows]
 
     steps:

.pre-commit-config.yaml

@@ -9,6 +9,12 @@ repos:
     hooks:
       - id: black
 
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.1.1
+    hooks:
+      - id: mypy
+        exclude: tests/samples
+
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.4.0
     hooks:

.readthedocs.yml

@@ -4,6 +4,7 @@ sphinx:
   configuration: docs/conf.py
 
 python:
+  version: 3.8
   install:
     - requirements: docs/requirements.txt
     - method: pip

docs/changelog.rst

@@ -1,6 +1,11 @@
 Changelog
 =========
 
+v1.1
+----
+
+- Add type annotations to the public API.
+
 v1.0
 ----
 

noxfile.py

@@ -6,7 +6,7 @@
 nox.options.reuse_existing_virtualenvs = True
 
 
-@nox.session(python=["3.7", "3.8", "3.9", "3.10", "3.11", "pypy3"])
+@nox.session(python=["3.7", "3.8", "3.9", "3.10", "3.11", "3.12", "pypy3"])
 def test(session: nox.Session) -> None:
     session.install("-r", "dev-requirements.txt")
     session.install(".")

pyproject.toml

@@ -22,5 +22,8 @@ Source = "https://github.com/pypa/pyproject-hooks"
 Documentation = "https://pyproject-hooks.readthedocs.io/"
 Changelog = "https://pyproject-hooks.readthedocs.io/en/latest/changelog.html"
 
-[tool.isort]
-profile = "black"
+[tool.ruff]
+src = ["src", "tests"]
+
+[tool.ruff.isort]
+known-first-party = ["pyproject_hooks", "tests"]

src/pyproject_hooks/_impl.py

@@ -6,31 +6,51 @@
 from os.path import abspath
 from os.path import join as pjoin
 from subprocess import STDOUT, check_call, check_output
+from typing import TYPE_CHECKING, Any, Iterator, Mapping, Optional, Sequence
 
 from ._in_process import _in_proc_script_path
 
+if TYPE_CHECKING:
+    from typing import Protocol
 
-def write_json(obj, path, **kwargs):
+    class SubprocessRunner(Protocol):
+        """A protocol for the subprocess runner."""
+
+        def __call__(
+            self,
+            cmd: Sequence[str],
+            cwd: Optional[str] = None,
+            extra_environ: Optional[Mapping[str, str]] = None,
+        ) -> None:
+            ...
+
+
+def write_json(obj: Mapping[str, Any], path: str, **kwargs) -> None:
     with open(path, "w", encoding="utf-8") as f:
         json.dump(obj, f, **kwargs)
 
 
-def read_json(path):
+def read_json(path: str) -> Mapping[str, Any]:
     with open(path, encoding="utf-8") as f:
         return json.load(f)
 
 
 class BackendUnavailable(Exception):
     """Will be raised if the backend cannot be imported in the hook process."""
 
-    def __init__(self, traceback):
+    def __init__(self, traceback: str) -> None:
         self.traceback = traceback
 
 
 class BackendInvalid(Exception):
     """Will be raised if the backend is invalid."""
 
-    def __init__(self, backend_name, backend_path, message):
+    def __init__(
+        self,
+        backend_name: str,
+        backend_path: Optional[Sequence[str]],
+        message: str,
+    ) -> None:
         super().__init__(message)
         self.backend_name = backend_name
         self.backend_path = backend_path
@@ -39,19 +59,23 @@ def __init__(self, backend_name, backend_path, message):
 class HookMissing(Exception):
     """Will be raised on missing hooks (if a fallback can't be used)."""
 
-    def __init__(self, hook_name):
+    def __init__(self, hook_name: str) -> None:
         super().__init__(hook_name)
         self.hook_name = hook_name
 
 
 class UnsupportedOperation(Exception):
     """May be raised by build_sdist if the backend indicates that it can't."""
 
-    def __init__(self, traceback):
+    def __init__(self, traceback: str) -> None:
         self.traceback = traceback
 
 
-def default_subprocess_runner(cmd, cwd=None, extra_environ=None):
+def default_subprocess_runner(
+    cmd: Sequence[str],
+    cwd: Optional[str] = None,
+    extra_environ: Optional[Mapping[str, str]] = None,
+) -> None:
     """The default method of calling the wrapper subprocess.
 
     This uses :func:`subprocess.check_call` under the hood.
@@ -63,7 +87,11 @@ def default_subprocess_runner(cmd, cwd=None, extra_environ=None):
     check_call(cmd, cwd=cwd, env=env)
 
 
-def quiet_subprocess_runner(cmd, cwd=None, extra_environ=None):
+def quiet_subprocess_runner(
+    cmd: Sequence[str],
+    cwd: Optional[str] = None,
+    extra_environ: Optional[Mapping[str, str]] = None,
+) -> None:
     """Call the subprocess while suppressing output.
 
     This uses :func:`subprocess.check_output` under the hood.
@@ -75,7 +103,7 @@ def quiet_subprocess_runner(cmd, cwd=None, extra_environ=None):
     check_output(cmd, cwd=cwd, env=env, stderr=STDOUT)
 
 
-def norm_and_check(source_tree, requested):
+def norm_and_check(source_tree: str, requested: str) -> str:
     """Normalise and check a backend path.
 
     Ensure that the requested backend path is specified as a relative path,
@@ -104,12 +132,12 @@ class BuildBackendHookCaller:
 
     def __init__(
         self,
-        source_dir,
-        build_backend,
-        backend_path=None,
-        runner=None,
-        python_executable=None,
-    ):
+        source_dir: str,
+        build_backend: str,
+        backend_path: Optional[Sequence[str]] = None,
+        runner: Optional["SubprocessRunner"] = None,
+        python_executable: Optional[str] = None,
+    ) -> None:
         """
         :param source_dir: The source directory to invoke the build backend for
         :param build_backend: The build backend spec
@@ -132,7 +160,7 @@ def __init__(
         self.python_executable = python_executable
 
     @contextmanager
-    def subprocess_runner(self, runner):
+    def subprocess_runner(self, runner: "SubprocessRunner") -> Iterator[None]:
         """A context manager for temporarily overriding the default
         :ref:`subprocess runner <Subprocess Runners>`.
 
@@ -149,15 +177,17 @@ def subprocess_runner(self, runner):
         finally:
             self._subprocess_runner = prev
 
-    def _supported_features(self):
+    def _supported_features(self) -> Sequence[str]:
         """Return the list of optional features supported by the backend."""
         return self._call_hook("_supported_features", {})
 
-    def get_requires_for_build_wheel(self, config_settings=None):
+    def get_requires_for_build_wheel(
+        self,
+        config_settings: Optional[Mapping[str, Any]] = None,
+    ) -> Sequence[str]:
         """Get additional dependencies required for building a wheel.
 
         :returns: A list of :pep:`dependency specifiers <508>`.
-        :rtype: list[str]
 
         .. admonition:: Fallback
 
@@ -169,8 +199,11 @@ def get_requires_for_build_wheel(self, config_settings=None):
         )
 
     def prepare_metadata_for_build_wheel(
-        self, metadata_directory, config_settings=None, _allow_fallback=True
-    ):
+        self,
+        metadata_directory: str,
+        config_settings: Optional[Mapping[str, Any]] = None,
+        _allow_fallback: bool = True,
+    ) -> Optional[str]:
         """Prepare a ``*.dist-info`` folder with metadata for this project.
 
         :returns: Name of the newly created subfolder within
@@ -194,8 +227,11 @@ def prepare_metadata_for_build_wheel(
         )
 
     def build_wheel(
-        self, wheel_directory, config_settings=None, metadata_directory=None
-    ):
+        self,
+        wheel_directory: str,
+        config_settings: Optional[Mapping[str, Any]] = None,
+        metadata_directory: Optional[str] = None,
+    ) -> str:
         """Build a wheel from this project.
 
         :returns:
@@ -219,11 +255,13 @@ def build_wheel(
             },
         )
 
-    def get_requires_for_build_editable(self, config_settings=None):
+    def get_requires_for_build_editable(
+        self,
+        config_settings: Optional[Mapping[str, Any]] = None,
+    ) -> Sequence[str]:
         """Get additional dependencies required for building an editable wheel.
 
         :returns: A list of :pep:`dependency specifiers <508>`.
-        :rtype: list[str]
 
         .. admonition:: Fallback
 
@@ -235,8 +273,11 @@ def get_requires_for_build_editable(self, config_settings=None):
         )
 
     def prepare_metadata_for_build_editable(
-        self, metadata_directory, config_settings=None, _allow_fallback=True
-    ):
+        self,
+        metadata_directory: str,
+        config_settings: Optional[Mapping[str, Any]] = None,
+        _allow_fallback: bool = True,
+    ) -> Optional[str]:
         """Prepare a ``*.dist-info`` folder with metadata for this project.
 
         :returns: Name of the newly created subfolder within
@@ -260,8 +301,11 @@ def prepare_metadata_for_build_editable(
         )
 
     def build_editable(
-        self, wheel_directory, config_settings=None, metadata_directory=None
-    ):
+        self,
+        wheel_directory: str,
+        config_settings: Optional[Mapping[str, Any]] = None,
+        metadata_directory: Optional[str] = None,
+    ) -> str:
         """Build an editable wheel from this project.
 
         :returns:
@@ -286,17 +330,23 @@ def build_editable(
             },
         )
 
-    def get_requires_for_build_sdist(self, config_settings=None):
+    def get_requires_for_build_sdist(
+        self,
+        config_settings: Optional[Mapping[str, Any]] = None,
+    ) -> Sequence[str]:
         """Get additional dependencies required for building an sdist.
 
         :returns: A list of :pep:`dependency specifiers <508>`.
-        :rtype: list[str]
         """
         return self._call_hook(
             "get_requires_for_build_sdist", {"config_settings": config_settings}
         )
 
-    def build_sdist(self, sdist_directory, config_settings=None):
+    def build_sdist(
+        self,
+        sdist_directory: str,
+        config_settings: Optional[Mapping[str, Any]] = None,
+    ) -> str:
         """Build an sdist from this project.
 
         :returns:
@@ -310,7 +360,7 @@ def build_sdist(self, sdist_directory, config_settings=None):
             },
         )
 
-    def _call_hook(self, hook_name, kwargs):
+    def _call_hook(self, hook_name: str, kwargs: Mapping[str, Any]) -> Any:
         extra_environ = {"PEP517_BUILD_BACKEND": self.build_backend}
 
         if self.backend_path: