Export pluggy's typing

changelog/428.feature.rst

@@ -0,0 +1,18 @@
+Pluggy now exposes its typings to static type checkers.
+
+As part of this, the following changes are made:
+
+- Renamed ``_Result`` to ``Result``, and exported as :class:`pluggy.Result`.
+- Renamed ``_HookRelay`` to ``HookRelay``, and exported as :class:`pluggy.HookRelay`.
+- Renamed ``_HookCaller`` to ``HookCaller``, and exported as :class:`pluggy.HookCaller`.
+- Exported ``HookImpl`` as :class:`pluggy.HookImpl`.
+- Renamed ``_HookImplOpts`` to ``HookimplOpts``, and exported as :class:`pluggy.HookimplOpts`.
+- Renamed ``_HookSpecOpts`` to ``HookspecOpts``, and exported as :class:`pluggy.HookspecOpts`.
+- Some fields and classes are marked ``Final`` and ``@final``.
+- The :ref:`api-reference` is updated to clearly delineate pluggy's public API.
+
+Compatibility aliases are put in place for the renamed types.
+We do not plan to remove the aliases, but we strongly recommend to only import from ``pluggy.*`` to ensure future compatibility.
+
+Please note that pluggy is currently unable to provide strong typing for hook calls, e.g. ``pm.hook.my_hook(...)``,
+nor to statically check that a hook implementation matches the hook specification's type.

docs/api_reference.rst

@@ -1,5 +1,7 @@
 :orphan:
 
+.. _`api-reference`:
+
 API Reference
 =============
 

setup.cfg

@@ -42,6 +42,8 @@ dev =
 testing =
     pytest
     pytest-benchmark
+[options.package_data]
+pluggy = py.typed
 
 [devpi:upload]
 formats=sdist.tgz,bdist_wheel

src/pluggy/__init__.py

@@ -6,6 +6,7 @@
     __version__ = "unknown"
 
 __all__ = [
+    "__version__",
     "PluginManager",
     "PluginValidationError",
     "HookCaller",

src/pluggy/_tracing.py

@@ -9,8 +9,8 @@
 from typing import Tuple
 
 
-_Writer = Callable[[str], None]
-_Processor = Callable[[Tuple[str, ...], Tuple[Any, ...]], None]
+_Writer = Callable[[str], object]
+_Processor = Callable[[Tuple[str, ...], Tuple[Any, ...]], object]
 
 
 class TagTracer: