Initial type annotations

mypy.ini

@@ -0,0 +1,12 @@
+[mypy]
+#python_version = 3.6
+mypy_path = $MYPY_CONFIG_FILE_DIR/src
+
+warn_return_any = True
+warn_unused_configs = True
+
+[mypy-pluggy.*]
+
+disallow_untyped_defs = True
+warn_return_any = True
+disallow_any_expr = True

setup.cfg

@@ -47,6 +47,7 @@ dev =
 testing =
     pytest
     pytest-benchmark
-
+    mypy
+    importlib-metadata>=0.12 # keep in sync
 [devpi:upload]
 formats=sdist.tgz,bdist_wheel

src/pluggy/_callers.py

@@ -3,20 +3,61 @@
 """
 import sys
 
-from ._result import HookCallError, _Result, _raise_wrapfail
+from ._result import (
+    HookCallError,
+    _Result,
+    WrapResult,
+    _raise_wrapfail,
+    EXCINFO,
+    SomeResult,
+)
+from typing import List, TYPE_CHECKING, Dict, cast, overload, Union, Callable
+from typing_extensions import Literal
 
+if TYPE_CHECKING:
+    from ._hooks import HookImpl
 
-def _multicall(hook_name, hook_impls, caller_kwargs, firstresult):
+HookImpls = List["HookImpl"]
+HookArgs = Dict[str, object]
+HookResultCallback = Callable[[SomeResult], SomeResult]
+
+
+@overload
+def _multicall(
+    hook_name: str,
+    hook_impls: HookImpls,
+    caller_kwargs: HookArgs,
+    firstresult: Literal[False],
+) -> List[SomeResult]:
+    pass
+
+
+@overload
+def _multicall(
+    hook_name: str,
+    hook_impls: HookImpls,
+    caller_kwargs: HookArgs,
+    firstresult: Literal[True],
+) -> SomeResult:
+    pass
+
+
+def _multicall(
+    hook_name: str,
+    hook_impls: HookImpls,
+    caller_kwargs: HookArgs,
+    firstresult: bool,
+) -> Union[List[SomeResult], SomeResult]:
     """Execute a call into multiple python functions/methods and return the
     result(s).
 
     ``caller_kwargs`` comes from _HookCaller.__call__().
     """
     __tracebackhide__ = True
     results = []
-    excinfo = None
+    excinfo: EXCINFO = None, None, None
     try:  # run impl and wrapper setup functions in a loop
-        teardowns = []
+        teardowns: List[WrapResult] = []
         try:
             for hook_impl in reversed(hook_impls):
                 try:
@@ -30,7 +71,7 @@ def _multicall(hook_name, hook_impls, caller_kwargs, firstresult):
 
                 if hook_impl.hookwrapper:
                     try:
-                        gen = hook_impl.function(*args)
+                        gen = cast(WrapResult, hook_impl.function(*args))
                         next(gen)  # first yield
                         teardowns.append(gen)
                     except StopIteration: