[feat] Deprecates the optional scope keyword argument of asyncio markers. Users are encouraged to use the loop_scope keyword argument. The loop_scope kwarg does exactly the same, though its naming is consistent with the loop_scope kwarg of pytest_asyncio.fixture.

Signed-off-by: Michael Seifert <m.seifert@digitalernachschub.de>

Author: seifertm

docs/source/concepts_module_scope_example.py

@@ -5,13 +5,13 @@
 loop: asyncio.AbstractEventLoop
 
 
-@pytest.mark.asyncio(scope="module")
+@pytest.mark.asyncio(loop_scope="module")
 async def test_remember_loop():
     global loop
     loop = asyncio.get_running_loop()
 
 
-@pytest.mark.asyncio(scope="module")
+@pytest.mark.asyncio(loop_scope="module")
 async def test_runs_in_a_loop():
     global loop
     assert asyncio.get_running_loop() is loop

docs/source/how-to-guides/class_scoped_loop_example.py

@@ -3,7 +3,7 @@
 import pytest
 
 
-@pytest.mark.asyncio(scope="class")
+@pytest.mark.asyncio(loop_scope="class")
 class TestInOneEventLoopPerClass:
     loop: asyncio.AbstractEventLoop
 

docs/source/how-to-guides/module_scoped_loop_example.py

@@ -2,7 +2,7 @@
 
 import pytest
 
-pytestmark = pytest.mark.asyncio(scope="module")
+pytestmark = pytest.mark.asyncio(loop_scope="module")
 
 loop: asyncio.AbstractEventLoop
 

docs/source/how-to-guides/package_scoped_loop_example.py

@@ -1,3 +1,3 @@
 import pytest
 
-pytestmark = pytest.mark.asyncio(scope="package")
+pytestmark = pytest.mark.asyncio(loop_scope="package")

docs/source/how-to-guides/run_class_tests_in_same_loop.rst

@@ -1,7 +1,7 @@
 ======================================================
 How to run all tests in a class in the same event loop
 ======================================================
-All tests can be run inside the same event loop by marking them with ``pytest.mark.asyncio(scope="class")``.
+All tests can be run inside the same event loop by marking them with ``pytest.mark.asyncio(loop_scope="class")``.
 This is easily achieved by using the *asyncio* marker as a class decorator.
 
 .. include:: class_scoped_loop_example.py

docs/source/how-to-guides/run_module_tests_in_same_loop.rst

@@ -1,7 +1,7 @@
 =======================================================
 How to run all tests in a module in the same event loop
 =======================================================
-All tests can be run inside the same event loop by marking them with ``pytest.mark.asyncio(scope="module")``.
+All tests can be run inside the same event loop by marking them with ``pytest.mark.asyncio(loop_scope="module")``.
 This is easily achieved by adding a `pytestmark` statement to your module.
 
 .. include:: module_scoped_loop_example.py

docs/source/how-to-guides/run_package_tests_in_same_loop.rst

@@ -1,7 +1,7 @@
 ========================================================
 How to run all tests in a package in the same event loop
 ========================================================
-All tests can be run inside the same event loop by marking them with ``pytest.mark.asyncio(scope="package")``.
+All tests can be run inside the same event loop by marking them with ``pytest.mark.asyncio(loop_scope="package")``.
 Add the following code to the ``__init__.py`` of the test package:
 
 .. include:: package_scoped_loop_example.py

docs/source/how-to-guides/run_session_tests_in_same_loop.rst

@@ -1,7 +1,7 @@
 ==========================================================
 How to run all tests in the session in the same event loop
 ==========================================================
-All tests can be run inside the same event loop by marking them with ``pytest.mark.asyncio(scope="session")``.
+All tests can be run inside the same event loop by marking them with ``pytest.mark.asyncio(loop_scope="session")``.
 The easiest way to mark all tests is via a ``pytest_collection_modifyitems`` hook in the ``conftest.py`` at the root folder of your test suite.
 
 .. include:: session_scoped_loop_example.py

docs/source/how-to-guides/session_scoped_loop_example.py

@@ -5,6 +5,6 @@
 
 def pytest_collection_modifyitems(items):
     pytest_asyncio_tests = (item for item in items if is_async_test(item))
-    session_scope_marker = pytest.mark.asyncio(scope="session")
+    session_scope_marker = pytest.mark.asyncio(loop_scope="session")
     for async_test in pytest_asyncio_tests:
         async_test.add_marker(session_scope_marker, append=False)

docs/source/reference/changelog.rst

@@ -2,6 +2,10 @@
 Changelog
 =========
 
+0.24.0 (UNRELEASED)
+===================
+- Deprecates the optional `scope` keyword argument of asyncio markers. Users are encouraged to use the `loop_scope` keyword argument. The `loop_scope` kwarg does exactly the same, though its naming is consistent with the `loop_scope` kwarg of ``pytest_asyncio.fixture``.
+
 0.23.8 (UNRELEASED)
 ===================
 - Fixes a bug that caused duplicate markers in async tests `#813 <https://github.com/pytest-dev/pytest-asyncio/issues/813>`_