From 689176f30c8e8a92cc8f8d22f4821d7fa7c7fe75 Mon Sep 17 00:00:00 2001 From: aizpurua23a <57321880+aizpurua23a@users.noreply.github.com> Date: Tue, 26 Jul 2022 21:22:15 +0200 Subject: [PATCH 01/13] Update fixtures.rst with finalizer execution order Add note to clarify the difference in execution order between after-yield finalizers and `request.addfinalizer` finalizers. --- doc/en/how-to/fixtures.rst | 61 ++++++++++++++++++++++++++++++++++---- 1 file changed, 56 insertions(+), 5 deletions(-) diff --git a/doc/en/how-to/fixtures.rst b/doc/en/how-to/fixtures.rst index b90b40619f5..d4aa13a7d71 100644 --- a/doc/en/how-to/fixtures.rst +++ b/doc/en/how-to/fixtures.rst @@ -729,15 +729,66 @@ Here's how the previous example would look using the ``addfinalizer`` method: assert email in receiving_user.inbox -It's a bit longer than yield fixtures and a bit more complex, but it -does offer some nuances for when you're in a pinch. +Here's how the previous example would look using the ``addfinalizer`` method: + It's a bit longer than yield fixtures and a bit more complex, but it + does offer some nuances for when you're in a pinch. + +Note on finalizer order +"""""""""""""""""""""""" + +Finalizers are executed in a first-in-last-out order, while operations after yield are executed sequentially. +Consider the differences in the following examples: + +.. code-block:: python + + import pytest + from functools import partial + + + @pytest.fixture + def fix_w_finalizers(request): + request.addfinalizer(partial(print, "finalizer_2")) + request.addfinalizer(partial(print, "finalizer_1")) + + @pytest.fixture + def fix_w_yield(): + yield + print("after_yield_1") + print("after_yield_2") + + + def test_foo(fix_w_finalizers): + print("test_foo") + pass + + + def test_bar(fix_w_yield): + print("test_bar") + pass + + .. code-block:: pytest - $ pytest -q test_emaillib.py - . [100%] - 1 passed in 0.12s + $ pytest test_module.py + =========================== test session starts ============================ + platform linux -- Python 3.x.y, pytest-7.x.y, pluggy-1.x.y + collected 2 items + + main.py + test_foo + .finalizer_1 + finalizer_2 + test_bar + .after_yield_1 + after_yield_2 + + +.. code-block:: pytest + $ pytest -q test_emaillib.py + . [100%] + 1 passed in 0.12s .. _`safe teardowns`: Safe teardowns From d5edb314233c146c59433f08ce03b572efff01b1 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Tue, 26 Jul 2022 19:25:52 +0000 Subject: [PATCH 02/13] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- doc/en/how-to/fixtures.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/en/how-to/fixtures.rst b/doc/en/how-to/fixtures.rst index d4aa13a7d71..9498442c8eb 100644 --- a/doc/en/how-to/fixtures.rst +++ b/doc/en/how-to/fixtures.rst @@ -750,6 +750,7 @@ Consider the differences in the following examples: request.addfinalizer(partial(print, "finalizer_2")) request.addfinalizer(partial(print, "finalizer_1")) + @pytest.fixture def fix_w_yield(): yield From 84d89969fb9c88eabac6676e7b8852e9c48db427 Mon Sep 17 00:00:00 2001 From: aizpurua23a <57321880+aizpurua23a@users.noreply.github.com> Date: Tue, 26 Jul 2022 21:28:19 +0200 Subject: [PATCH 03/13] Edit fixtures.rst to not modify previous lines. --- doc/en/how-to/fixtures.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/doc/en/how-to/fixtures.rst b/doc/en/how-to/fixtures.rst index 9498442c8eb..899474b88c0 100644 --- a/doc/en/how-to/fixtures.rst +++ b/doc/en/how-to/fixtures.rst @@ -680,8 +680,6 @@ So to make sure we don't run the finalizer code when we wouldn't need to, we would only add the finalizer once the fixture would have done something that we'd need to teardown. -Here's how the previous example would look using the ``addfinalizer`` method: - .. code-block:: python # content of test_emaillib.py @@ -730,8 +728,8 @@ Here's how the previous example would look using the ``addfinalizer`` method: Here's how the previous example would look using the ``addfinalizer`` method: - It's a bit longer than yield fixtures and a bit more complex, but it - does offer some nuances for when you're in a pinch. +It's a bit longer than yield fixtures and a bit more complex, but it +does offer some nuances for when you're in a pinch. Note on finalizer order """""""""""""""""""""""" From 5b3e2d94f8e1127d229e4a68116a60fbe64a8816 Mon Sep 17 00:00:00 2001 From: aizpurua23a <57321880+aizpurua23a@users.noreply.github.com> Date: Tue, 26 Jul 2022 21:30:07 +0200 Subject: [PATCH 04/13] Revert minor fixtures.rst edits. --- doc/en/how-to/fixtures.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/en/how-to/fixtures.rst b/doc/en/how-to/fixtures.rst index 899474b88c0..edac320abaa 100644 --- a/doc/en/how-to/fixtures.rst +++ b/doc/en/how-to/fixtures.rst @@ -680,6 +680,8 @@ So to make sure we don't run the finalizer code when we wouldn't need to, we would only add the finalizer once the fixture would have done something that we'd need to teardown. +Here's how the previous example would look using the ``addfinalizer`` method: + .. code-block:: python # content of test_emaillib.py @@ -727,7 +729,6 @@ we'd need to teardown. assert email in receiving_user.inbox -Here's how the previous example would look using the ``addfinalizer`` method: It's a bit longer than yield fixtures and a bit more complex, but it does offer some nuances for when you're in a pinch. From 9ee20ef7ebacee24c6c4d2dea01532aa447513f2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adri=C3=A1n=20Aizpurua?= Date: Tue, 26 Jul 2022 21:54:54 +0200 Subject: [PATCH 05/13] fix build and lint --- doc/en/how-to/fixtures.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/en/how-to/fixtures.rst b/doc/en/how-to/fixtures.rst index edac320abaa..585fd2d8cb0 100644 --- a/doc/en/how-to/fixtures.rst +++ b/doc/en/how-to/fixtures.rst @@ -786,6 +786,7 @@ Consider the differences in the following examples: .. code-block:: pytest + $ pytest -q test_emaillib.py . [100%] 1 passed in 0.12s From b5bdd52208f26c7dba80aa962ba543cb966dafb7 Mon Sep 17 00:00:00 2001 From: aizpurua23a <57321880+aizpurua23a@users.noreply.github.com> Date: Wed, 27 Jul 2022 18:34:11 +0200 Subject: [PATCH 06/13] Update doc/en/how-to/fixtures.rst Co-authored-by: Bruno Oliveira --- doc/en/how-to/fixtures.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/en/how-to/fixtures.rst b/doc/en/how-to/fixtures.rst index 585fd2d8cb0..5a10b616f69 100644 --- a/doc/en/how-to/fixtures.rst +++ b/doc/en/how-to/fixtures.rst @@ -759,7 +759,6 @@ Consider the differences in the following examples: def test_foo(fix_w_finalizers): print("test_foo") - pass def test_bar(fix_w_yield): From 22c5394acddb6bfaf5f4b8382eb04064b67fde37 Mon Sep 17 00:00:00 2001 From: aizpurua23a <57321880+aizpurua23a@users.noreply.github.com> Date: Wed, 27 Jul 2022 18:34:16 +0200 Subject: [PATCH 07/13] Update doc/en/how-to/fixtures.rst Co-authored-by: Bruno Oliveira --- doc/en/how-to/fixtures.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/en/how-to/fixtures.rst b/doc/en/how-to/fixtures.rst index 5a10b616f69..8407a3690ad 100644 --- a/doc/en/how-to/fixtures.rst +++ b/doc/en/how-to/fixtures.rst @@ -763,7 +763,6 @@ Consider the differences in the following examples: def test_bar(fix_w_yield): print("test_bar") - pass From 803c536ca448405f0b282bc76e7af05744c9d92f Mon Sep 17 00:00:00 2001 From: aizpurua23a <57321880+aizpurua23a@users.noreply.github.com> Date: Wed, 27 Jul 2022 18:37:33 +0200 Subject: [PATCH 08/13] Update doc/en/how-to/fixtures.rst Co-authored-by: Bruno Oliveira --- doc/en/how-to/fixtures.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/en/how-to/fixtures.rst b/doc/en/how-to/fixtures.rst index 8407a3690ad..de68298420a 100644 --- a/doc/en/how-to/fixtures.rst +++ b/doc/en/how-to/fixtures.rst @@ -738,6 +738,8 @@ Note on finalizer order Finalizers are executed in a first-in-last-out order, while operations after yield are executed sequentially. Consider the differences in the following examples: +.. regendoc:wipe + .. code-block:: python import pytest From b61b6138ec99aa9ab58b4ef2648769f04d23fb86 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adri=C3=A1n=20Aizpurua?= Date: Wed, 27 Jul 2022 18:47:43 +0200 Subject: [PATCH 09/13] merge pass remove --- doc/en/how-to/fixtures.rst | 28 +++++++++++++--------------- 1 file changed, 13 insertions(+), 15 deletions(-) diff --git a/doc/en/how-to/fixtures.rst b/doc/en/how-to/fixtures.rst index de68298420a..742f3c0e7ae 100644 --- a/doc/en/how-to/fixtures.rst +++ b/doc/en/how-to/fixtures.rst @@ -732,6 +732,12 @@ Here's how the previous example would look using the ``addfinalizer`` method: It's a bit longer than yield fixtures and a bit more complex, but it does offer some nuances for when you're in a pinch. +.. code-block:: pytest + + $ pytest -q test_emaillib.py + . [100%] + 1 passed in 0.12s + Note on finalizer order """""""""""""""""""""""" @@ -743,28 +749,24 @@ Consider the differences in the following examples: .. code-block:: python import pytest - from functools import partial @pytest.fixture - def fix_w_finalizers(request): - request.addfinalizer(partial(print, "finalizer_2")) - request.addfinalizer(partial(print, "finalizer_1")) + def test_bar(fix_w_yield1, fix_w_yield2): + print("test_bar") @pytest.fixture - def fix_w_yield(): + def fix_w_yield1(): yield print("after_yield_1") - print("after_yield_2") - - def test_foo(fix_w_finalizers): - print("test_foo") + @pytest.fixture + def fix_w_yield2(): + yield + print("after_yield_2") - def test_bar(fix_w_yield): - print("test_bar") @@ -785,11 +787,7 @@ Consider the differences in the following examples: after_yield_2 -.. code-block:: pytest - $ pytest -q test_emaillib.py - . [100%] - 1 passed in 0.12s .. _`safe teardowns`: Safe teardowns From 059447cecde20d66eddfbcb8c760dd719f0ea6e8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adri=C3=A1n=20Aizpurua?= Date: Wed, 27 Jul 2022 19:10:59 +0200 Subject: [PATCH 10/13] re-add finalizers examples --- doc/en/how-to/fixtures.rst | 36 ++++++++++++++++++++++++++++-------- 1 file changed, 28 insertions(+), 8 deletions(-) diff --git a/doc/en/how-to/fixtures.rst b/doc/en/how-to/fixtures.rst index 742f3c0e7ae..e539990197a 100644 --- a/doc/en/how-to/fixtures.rst +++ b/doc/en/how-to/fixtures.rst @@ -768,6 +768,32 @@ Consider the differences in the following examples: print("after_yield_2") +.. code-block:: pytest + + $ pytest test_module.py + =========================== test session starts ============================ + platform linux -- Python 3.x.y, pytest-7.x.y, pluggy-1.x.y + collected 1 item + + test_module.py test_bar + .after_yield_2 + after_yield_1 + + +.. code-block:: python + + import pytest + + + @pytest.fixture + def fix_w_finalizers(request): + request.addfinalizer(partial(print, "finalizer_2")) + request.addfinalizer(partial(print, "finalizer_1")) + + + @pytest.fixture + def test_bar(fix_w_finalizers): + print("test_bar") .. code-block:: pytest @@ -775,18 +801,12 @@ Consider the differences in the following examples: $ pytest test_module.py =========================== test session starts ============================ platform linux -- Python 3.x.y, pytest-7.x.y, pluggy-1.x.y - collected 2 items + collected 1 item - main.py - test_foo + test_module.py test_bar .finalizer_1 finalizer_2 - test_bar - .after_yield_1 - after_yield_2 - - .. _`safe teardowns`: From fd316339edf32955ba175a4123c893821fa28674 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adri=C3=A1n=20Aizpurua?= Date: Wed, 27 Jul 2022 19:55:50 +0200 Subject: [PATCH 11/13] rework examples and edit copy --- doc/en/how-to/fixtures.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/doc/en/how-to/fixtures.rst b/doc/en/how-to/fixtures.rst index e539990197a..d881f74cc17 100644 --- a/doc/en/how-to/fixtures.rst +++ b/doc/en/how-to/fixtures.rst @@ -741,8 +741,8 @@ does offer some nuances for when you're in a pinch. Note on finalizer order """""""""""""""""""""""" -Finalizers are executed in a first-in-last-out order, while operations after yield are executed sequentially. -Consider the differences in the following examples: +Finalizers are executed in a first-in-last-out order. +For yield fixtures, the first fixture to run is the right-most one, i.e. the last test parameter. .. regendoc:wipe @@ -751,7 +751,6 @@ Consider the differences in the following examples: import pytest - @pytest.fixture def test_bar(fix_w_yield1, fix_w_yield2): print("test_bar") @@ -780,6 +779,9 @@ Consider the differences in the following examples: after_yield_1 + +For finalizers, the first fixture to run is last call to `request.addfinalizer`. + .. code-block:: python import pytest @@ -791,7 +793,6 @@ Consider the differences in the following examples: request.addfinalizer(partial(print, "finalizer_1")) - @pytest.fixture def test_bar(fix_w_finalizers): print("test_bar") @@ -807,6 +808,8 @@ Consider the differences in the following examples: .finalizer_1 finalizer_2 +This is so because yield fixtures use addfinalizer behind the scenes: when the fixture executes, addfinalizer registers a function that resumes the generator, which in turn calls the teardown code. + .. _`safe teardowns`: From 914ad2ec59e3b74b67b9b4d9b51a61e86408f0ba Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adri=C3=A1n=20Aizpurua?= Date: Wed, 27 Jul 2022 19:58:24 +0200 Subject: [PATCH 12/13] added backticks to addfinalizer --- doc/en/how-to/fixtures.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/en/how-to/fixtures.rst b/doc/en/how-to/fixtures.rst index d881f74cc17..6aba2b94bcb 100644 --- a/doc/en/how-to/fixtures.rst +++ b/doc/en/how-to/fixtures.rst @@ -808,7 +808,7 @@ For finalizers, the first fixture to run is last call to `request.addfinalizer`. .finalizer_1 finalizer_2 -This is so because yield fixtures use addfinalizer behind the scenes: when the fixture executes, addfinalizer registers a function that resumes the generator, which in turn calls the teardown code. +This is so because yield fixtures use `addfinalizer` behind the scenes: when the fixture executes, `addfinalizer` registers a function that resumes the generator, which in turn calls the teardown code. .. _`safe teardowns`: From 7aa62732a3158c27411f0291d16b9b65adb66235 Mon Sep 17 00:00:00 2001 From: aizpurua23a <57321880+aizpurua23a@users.noreply.github.com> Date: Wed, 27 Jul 2022 20:28:36 +0200 Subject: [PATCH 13/13] Update doc/en/how-to/fixtures.rst Co-authored-by: Bruno Oliveira --- doc/en/how-to/fixtures.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/en/how-to/fixtures.rst b/doc/en/how-to/fixtures.rst index 6aba2b94bcb..8ab498bd7d4 100644 --- a/doc/en/how-to/fixtures.rst +++ b/doc/en/how-to/fixtures.rst @@ -742,7 +742,7 @@ Note on finalizer order """""""""""""""""""""""" Finalizers are executed in a first-in-last-out order. -For yield fixtures, the first fixture to run is the right-most one, i.e. the last test parameter. +For yield fixtures, the first teardown code to run is from the right-most fixture, i.e. the last test parameter. .. regendoc:wipe