Make ScopeName public to enable downstream type checking (#14325)

Closes #14137

Author: JuliaKnaak

AUTHORS

@@ -57,6 +57,7 @@ Aron Curzon
 Arthur Richard
 Ashish Kurmi
 Ashley Whetter
+Ava Birtwistle
 Aviral Verma
 Aviv Palivoda
 Babak Keyvani
@@ -239,6 +240,7 @@ Joseph Hunkeler
 Joseph Sawaya
 Josh Karpel
 Joshua Bronson
+Julia Knaak
 Julian Valentin
 Junhao Liao
 Jurko Gospodnetić
@@ -300,6 +302,7 @@ Martijn Faassen
 Martin Altmayer
 Martin K. Scherer
 Martin Prusse
+Mateya Berezowsky
 Mathieu Clabaut
 Matt Bachmann
 Matt Duck

changelog/14137.improvement.rst

@@ -0,0 +1 @@
+`pytest.ScopeName` is now public to allow using it in function signatures.

doc/en/conf.py

@@ -110,7 +110,7 @@
     ("py:class", "_pytest.runner.TResult"),
     ("py:obj", "_pytest.fixtures.FixtureValue"),
     ("py:obj", "_pytest.stash.T"),
-    ("py:class", "_ScopeName"),
+    ("py:class", "ScopeName"),
     ("py:class", "BaseExcT_1"),
     ("py:class", "ExcT_1"),
 ]

src/_pytest/fixtures.py

@@ -65,9 +65,9 @@
 from _pytest.outcomes import TEST_OUTCOME
 from _pytest.pathlib import absolutepath
 from _pytest.pathlib import bestrelpath
-from _pytest.scope import _ScopeName
 from _pytest.scope import HIGH_SCOPES
 from _pytest.scope import Scope
+from _pytest.scope import ScopeName
 from _pytest.warning_types import PytestWarning
 
 
@@ -401,7 +401,7 @@ def _scope(self) -> Scope:
         raise NotImplementedError()
 
     @property
-    def scope(self) -> _ScopeName:
+    def scope(self) -> ScopeName:
         """Scope string, one of "function", "class", "module", "package", "session"."""
         return self._scope.value
 
@@ -942,10 +942,10 @@ def _teardown_yield_fixture(fixturefunc, it) -> None:
 
 
 def _eval_scope_callable(
-    scope_callable: Callable[[str, Config], _ScopeName],
+    scope_callable: Callable[[str, Config], ScopeName],
     fixture_name: str,
     config: Config,
-) -> _ScopeName:
+) -> ScopeName:
     try:
         # Type ignored because there is no typing mechanism to specify
         # keyword arguments, currently.
@@ -977,7 +977,7 @@ def __init__(
         baseid: str | None,
         argname: str,
         func: _FixtureFunc[FixtureValue],
-        scope: Scope | _ScopeName | Callable[[str, Config], _ScopeName] | None,
+        scope: Scope | ScopeName | Callable[[str, Config], ScopeName] | None,
         params: Sequence[object] | None,
         ids: tuple[object | None, ...] | Callable[[Any], object | None] | None = None,
         *,
@@ -1034,7 +1034,7 @@ def __init__(
         self._autouse = _autouse
 
     @property
-    def scope(self) -> _ScopeName:
+    def scope(self) -> ScopeName:
         """Scope string, one of "function", "class", "module", "package", "session"."""
         return self._scope.value
 
@@ -1228,7 +1228,7 @@ def pytest_fixture_setup(
 @final
 @dataclasses.dataclass(frozen=True)
 class FixtureFunctionMarker:
-    scope: _ScopeName | Callable[[str, Config], _ScopeName]
+    scope: ScopeName | Callable[[str, Config], ScopeName]
     params: tuple[object, ...] | None
     autouse: bool = False
     ids: tuple[object | None, ...] | Callable[[Any], object | None] | None = None
@@ -1322,7 +1322,7 @@ def _get_wrapped_function(self) -> Callable[..., Any]:
 def fixture(
     fixture_function: Callable[..., object],
     *,
-    scope: _ScopeName | Callable[[str, Config], _ScopeName] = ...,
+    scope: ScopeName | Callable[[str, Config], ScopeName] = ...,
     params: Iterable[object] | None = ...,
     autouse: bool = ...,
     ids: Sequence[object | None] | Callable[[Any], object | None] | None = ...,
@@ -1334,7 +1334,7 @@ def fixture(
 def fixture(
     fixture_function: None = ...,
     *,
-    scope: _ScopeName | Callable[[str, Config], _ScopeName] = ...,
+    scope: ScopeName | Callable[[str, Config], ScopeName] = ...,
     params: Iterable[object] | None = ...,
     autouse: bool = ...,
     ids: Sequence[object | None] | Callable[[Any], object | None] | None = ...,
@@ -1345,7 +1345,7 @@ def fixture(
 def fixture(
     fixture_function: FixtureFunction | None = None,
     *,
-    scope: _ScopeName | Callable[[str, Config], _ScopeName] = "function",
+    scope: ScopeName | Callable[[str, Config], ScopeName] = "function",
     params: Iterable[object] | None = None,
     autouse: bool = False,
     ids: Sequence[object | None] | Callable[[Any], object | None] | None = None,
@@ -1799,7 +1799,7 @@ def _register_fixture(
         name: str,
         func: _FixtureFunc[object],
         nodeid: str | None,
-        scope: Scope | _ScopeName | Callable[[str, Config], _ScopeName] = "function",
+        scope: Scope | ScopeName | Callable[[str, Config], ScopeName] = "function",
         params: Sequence[object] | None = None,
         ids: tuple[object | None, ...] | Callable[[Any], object | None] | None = None,
         autouse: bool = False,

src/_pytest/mark/structures.py

@@ -29,7 +29,7 @@
 from _pytest.deprecated import PARAMETRIZE_NON_COLLECTION_ITERABLE
 from _pytest.outcomes import fail
 from _pytest.raises import AbstractRaises
-from _pytest.scope import _ScopeName
+from _pytest.scope import ScopeName
 from _pytest.warning_types import PytestUnknownMarkWarning
 
 
@@ -535,7 +535,7 @@ def __call__(
             ids: Iterable[None | str | float | int | bool]
             | Callable[[Any], object | None]
             | None = ...,
-            scope: _ScopeName | None = ...,
+            scope: ScopeName | None = ...,
         ) -> MarkDecorator: ...
 
         @overload
@@ -552,7 +552,7 @@ def __call__(
             ids: Iterable[None | str | float | int | bool]
             | Callable[[Any], object | None]
             | None = ...,
-            scope: _ScopeName | None = ...,
+            scope: ScopeName | None = ...,
         ) -> MarkDecorator: ...
 
     class _UsefixturesMarkDecorator(MarkDecorator):

src/_pytest/python.py

@@ -71,8 +71,8 @@
 from _pytest.pathlib import import_path
 from _pytest.pathlib import ImportPathMismatchError
 from _pytest.pathlib import scandir
-from _pytest.scope import _ScopeName
 from _pytest.scope import Scope
+from _pytest.scope import ScopeName
 from _pytest.stash import StashKey
 from _pytest.warning_types import PytestCollectionWarning
 from _pytest.warning_types import PytestReturnNotNoneWarning
@@ -1209,7 +1209,7 @@ def parametrize(
         argvalues: Iterable[ParameterSet | Sequence[object] | object],
         indirect: bool | Sequence[str] = False,
         ids: Iterable[object | None] | Callable[[Any], object | None] | None = None,
-        scope: _ScopeName | None = None,
+        scope: ScopeName | None = None,
         *,
         _param_mark: Mark | None = None,
     ) -> None:

src/_pytest/scope.py

@@ -15,7 +15,7 @@
 from typing import Literal
 
 
-_ScopeName = Literal["session", "package", "module", "class", "function"]
+ScopeName = Literal["session", "package", "module", "class", "function"]
 
 
 @total_ordering
@@ -60,7 +60,7 @@ def __lt__(self, other: Scope) -> bool:
 
     @classmethod
     def from_user(
-        cls, scope_name: _ScopeName, descr: str, where: str | None = None
+        cls, scope_name: ScopeName, descr: str, where: str | None = None
     ) -> Scope:
         """
         Given a scope name from the user, return the equivalent Scope enum. Should be used

src/pytest/__init__.py

@@ -69,6 +69,7 @@
 from _pytest.reports import CollectReport
 from _pytest.reports import TestReport
 from _pytest.runner import CallInfo
+from _pytest.scope import ScopeName
 from _pytest.stash import Stash
 from _pytest.stash import StashKey
 from _pytest.subtests import SubtestReport
@@ -145,6 +146,7 @@
     "RaisesGroup",
     "RecordedHookCall",
     "RunResult",
+    "ScopeName",
     "Session",
     "Stash",
     "StashKey",

testing/typing_checks.py

@@ -14,6 +14,7 @@
 
 import pytest
 from pytest import MonkeyPatch
+from pytest import ScopeName
 from pytest import TestReport
 
 
@@ -65,3 +66,10 @@ def check_testreport_attributes(report: TestReport) -> None:
 @pytest.mark.parametrize("x", iter(range(10)))  # type: ignore[deprecated]
 def test_it(x: int) -> None:
     pass
+
+
+# Issue #14137.
+def check_scope_typing() -> None:
+
+    custom_scope: ScopeName = "function"
+    assert_type(custom_scope, ScopeName)