From 62da97c2d6cc0821774bc3cb2fa210f8592f7d13 Mon Sep 17 00:00:00 2001 From: Ran Benita Date: Mon, 14 Aug 2023 21:43:35 +0300 Subject: [PATCH] Export pluggy's typing Fix #428. --- changelog/428.feature.rst | 18 ++++++++++++++++++ docs/api_reference.rst | 2 ++ setup.cfg | 2 ++ src/pluggy/py.typed | 0 4 files changed, 22 insertions(+) create mode 100644 changelog/428.feature.rst create mode 100644 src/pluggy/py.typed diff --git a/changelog/428.feature.rst b/changelog/428.feature.rst new file mode 100644 index 00000000..8b79dffb --- /dev/null +++ b/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. diff --git a/docs/api_reference.rst b/docs/api_reference.rst index 6580fa9e..40b27bfe 100644 --- a/docs/api_reference.rst +++ b/docs/api_reference.rst @@ -1,5 +1,7 @@ :orphan: +.. _`api-reference`: + API Reference ============= diff --git a/setup.cfg b/setup.cfg index d04c6133..1e34d361 100644 --- a/setup.cfg +++ b/setup.cfg @@ -42,6 +42,8 @@ dev = testing = pytest pytest-benchmark +[options.package_data] +pluggy = py.typed [devpi:upload] formats=sdist.tgz,bdist_wheel diff --git a/src/pluggy/py.typed b/src/pluggy/py.typed new file mode 100644 index 00000000..e69de29b