From 9532856ba38be322809c2992eda6631180f29e3b Mon Sep 17 00:00:00 2001 From: Maxim Nikulin Date: Tue, 30 Jun 2020 19:51:37 +0700 Subject: [PATCH] Note on try-finally for wrappers in docs --- docs/index.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/index.rst b/docs/index.rst index a58e9af4..7aec9879 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -402,9 +402,19 @@ 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. +If a wrapper is intended for setup and tear down of other stuff, +do not forget to surround ``yield`` and ``outcome.get_result()`` +with ``try`` and ``finally`` exactly as it is recommended for +:py:func:`@contextlib.contextmanager `. +``outcome.get_result()`` could raise an exception if some other hook failed. +For future compatibility it is better to assume that ``yield`` could +throw as well. + .. note:: Hook wrappers can **not** return results (as per generator function semantics); they can only modify them using the ``_Result`` API. + However an exception following ``yield`` implicitly replaces result + for the outer wrappers if there are any of them. Also see the :ref:`pytest:hookwrapper` section in the ``pytest`` docs.