Export pluggy's typing

Fix #428.

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