Add type annotations

.coveragerc

@@ -12,3 +12,15 @@ source = pluggy/
   */lib/python*/site-packages/pluggy/
   */pypy*/site-packages/pluggy/
   *\Lib\site-packages\pluggy\
+
+[report]
+exclude_lines =
+    # Have to re-enable the standard pragma
+    pragma: no cover
+
+    if TYPE_CHECKING:
+
+    if __name__ == .__main__.:
+
+    # Ignore coverage on lines solely with `...`
+    ^\s*\.\.\.\s*$

.gitignore

@@ -39,6 +39,7 @@ htmlcov/
 .coverage
 .coverage.*
 .cache
+.mypy_cache/
 nosetests.xml
 coverage.xml
 *,cover

.pre-commit-config.yaml

@@ -15,6 +15,14 @@ repos:
     -   id: trailing-whitespace
     -   id: end-of-file-fixer
     -   id: flake8
+        additional_dependencies: [flake8-typing-imports]
+-   repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v0.931
+    hooks:
+    -   id: mypy
+        files: ^(src/|testing/)
+        args: []
+        additional_dependencies: [pytest]
 -   repo: local
     hooks:
     -   id: rst

docs/conf.py

@@ -59,6 +59,7 @@
 # (source start file, name, description, authors, manual section).
 man_pages = [(master_doc, "pluggy", "pluggy Documentation", [author], 1)]
 
+autodoc_typehints = "none"
 
 # -- Options for Texinfo output -------------------------------------------
 

pyproject.toml

@@ -45,3 +45,25 @@ template = "changelog/_template.rst"
   directory = "trivial"
   name = "Trivial/Internal Changes"
   showcontent = true
+
+[tool.mypy]
+mypy_path = "src"
+check_untyped_defs = true
+# Hopefully we can set this someday!
+# disallow_any_expr = true
+disallow_any_generics = true
+disallow_any_unimported = true
+disallow_subclassing_any = true
+disallow_untyped_calls = true
+disallow_untyped_decorators = true
+ignore_missing_imports = true
+implicit_reexport = false
+no_implicit_optional = true
+show_error_codes = true
+strict_equality = true
+strict_optional = true
+warn_redundant_casts = true
+warn_return_any = true
+warn_unreachable = true
+warn_unused_configs = true
+warn_unused_ignores = true

src/pluggy/__init__.py

@@ -14,5 +14,5 @@
 ]
 
 from ._manager import PluginManager, PluginValidationError
-from ._callers import HookCallError
+from ._result import HookCallError
 from ._hooks import HookspecMarker, HookimplMarker

src/pluggy/_callers.py

@@ -2,18 +2,28 @@
 Call loop machinery
 """
 import sys
+from typing import cast, Generator, List, Mapping, Sequence, Union
+from typing import TYPE_CHECKING
 
 from ._result import HookCallError, _Result, _raise_wrapfail
 
+if TYPE_CHECKING:
+    from ._hooks import HookImpl
 
-def _multicall(hook_name, hook_impls, caller_kwargs, firstresult):
+
+def _multicall(
+    hook_name: str,
+    hook_impls: Sequence["HookImpl"],
+    caller_kwargs: Mapping[str, object],
+    firstresult: bool,
+) -> Union[object, List[object]]:
     """Execute a call into multiple python functions/methods and return the
     result(s).
 
     ``caller_kwargs`` comes from _HookCaller.__call__().
     """
     __tracebackhide__ = True
-    results = []
+    results: List[object] = []
     excinfo = None
     try:  # run impl and wrapper setup functions in a loop
         teardowns = []
@@ -30,7 +40,10 @@ def _multicall(hook_name, hook_impls, caller_kwargs, firstresult):
 
                 if hook_impl.hookwrapper:
                     try:
-                        gen = hook_impl.function(*args)
+                        # If this cast is not valid, a type error is raised below,
+                        # which is the desired response.
+                        res = hook_impl.function(*args)
+                        gen = cast(Generator[None, _Result[object], None], res)
                         next(gen)  # first yield
                         teardowns.append(gen)
                     except StopIteration:
@@ -42,10 +55,16 @@ def _multicall(hook_name, hook_impls, caller_kwargs, firstresult):
                         if firstresult:  # halt further impl calls
                             break
         except BaseException:
-            excinfo = sys.exc_info()
+            _excinfo = sys.exc_info()
+            assert _excinfo[0] is not None
+            assert _excinfo[1] is not None
+            assert _excinfo[2] is not None
+            excinfo = (_excinfo[0], _excinfo[1], _excinfo[2])
     finally:
         if firstresult:  # first result hooks return a single value
-            outcome = _Result(results[0] if results else None, excinfo)
+            outcome: _Result[Union[object, List[object]]] = _Result(
+                results[0] if results else None, excinfo
+            )
         else:
             outcome = _Result(results, excinfo)