fixtures: provide per-scope fixtures for unblocking database access

Allow the convenience of `db` fixture for all fixture scopes.

Author: m000

pytest_django/fixtures.py

@@ -43,6 +43,10 @@
 __all__ = [
     "django_db_setup",
     "db",
+    "db_class",
+    "db_module",
+    "db_package",
+    "db_session",
     "transactional_db",
     "django_db_reset_sequences",
     "django_db_serialized_rollback",
@@ -159,8 +163,7 @@ def django_db_setup(
                 )
 
 
-@pytest.fixture()
-def _django_db_helper(
+def _base_django_db_helper(
     request: pytest.FixtureRequest,
     django_db_setup: None,
     django_db_blocker: DjangoDbBlocker,
@@ -256,6 +259,14 @@ def tearDownClass(cls) -> None:
         PytestDjangoTestCase.doClassCleanups()
 
 
+# Per-scope db helpers.
+_django_db_helper = pytest.fixture(_base_django_db_helper, scope="function")
+_django_db_helper_class = pytest.fixture(_base_django_db_helper, scope="class")
+_django_db_helper_module = pytest.fixture(_base_django_db_helper, scope="module")
+_django_db_helper_package = pytest.fixture(_base_django_db_helper, scope="package")
+_django_db_helper_session = pytest.fixture(_base_django_db_helper, scope="session")
+
+
 def validate_django_db(marker: pytest.Mark) -> _DjangoDb:
     """Validate the django_db marker.
 
@@ -321,22 +332,53 @@ def _set_suffix_to_test_databases(suffix: str) -> None:
 
 # ############### User visible fixtures ################
 
+_db_fixture_help = (
+"""Require a django test database for use by tests and {}-scoped fixtures.
+
+This database will be setup with the default fixtures and will have
+the transaction management disabled. At the end of the test the outer
+transaction that wraps the test itself will be rolled back to undo any
+changes to the database (in case the backend supports transactions).
+This is more limited than the ``transactional_db`` fixture but
+faster.
+
+If both ``db`` and ``transactional_db`` are requested,
+``transactional_db`` takes precedence.
+""")
 
 @pytest.fixture()
 def db(_django_db_helper: None) -> None:
-    """Require a django test database.
+    # The `_django_db_helper` fixture checks if `db` is requested.
+    pass
+db.__doc__ = _db_fixture_help.format('function')
 
-    This database will be setup with the default fixtures and will have
-    the transaction management disabled. At the end of the test the outer
-    transaction that wraps the test itself will be rolled back to undo any
-    changes to the database (in case the backend supports transactions).
-    This is more limited than the ``transactional_db`` fixture but
-    faster.
 
-    If both ``db`` and ``transactional_db`` are requested,
-    ``transactional_db`` takes precedence.
-    """
+@pytest.fixture(scope="class")
+def db_class(_django_db_helper_class: None) -> None:
+    # The `_django_db_helper` fixture checks if `db` is requested.
+    pass
+db_class.__doc__ = _db_fixture_help.format('class')
+
+
+@pytest.fixture(scope="module")
+def db_module(_django_db_helper_module: None) -> None:
+    # The `_django_db_helper` fixture checks if `db` is requested.
+    pass
+db_module.__doc__ = _db_fixture_help.format('module')
+
+
+@pytest.fixture(scope="package")
+def db_package(_django_db_helper_package: None) -> None:
+    # The `_django_db_helper` fixture checks if `db` is requested.
+    pass
+db_package.__doc__ = _db_fixture_help.format('package')
+
+
+@pytest.fixture(scope="session")
+def db_session(_django_db_helper_session: None) -> None:
     # The `_django_db_helper` fixture checks if `db` is requested.
+    pass
+db_session.__doc__ = _db_fixture_help.format('session')
 
 
 @pytest.fixture()

pytest_django/plugin.py

@@ -20,13 +20,21 @@
 from .django_compat import is_django_unittest
 from .fixtures import (
     _django_db_helper,  # noqa: F401
+    _django_db_helper_class,  # noqa: F401
+    _django_db_helper_module,  # noqa: F401
+    _django_db_helper_package,  # noqa: F401
+    _django_db_helper_session,  # noqa: F401
     _live_server_helper,  # noqa: F401
     admin_client,  # noqa: F401
     admin_user,  # noqa: F401
     async_client,  # noqa: F401
     async_rf,  # noqa: F401
     client,  # noqa: F401
     db,  # noqa: F401
+    db_class,  # noqa: F401
+    db_module,  # noqa: F401
+    db_package,  # noqa: F401
+    db_session,  # noqa: F401
     django_assert_max_num_queries,  # noqa: F401
     django_assert_num_queries,  # noqa: F401
     django_capture_on_commit_callbacks,  # noqa: F401