Type annotate the public API

.github/workflows/ci.yml

@@ -29,7 +29,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:

.gitignore

@@ -3,7 +3,7 @@ __pycache__/
 /dist/
 .nox
 .pytest_cache
-doc/_build/
+docs/_build/
 *.egg-info/
 .coverage
 htmlcov/

.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
 ----
 

docs/conf.py

@@ -30,8 +30,11 @@
 # -- Options for autodoc -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration
 
+autodoc_class_signature = "separated"
 autodoc_member_order = "bysource"
+autodoc_preserve_defaults = True
 autodoc_typehints = "description"
+autodoc_typehints_description_target = "documented_params"
 
 # -- Options for intersphinx -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#configuration

docs/pyproject_hooks.rst

@@ -22,18 +22,31 @@ Custom Subprocess Runners
 
 It is possible to provide a custom subprocess runner, that behaves differently. The expected protocol for subprocess runners is as follows:
 
-.. function:: subprocess_runner_protocol(cmd, cwd, extra_environ)
+.. function:: subprocess_runner_protocol(cmd, cwd=None, extra_environ=None)
    :noindex:
 
    :param cmd: The command and arguments to execute, as would be passed to :func:`subprocess.run`.
-   :type cmd: list[str]
+   :type cmd: typing.Sequence[str]
    :param cwd: The working directory that must be used for the subprocess.
-   :type cwd: str
+   :type cwd: typing.Optional[str]
    :param extra_environ: Mapping of environment variables (name to value) which must be set for the subprocess execution.
-   :type extra_environ: dict[str, str]
+   :type extra_environ: typing.Optional[typing.Mapping[str, str]]
 
    :rtype: None
 
+Since this codebase is currently Python 3.7-compatible, the type annotation for this protocol is only available to type checkers. To annotate a variable as a subprocess runner, you can do something along the lines of:
+
+.. code-block:: python
+
+   from typing import TYPE_CHECKING
+
+   if TYPE_CHECKING:
+      from pyproject_hooks import SubprocessRunner
+
+   # Example usage
+   def build(awesome_runner: "SubprocessRunner") -> None:
+      ...
+
 Exceptions
 ----------
 

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(".")
@@ -40,7 +40,7 @@ def lint(session: nox.Session) -> None:
     session.run("pre-commit", "run", *args)
 
 
-@nox.session(name="docs-live")
+@nox.session
 def release(session: nox.Session) -> None:
     session.install("flit")
     session.run("flit", "publish")

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/__init__.py

@@ -1,6 +1,8 @@
 """Wrappers to call pyproject.toml-based build backend hooks.
 """
 
+from typing import TYPE_CHECKING
+
 from ._impl import (
     BackendUnavailable,
     BuildBackendHookCaller,
@@ -19,3 +21,6 @@
     "quiet_subprocess_runner",
     "BuildBackendHookCaller",
 ]
+
+if TYPE_CHECKING:
+    from ._impl import SubprocessRunner  # noqa: F401