diff --git a/changelog/313.removal.rst b/changelog/313.removal.rst new file mode 100644 index 00000000..0df4bbb2 --- /dev/null +++ b/changelog/313.removal.rst @@ -0,0 +1,2 @@ +The internal ``pluggy.callers``, ``pluggy.manager`` and ``pluggy.hooks`` are now explicitly marked private by a ``_`` prefix (e.g. ``pluggy._callers``). +Only API exported by the top-level ``pluggy`` module is considered public. diff --git a/docs/api_reference.rst b/docs/api_reference.rst index 393d0aeb..d9552d44 100644 --- a/docs/api_reference.rst +++ b/docs/api_reference.rst @@ -8,12 +8,12 @@ Api Reference :undoc-members: :show-inheritance: -.. autoclass:: pluggy.callers._Result -.. automethod:: pluggy.callers._Result.get_result -.. automethod:: pluggy.callers._Result.force_result +.. autoclass:: pluggy._callers._Result +.. automethod:: pluggy._callers._Result.get_result +.. automethod:: pluggy._callers._Result.force_result -.. autoclass:: pluggy.hooks._HookCaller -.. automethod:: pluggy.hooks._HookCaller.call_extra -.. automethod:: pluggy.hooks._HookCaller.call_historic +.. autoclass:: pluggy._hooks._HookCaller +.. automethod:: pluggy._hooks._HookCaller.call_extra +.. automethod:: pluggy._hooks._HookCaller.call_historic -.. autoclass:: pluggy.hooks._HookRelay +.. autoclass:: pluggy._hooks._HookRelay diff --git a/docs/index.rst b/docs/index.rst index 49e8b08b..5559156c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -395,11 +395,11 @@ be implemented as generator function with a single ``yield`` in its body: if config.use_defaults: outcome.force_result(defaults) -The generator is :py:meth:`sent ` a :py:class:`pluggy.callers._Result` object which can +The generator is :py:meth:`sent ` a :py:class:`pluggy._callers._Result` object which can be assigned in the ``yield`` expression and used to override or inspect the final result(s) returned back to the caller using the -:py:meth:`~pluggy.callers._Result.force_result` or -:py:meth:`~pluggy.callers._Result.get_result` methods. +:py:meth:`~pluggy._callers._Result.force_result` or +:py:meth:`~pluggy._callers._Result.get_result` methods. .. note:: Hook wrappers can **not** return results (as per generator function @@ -533,7 +533,7 @@ Also see the :ref:`pytest:firstresult` section in the ``pytest`` docs. Historic hooks ^^^^^^^^^^^^^^ You can mark a *hookspec* as being *historic* meaning that the hook -can be called with :py:meth:`~pluggy.hooks._HookCaller.call_historic()` **before** +can be called with :py:meth:`~pluggy._hooks._HookCaller.call_historic()` **before** having been registered: .. code-block:: python @@ -655,13 +655,13 @@ The core functionality of ``pluggy`` enables an extension provider to override function calls made at certain points throughout a program. A particular *hook* is invoked by calling an instance of -a :py:class:`pluggy.hooks._HookCaller` which in turn *loops* through the +a :py:class:`pluggy._hooks._HookCaller` which in turn *loops* through the ``1:N`` registered *hookimpls* and calls them in sequence. Every :py:class:`~pluggy.PluginManager` has a ``hook`` attribute -which is an instance of this :py:class:`pluggy.hooks._HookRelay`. -The :py:class:`~pluggy.hooks._HookRelay` itself contains references -(by hook name) to each registered *hookimpl*'s :py:class:`~pluggy.hooks._HookCaller` instance. +which is an instance of this :py:class:`pluggy._hooks._HookRelay`. +The :py:class:`~pluggy._hooks._HookRelay` itself contains references +(by hook name) to each registered *hookimpl*'s :py:class:`~pluggy._hooks._HookCaller` instance. More practically you call a *hook* like so: @@ -801,7 +801,7 @@ only useful if you expect that some *hookimpls* may be registered **after** the hook is initially invoked. Historic hooks must be :ref:`specially marked ` and called -using the :py:meth:`~pluggy.hooks._HookCaller.call_historic()` method: +using the :py:meth:`~pluggy._hooks._HookCaller.call_historic()` method: .. code-block:: python @@ -822,8 +822,8 @@ using the :py:meth:`~pluggy.hooks._HookCaller.call_historic()` method: # historic callback is invoked here pm.register(mylateplugin) -Note that if you :py:meth:`~pluggy.hooks._HookCaller.call_historic()` -the :py:class:`~pluggy.hooks._HookCaller` (and thus your calling code) +Note that if you :py:meth:`~pluggy._hooks._HookCaller.call_historic()` +the :py:class:`~pluggy._hooks._HookCaller` (and thus your calling code) can not receive results back from the underlying *hookimpl* functions. Instead you can provide a *callback* for processing results (like the ``callback`` function above) which will be called as each new plugin @@ -838,19 +838,19 @@ Calling with extras ------------------- You can call a hook with temporarily participating *implementation* functions (that aren't in the registry) using the -:py:meth:`pluggy.hooks._HookCaller.call_extra()` method. +:py:meth:`pluggy._hooks._HookCaller.call_extra()` method. Calling with a subset of registered plugins ------------------------------------------- You can make a call using a subset of plugins by asking the :py:class:`~pluggy.PluginManager` first for a -:py:class:`~pluggy.hooks._HookCaller` with those plugins removed +:py:class:`~pluggy._hooks._HookCaller` with those plugins removed using the :py:meth:`pluggy.PluginManager.subset_hook_caller()` method. -You then can use that :py:class:`_HookCaller ` -to make normal, :py:meth:`~pluggy.hooks._HookCaller.call_historic`, or -:py:meth:`~pluggy.hooks._HookCaller.call_extra` calls as necessary. +You then can use that :py:class:`_HookCaller ` +to make normal, :py:meth:`~pluggy._hooks._HookCaller.call_historic`, or +:py:meth:`~pluggy._hooks._HookCaller.call_extra` calls as necessary. Built-in tracing **************** diff --git a/src/pluggy/__init__.py b/src/pluggy/__init__.py index fb4f991a..979028f7 100644 --- a/src/pluggy/__init__.py +++ b/src/pluggy/__init__.py @@ -13,6 +13,6 @@ "HookimplMarker", ] -from .manager import PluginManager, PluginValidationError -from .callers import HookCallError -from .hooks import HookspecMarker, HookimplMarker +from ._manager import PluginManager, PluginValidationError +from ._callers import HookCallError +from ._hooks import HookspecMarker, HookimplMarker diff --git a/src/pluggy/callers.py b/src/pluggy/_callers.py similarity index 100% rename from src/pluggy/callers.py rename to src/pluggy/_callers.py diff --git a/src/pluggy/hooks.py b/src/pluggy/_hooks.py similarity index 100% rename from src/pluggy/hooks.py rename to src/pluggy/_hooks.py diff --git a/src/pluggy/manager.py b/src/pluggy/_manager.py similarity index 98% rename from src/pluggy/manager.py rename to src/pluggy/_manager.py index 62b999f9..c780c21a 100644 --- a/src/pluggy/manager.py +++ b/src/pluggy/_manager.py @@ -1,10 +1,11 @@ import inspect import sys -from . import _tracing -from .callers import _Result, _multicall -from .hooks import HookImpl, _HookRelay, _HookCaller, normalize_hookimpl_opts import warnings +from . import _tracing +from ._callers import _Result, _multicall +from ._hooks import HookImpl, _HookRelay, _HookCaller, normalize_hookimpl_opts + if sys.version_info >= (3, 8): from importlib import metadata as importlib_metadata else: @@ -312,7 +313,7 @@ def add_hookcall_monitoring(self, before, after): of HookImpl instances and the keyword arguments for the hook call. ``after(outcome, hook_name, hook_impls, kwargs)`` receives the - same arguments as ``before`` but also a :py:class:`pluggy.callers._Result` object + same arguments as ``before`` but also a :py:class:`pluggy._callers._Result` object which represents the result of the overall hook call. """ oldcall = self._inner_hookexec diff --git a/testing/benchmark.py b/testing/benchmark.py index 7eec4111..e0d8b031 100644 --- a/testing/benchmark.py +++ b/testing/benchmark.py @@ -3,8 +3,8 @@ """ import pytest from pluggy import HookspecMarker, HookimplMarker -from pluggy.hooks import HookImpl -from pluggy.callers import _multicall +from pluggy._hooks import HookImpl +from pluggy._callers import _multicall hookspec = HookspecMarker("example") diff --git a/testing/test_helpers.py b/testing/test_helpers.py index da3c08c9..465858c4 100644 --- a/testing/test_helpers.py +++ b/testing/test_helpers.py @@ -1,5 +1,5 @@ -from pluggy.hooks import varnames -from pluggy.manager import _formatdef +from pluggy._hooks import varnames +from pluggy._manager import _formatdef def test_varnames(): diff --git a/testing/test_hookcaller.py b/testing/test_hookcaller.py index 98cfdc67..9eeaef86 100644 --- a/testing/test_hookcaller.py +++ b/testing/test_hookcaller.py @@ -1,7 +1,7 @@ import pytest from pluggy import HookimplMarker, HookspecMarker, PluginValidationError -from pluggy.hooks import HookImpl +from pluggy._hooks import HookImpl hookspec = HookspecMarker("example") hookimpl = HookimplMarker("example") diff --git a/testing/test_multicall.py b/testing/test_multicall.py index 554ed196..8ffb452f 100644 --- a/testing/test_multicall.py +++ b/testing/test_multicall.py @@ -1,7 +1,7 @@ import pytest from pluggy import HookCallError, HookspecMarker, HookimplMarker -from pluggy.hooks import HookImpl -from pluggy.callers import _multicall +from pluggy._hooks import HookImpl +from pluggy._callers import _multicall hookspec = HookspecMarker("example") diff --git a/testing/test_pluginmanager.py b/testing/test_pluginmanager.py index 6eb50457..304a007a 100644 --- a/testing/test_pluginmanager.py +++ b/testing/test_pluginmanager.py @@ -9,7 +9,7 @@ HookimplMarker, HookspecMarker, ) -from pluggy.manager import importlib_metadata +from pluggy._manager import importlib_metadata hookspec = HookspecMarker("example")