2 new commits in pytest: https://bitbucket.org/hpk42/pytest/commits/dcc30fc64d62/ Changeset: dcc30fc64d62 Branch: defer-hook-example User: nicoddemus Date: 2014-10-04 17:48:19+00:00 Summary: Adding docs on how to properly add new hooks and using them in 3rd party plugins Affected #: 1 file
diff -r 25aa56b376c11b083ccc6d49057b765bc5e4b87a -r dcc30fc64d62a316598c8363a5871eca545a7bf4 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 =========================================================== 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. _______________________________________________ pytest-commit mailing list pytest-commit@python.org https://mail.python.org/mailman/listinfo/pytest-commit