[Pytest-commit] commit/pytest: hpk42: Merged in nicoddemus/pytest/defer-hook-example (pull request #216)

[commits-noreply at bitbucket.org]

1 new commit in pytest:

https://bitbucket.org/hpk42/pytest/commits/9d5d7c0d97ba/
Changeset:   9d5d7c0d97ba
User:        hpk42
Date:        2014-10-06 09:55:35+00:00
Summary:     Merged in nicoddemus/pytest/defer-hook-example (pull request #216)

Documentation for new hooks and how to use them
Affected #:  1 file

diff -r a846b9033a61904fe60fcc64c5dff582cb01d85c -r 9d5d7c0d97ba889a7c369f184122ecdd5ad1f22f doc/en/plugins.txt
--- a/doc/en/plugins.txt
+++ b/doc/en/plugins.txt
@@ -384,6 +384,54 @@
 .. autofunction:: pytest_keyboard_interrupt
 .. autofunction:: pytest_exception_interact
 
+
+Declaring new hooks
+------------------------
+
+Plugins and ``conftest.py`` files may declare new hooks that can then be
+implemented by other plugins in order to alter behaviour or interact with
+the new plugin:
+
+.. autofunction:: pytest_addhooks
+
+Hooks are usually declared as do-nothing functions that contain only
+documentation describing when the hook will be called and what return values
+are expected.
+
+For an example, see `newhooks.py`_ from :ref:`xdist`.
+
+.. _`newhooks.py`: https://bitbucket.org/hpk42/pytest-xdist/src/52082f70e7dd04b00361091b8af906c60fd6700f/xdist/newhooks.py?at=default
+
+
+Using hooks from 3rd party plugins
+-------------------------------------
+
+Using new hooks from plugins as explained above might be a little tricky
+because the standard `Hook specification and validation`_ mechanism:
+if you depend on a plugin that is not installed,
+validation will fail and the error message will not make much sense to your users.
+
+One approach is to defer the hook implementation to a new plugin instead of
+declaring the hook functions directly in your plugin module, for example::
+
+    # contents of myplugin.py
+
+    class DeferPlugin(object):
+        """Simple plugin to defer pytest-xdist hook functions."""
+
+        def pytest_testnodedown(self, node, error):
+            """standard xdist hook function.
+            """
+
+    def pytest_configure(config):
+        if config.pluginmanager.hasplugin('xdist'):
+            config.pluginmanager.register(DeferPlugin())
+
+
+This has the added benefit of allowing you to conditionally install hooks
+depending on which plugins are installed.
+
+
 Reference of objects involved in hooks
 ===========================================================

Repository URL: https://bitbucket.org/hpk42/pytest/

--

This is a commit notification from bitbucket.org. You are receiving
this because you have the service enabled, addressing the recipient of
this email.