Prefix all internal modules with _ to clarify they're private

Some were already prefixed, but some weren't.

This clarifies that pluggy's only public API is what's exported from the
top-level `pluggy` module.

This will allow internal code to be nicer, not having to defensively
prefix internal types and functions with _.

Fixes pytest-dev#313.

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.

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

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 <python:generator.send>` a :py:class:`pluggy.callers._Result` object which can
+The generator is :py:meth:`sent <python:generator.send>` 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 <historic>` 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 <pluggy.hooks._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 <pluggy.__hooks._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
 ****************

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

src/pluggy/manager.py → 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

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")

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():

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")

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")

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")