From 97cb4db3ae5da34bfe4520e0963d7133ea98bf22 Mon Sep 17 00:00:00 2001 From: Michael Seifert Date: Wed, 12 Jul 2023 10:24:05 +0200 Subject: [PATCH 1/3] [docs] Explain that scopes of event_loop fixtures should not overlap. The example for overriding event loop scopes now uses a module scope rather than a session scope. Due to the constraint that event_loop fixture scopes should not overlap, a session-scoped fixture is usually not that helpful. Addresses #531 Signed-off-by: Michael Seifert --- docs/source/reference/fixtures.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/source/reference/fixtures.rst b/docs/source/reference/fixtures.rst index fdd3e034..f7398a15 100644 --- a/docs/source/reference/fixtures.rst +++ b/docs/source/reference/fixtures.rst @@ -25,13 +25,18 @@ fixture scope, for example: .. code-block:: python - @pytest.fixture(scope="session") + @pytest.fixture(scope="module") def event_loop(): policy = asyncio.get_event_loop_policy() loop = policy.new_event_loop() yield loop loop.close() +When defining multiple ``event_loop`` fixtures, you should ensure that their scopes don't overlap. +Each of the fixtures replace the running event loop, potentially without proper clean up. +This will emit a warning and likely lead to errors in your tests suite. +You can manually check for overlapping ``event_loop`` fixtures by running pytest with the ``--setup-show`` option. + If you need to change the type of the event loop, prefer setting a custom event loop policy over redefining the ``event_loop`` fixture. If the ``pytest.mark.asyncio`` decorator is applied to a test function, the ``event_loop`` From 10b004607c15e4f37ab6e0a910e74bc298745540 Mon Sep 17 00:00:00 2001 From: Michael Seifert Date: Wed, 12 Jul 2023 10:28:03 +0200 Subject: [PATCH 2/3] [feat] Extend warning message about unclosed event loops with additional possible cause. Closes #531 Signed-off-by: Michael Seifert --- docs/source/reference/changelog.rst | 2 ++ pytest_asyncio/plugin.py | 3 ++- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/source/reference/changelog.rst b/docs/source/reference/changelog.rst index 8e5e7d08..00b73fa0 100644 --- a/docs/source/reference/changelog.rst +++ b/docs/source/reference/changelog.rst @@ -5,6 +5,8 @@ Changelog 0.22.0 (UNRELEASED) =================== - Output a proper error message when an invalid ``asyncio_mode`` is selected. +- Extend warning message about unclosed event loops with additional possible cause. + `#531 `_ 0.21.0 (2023-03-19) =================== diff --git a/pytest_asyncio/plugin.py b/pytest_asyncio/plugin.py index b7c3fcbf..12669791 100644 --- a/pytest_asyncio/plugin.py +++ b/pytest_asyncio/plugin.py @@ -434,7 +434,8 @@ def _add_finalizers(fixturedef: FixtureDef, *finalizers: Callable[[], object]) - library will no longer do so. In order to ensure compatibility with future versions, please make sure that: 1. Any custom "event_loop" fixture properly closes the loop after yielding it - 2. Your code does not modify the event loop in async fixtures or tests + 2. The scopes of your custom "event_loop" fixtures do not overlap + 3. Your code does not modify the event loop in async fixtures or tests """ ) From 83c77167fc881b8e5829bd76b3243f4d8a3f3411 Mon Sep 17 00:00:00 2001 From: Michael Seifert Date: Wed, 12 Jul 2023 10:29:49 +0200 Subject: [PATCH 3/3] [docs] Improved readbility of headings on the fixtures reference in the docs. The headings no longer use the "pre-formatted" text style. Signed-off-by: Michael Seifert --- docs/source/reference/fixtures.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/source/reference/fixtures.rst b/docs/source/reference/fixtures.rst index f7398a15..adcc092d 100644 --- a/docs/source/reference/fixtures.rst +++ b/docs/source/reference/fixtures.rst @@ -2,8 +2,8 @@ Fixtures ======== -``event_loop`` -============== +event_loop +========== Creates a new asyncio event loop based on the current event loop policy. The new loop is available as the return value of this fixture or via `asyncio.get_running_loop `__. The event loop is closed when the fixture scope ends. The fixture scope defaults @@ -42,13 +42,13 @@ If you need to change the type of the event loop, prefer setting a custom event If the ``pytest.mark.asyncio`` decorator is applied to a test function, the ``event_loop`` fixture will be requested automatically by the test function. -``unused_tcp_port`` -=================== +unused_tcp_port +=============== Finds and yields a single unused TCP port on the localhost interface. Useful for binding temporary test servers. -``unused_tcp_port_factory`` -=========================== +unused_tcp_port_factory +======================= A callable which returns a different unused TCP port each invocation. Useful when several unused TCP ports are required in a test. @@ -58,6 +58,6 @@ when several unused TCP ports are required in a test. port1, port2 = unused_tcp_port_factory(), unused_tcp_port_factory() ... -``unused_udp_port`` and ``unused_udp_port_factory`` -=================================================== +unused_udp_port and unused_udp_port_factory +=========================================== Works just like their TCP counterparts but returns unused UDP ports.