From 25c54a541707d7e4f3f4098c5d28a9534380180e Mon Sep 17 00:00:00 2001 From: Michael Seifert Date: Tue, 5 Jul 2022 06:27:25 +0200 Subject: [PATCH] Clarify documentation of event_loop fixture (#375) * docs: Removed contradicting information about the event_loop fixture not setting the global event loop. Signed-off-by: Michael Seifert * docs: Clarified the effect of pytest.mark.asyncio with regards to the event_loop fixture. Signed-off-by: Michael Seifert * docs: Provide an example for redefining the event_loop fixture rather than for setting a custom event loop. Signed-off-by: Michael Seifert --- README.rst | 30 ++++++++++++++---------------- 1 file changed, 14 insertions(+), 16 deletions(-) diff --git a/README.rst b/README.rst index 17a10f67..12c76eb0 100644 --- a/README.rst +++ b/README.rst @@ -123,19 +123,16 @@ Fixtures ``event_loop`` ~~~~~~~~~~~~~~ -Creates and injects a new instance of the default asyncio event loop. By -default, the loop will be closed at the end of the test (i.e. the default -fixture scope is ``function``). +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 +to ``function`` scope. Note that just using the ``event_loop`` fixture won't make your test function a coroutine. You'll need to interact with the event loop directly, using methods like ``event_loop.run_until_complete``. See the ``pytest.mark.asyncio`` marker for treating test functions like coroutines. -Simply using this fixture will not set the generated event loop as the -default asyncio event loop, or change the asyncio event loop policy in any way. -Use ``pytest.mark.asyncio`` for this purpose. - .. code-block:: python def test_http_client(event_loop): @@ -143,22 +140,23 @@ Use ``pytest.mark.asyncio`` for this purpose. resp = event_loop.run_until_complete(http_client(url)) assert b"HTTP/1.1 200 OK" in resp -This fixture can be easily overridden in any of the standard pytest locations -(e.g. directly in the test file, or in ``conftest.py``) to use a non-default -event loop. This will take effect even if you're using the -``pytest.mark.asyncio`` marker and not the ``event_loop`` fixture directly. +The ``event_loop`` fixture can be overridden in any of the standard pytest locations, +e.g. directly in the test file, or in ``conftest.py``. This allows redefining the +fixture scope, for example: .. code-block:: python - @pytest.fixture + @pytest.fixture(scope="session") def event_loop(): - loop = MyCustomLoop() + policy = asyncio.get_event_loop_policy() + loop = policy.new_event_loop() yield loop loop.close() -If the ``pytest.mark.asyncio`` marker is applied, a pytest hook will -ensure the produced loop is set as the default global loop. -Fixtures depending on the ``event_loop`` fixture can expect the policy to be properly modified when they run. +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`` marker is applied to a test function, the ``event_loop`` +fixture will be requested automatically by the test function. ``unused_tcp_port`` ~~~~~~~~~~~~~~~~~~~