From fc608edd6f3d29e3b44d63b7bb0b9ec8168391fb Mon Sep 17 00:00:00 2001 From: Talley Lambert Date: Mon, 27 Jan 2020 12:29:07 -0500 Subject: [PATCH 1/3] add docs for specname --- docs/index.rst | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/docs/index.rst b/docs/index.rst index 72546dc2..6fb1b2e9 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -268,6 +268,35 @@ then the *hookimpl* should be marked with the ``"optionalhook"`` option: return config +.. _specname: + +Hook implementation naming +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +During plugin :ref:`registration `, hook implementations are +matched to a hook :ref:`specifications ` in the *host* program with the +same name as the function being decorated by ``@hookimpl`` (e.g. +``setup_project`` in the example above). + +*new in version 0.13.2:* + +To override the default behavior, a *hookimpl* may also be matched to a +*hookspec* in the ``host program`` with a non-matching name by using the +``specname`` option. Continuing the example above, the *hookimpl* function +does not need to be named ``setup_project``: + +.. code-block:: python + + @hookimpl(specname="setup_project") + def any_plugin_function(config, args): + """This hook is used to process the initial config + and possibly input arguments. + """ + if args: + config.process_args(args) + + return config + Call time order ^^^^^^^^^^^^^^^ By default hooks are :ref:`called ` in LIFO registered order, however, @@ -553,6 +582,7 @@ scans for *hook* functions :ref:`defined on a plugin `. This allows for multiple plugin managers from multiple projects to define hooks alongside each other. +.. _registration: Registration ------------ From dfe89258774fb275bf008d1072c0db1d1c1c0f6b Mon Sep 17 00:00:00 2001 From: Talley Lambert Date: Thu, 6 Feb 2020 21:00:02 -0500 Subject: [PATCH 2/3] update docs --- docs/index.rst | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 6fb1b2e9..77668e45 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -270,20 +270,24 @@ then the *hookimpl* should be marked with the ``"optionalhook"`` option: .. _specname: -Hook implementation naming -^^^^^^^^^^^^^^^^^^^^^^^^^^ +Hookspec name matching +^^^^^^^^^^^^^^^^^^^^^^ -During plugin :ref:`registration `, hook implementations are -matched to a hook :ref:`specifications ` in the *host* program with the -same name as the function being decorated by ``@hookimpl`` (e.g. -``setup_project`` in the example above). +During plugin :ref:`registration `, pluggy attempts to match each +hook implementation declared by the *plugin* to a hook +:ref:`specification ` in the *host* program with the **same name** as +the function being decorated by ``@hookimpl`` (e.g. ``setup_project`` in the +example above). Note: there is *no* strict requirement that each *hookimpl* has +a corresponding *hookspec* (see :ref:`enforcing spec validation `). *new in version 0.13.2:* To override the default behavior, a *hookimpl* may also be matched to a -*hookspec* in the ``host program`` with a non-matching name by using the -``specname`` option. Continuing the example above, the *hookimpl* function -does not need to be named ``setup_project``: +*hookspec* in the *host* program with a non-matching function name by using +the ``specname`` option. Continuing the example above, the *hookimpl* function +does not need to be named ``setup_project``, but if the argument +``specname="setup_project"`` is provided to the ``hookimpl`` decorator, it will +be matched and checked against the ``setup_project`` hookspec: .. code-block:: python @@ -452,6 +456,8 @@ delayed hook validation. which defines ``hookspec`` decorated functions as in the case of ``pytest``'s `hookspec module`_ +.. _enforcing: + Enforcing spec validation ^^^^^^^^^^^^^^^^^^^^^^^^^ By default there is no strict requirement that each *hookimpl* has From 4cdc6e0b65cbe8cd4c64d3eba723eeebf4196cad Mon Sep 17 00:00:00 2001 From: Talley Lambert Date: Thu, 6 Feb 2020 21:36:22 -0500 Subject: [PATCH 3/3] trailing whitespace --- docs/index.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 77668e45..12a775a4 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -277,15 +277,16 @@ During plugin :ref:`registration `, pluggy attempts to match each hook implementation declared by the *plugin* to a hook :ref:`specification ` in the *host* program with the **same name** as the function being decorated by ``@hookimpl`` (e.g. ``setup_project`` in the -example above). Note: there is *no* strict requirement that each *hookimpl* has -a corresponding *hookspec* (see :ref:`enforcing spec validation `). +example above). Note: there is *no* strict requirement that each *hookimpl* +has a corresponding *hookspec* (see +:ref:`enforcing spec validation `). *new in version 0.13.2:* To override the default behavior, a *hookimpl* may also be matched to a *hookspec* in the *host* program with a non-matching function name by using the ``specname`` option. Continuing the example above, the *hookimpl* function -does not need to be named ``setup_project``, but if the argument +does not need to be named ``setup_project``, but if the argument ``specname="setup_project"`` is provided to the ``hookimpl`` decorator, it will be matched and checked against the ``setup_project`` hookspec: