From 653abad27bbef8cdc28dd9e3a9393fbf0e0b2606 Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Wed, 31 Jan 2018 18:18:15 -0200
Subject: [PATCH] Mention outcome.force_result() and add link to pluggy's docs
Related to #3169
---
doc/en/writing_plugins.rst | 9 +++++++--
1 file changed, 7 insertions(+), 2 deletions(-)
diff --git a/doc/en/writing_plugins.rst b/doc/en/writing_plugins.rst
index 7787f8d32..f5a8ea41e 100644
--- a/doc/en/writing_plugins.rst
+++ b/doc/en/writing_plugins.rst
@@ -462,19 +462,24 @@ Here is an example definition of a hook wrapper::
@pytest.hookimpl(hookwrapper=True)
def pytest_pyfunc_call(pyfuncitem):
- # do whatever you want before the next hook executes
+ do_something_before_next_hook_executes()
outcome = yield
# outcome.excinfo may be None or a (cls, val, tb) tuple
res = outcome.get_result() # will raise if outcome was exception
- # postprocess result
+
+ post_process_result(res)
+
+ outcome.force_result(new_res) # to override the return value to the plugin system
Note that hook wrappers don't return results themselves, they merely
perform tracing or other side effects around the actual hook implementations.
If the result of the underlying hook is a mutable object, they may modify
that result but it's probably better to avoid it.
+For more information, consult the `pluggy documentation <http://pluggy.readthedocs.io/en/latest/#wrappers>`_.
+
Hook function ordering / call example
-------------------------------------