From c1b935adbd7857b74209af266d6ca236b30c10d7 Mon Sep 17 00:00:00 2001 From: Bruno Oliveira Date: Fri, 3 Apr 2015 16:28:20 -0300 Subject: [PATCH 1/6] Removed note about yield fixtures being experimental --HG-- branch : yield-experimental-docs --- doc/en/yieldfixture.txt | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/doc/en/yieldfixture.txt b/doc/en/yieldfixture.txt index f3cc542dc..ef45970b4 100644 --- a/doc/en/yieldfixture.txt +++ b/doc/en/yieldfixture.txt @@ -9,15 +9,7 @@ Fixture functions using "yield" / context manager integration pytest-2.4 allows fixture functions to seamlessly use a ``yield`` instead of a ``return`` statement to provide a fixture value while otherwise -fully supporting all other fixture features. - -.. note:: - - "yielding" fixture values is an experimental feature and its exact - declaration may change later but earliest in a 2.5 release. You can thus - safely use this feature in the 2.4 series but may need to adapt later. - Test functions themselves will not need to change (as a general - feature, they are ignorant of how fixtures are setup). +fully supporting all other fixture features. Let's look at a simple standalone-example using the new ``yield`` syntax:: From 30260361dd6b37510c702e8a68506db5e3507cb3 Mon Sep 17 00:00:00 2001 From: Bruno Oliveira Date: Fri, 3 Apr 2015 16:55:10 -0300 Subject: [PATCH 2/6] Reviewed wording about yield being a "new" feature --HG-- branch : yield-experimental-docs --- doc/en/yieldfixture.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/en/yieldfixture.txt b/doc/en/yieldfixture.txt index ef45970b4..b3a140c1d 100644 --- a/doc/en/yieldfixture.txt +++ b/doc/en/yieldfixture.txt @@ -11,7 +11,7 @@ pytest-2.4 allows fixture functions to seamlessly use a ``yield`` instead of a ``return`` statement to provide a fixture value while otherwise fully supporting all other fixture features. -Let's look at a simple standalone-example using the new ``yield`` syntax:: +Let's look at a simple standalone-example using the ``yield`` syntax:: # content of test_yield.py @@ -64,9 +64,9 @@ The file ``f`` will be closed after the test finished execution because the Python ``file`` object supports finalization when the ``with`` statement ends. -Note that the new syntax is fully integrated with using ``scope``, -``params`` and other fixture features. Changing existing -fixture functions to use ``yield`` is thus straight forward. +Note that the yield fixture form supports all other fixture +features such as ``scope``, ``params``, etc., thus changing existing +fixture functions to use ``yield`` is straight forward. Discussion and future considerations / feedback ++++++++++++++++++++++++++++++++++++++++++++++++++++ @@ -106,7 +106,7 @@ However, there are also limitations or foreseeable irritations: - lastly ``yield`` introduces more than one way to write fixture functions, so what's the obvious way to a newcomer? Newcomers reading the docs will see feature examples using the - ``return`` style so should use that, if in doubt. + ``return`` style so should use that, if in doubt. Others can start experimenting with writing yield-style fixtures and possibly help evolving them further. From 161d9e5971865af57a2defabe4c39d7e9dd0f7ab Mon Sep 17 00:00:00 2001 From: Bruno Oliveira Date: Fri, 3 Apr 2015 16:59:33 -0300 Subject: [PATCH 3/6] Removed "discussion" session Kept a note about exceptions after yield not being reraised --HG-- branch : yield-experimental-docs --- doc/en/yieldfixture.txt | 51 +++++++---------------------------------- 1 file changed, 8 insertions(+), 43 deletions(-) diff --git a/doc/en/yieldfixture.txt b/doc/en/yieldfixture.txt index b3a140c1d..5c7558d7e 100644 --- a/doc/en/yieldfixture.txt +++ b/doc/en/yieldfixture.txt @@ -68,48 +68,13 @@ Note that the yield fixture form supports all other fixture features such as ``scope``, ``params``, etc., thus changing existing fixture functions to use ``yield`` is straight forward. -Discussion and future considerations / feedback -++++++++++++++++++++++++++++++++++++++++++++++++++++ +.. note:: -The yield-syntax has been discussed by pytest users extensively. -In general, the advantages of the using a ``yield`` fixture syntax are: + While the ``yield`` syntax is similar to what + :py:func:`contextlib.contextmanager` decorated functions + provide, with pytest fixture functions the part after the + "yield" will always be invoked, independently from the + exception status of the test function which uses the fixture. + This behaviour makes sense if you consider that many different + test functions might use a module or session scoped fixture. -- easy provision of fixtures in conjunction with context managers. - -- no need to register a callback, providing for more synchronous - control flow in the fixture function. Also there is no need to accept - the ``request`` object into the fixture function just for providing - finalization code. - -However, there are also limitations or foreseeable irritations: - -- usually ``yield`` is used for producing multiple values. - But fixture functions can only yield exactly one value. - Yielding a second fixture value will get you an error. - It's possible we can evolve pytest to allow for producing - multiple values as an alternative to current parametrization. - For now, you can just use the normal - :ref:`fixture parametrization ` - mechanisms together with ``yield``-style fixtures. - -- the ``yield`` syntax is similar to what - :py:func:`contextlib.contextmanager` decorated functions - provide. With pytest fixture functions, the "after yield" part will - always be invoked, independently from the exception status - of the test function which uses the fixture. The pytest - behaviour makes sense if you consider that many different - test functions might use a module or session scoped fixture. - Some test functions might raise exceptions and others not, - so how could pytest re-raise a single exception at the - ``yield`` point in the fixture function? - -- lastly ``yield`` introduces more than one way to write - fixture functions, so what's the obvious way to a newcomer? - Newcomers reading the docs will see feature examples using the - ``return`` style so should use that, if in doubt. - Others can start experimenting with writing yield-style fixtures - and possibly help evolving them further. - -If you want to feedback or participate in the ongoing -discussion, please join our :ref:`contact channels`. -you are most welcome. From b3d646455a495165fa74dedad0d7a159cc7c11f2 Mon Sep 17 00:00:00 2001 From: Bruno Oliveira Date: Fri, 3 Apr 2015 17:06:51 -0300 Subject: [PATCH 4/6] Fixed straightforward spelling --HG-- branch : yield-experimental-docs --- doc/en/yieldfixture.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/en/yieldfixture.txt b/doc/en/yieldfixture.txt index 5c7558d7e..e108a5324 100644 --- a/doc/en/yieldfixture.txt +++ b/doc/en/yieldfixture.txt @@ -66,7 +66,7 @@ the ``with`` statement ends. Note that the yield fixture form supports all other fixture features such as ``scope``, ``params``, etc., thus changing existing -fixture functions to use ``yield`` is straight forward. +fixture functions to use ``yield`` is straightforward. .. note:: From 6558c7245fe5d41f2909eaf876ad846226e6686d Mon Sep 17 00:00:00 2001 From: Bruno Oliveira Date: Fri, 3 Apr 2015 19:44:06 -0300 Subject: [PATCH 5/6] Brought back discussion session Reworded it a bit to bring it to par with the current status --HG-- branch : yield-experimental-docs --- doc/en/yieldfixture.txt | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/doc/en/yieldfixture.txt b/doc/en/yieldfixture.txt index e108a5324..0fc7b5099 100644 --- a/doc/en/yieldfixture.txt +++ b/doc/en/yieldfixture.txt @@ -78,3 +78,23 @@ fixture functions to use ``yield`` is straightforward. This behaviour makes sense if you consider that many different test functions might use a module or session scoped fixture. + +Discussion and future considerations / feedback +++++++++++++++++++++++++++++++++++++++++++++++++++++ + +There are some topics that are worth mentioning: + +- usually ``yield`` is used for producing multiple values. + But fixture functions can only yield exactly one value. + Yielding a second fixture value will get you an error. + It's possible we can evolve pytest to allow for producing + multiple values as an alternative to current parametrization. + For now, you can just use the normal + :ref:`fixture parametrization ` + mechanisms together with ``yield``-style fixtures. + +- lastly ``yield`` introduces more than one way to write + fixture functions, so what's the obvious way to a newcomer? + +If you want to feedback or participate in discussion of the above +topics, please join our :ref:`contact channels`, you are most welcome.