mark: export pytest.MarkGenerator for typing purposes

The type cannot be constructed directly, but is exported for use in type
annotations, since it is reachable through existing public API.

Author: bluetech

changelog/7469.deprecation.rst

@@ -2,5 +2,6 @@ Directly constructing the following classes is now deprecated:
 
 - ``_pytest.mark.structures.Mark``
 - ``_pytest.mark.structures.MarkDecorator``
+- ``_pytest.mark.structures.MarkGenerator``
 
 These have always been considered private, but now issue a deprecation warning, which may become a hard error in pytest 7.0.0.

changelog/7469.feature.rst

@@ -4,6 +4,7 @@ The newly-exported types are:
 
 - ``pytest.Mark`` for :class:`marks <pytest.Mark>`.
 - ``pytest.MarkDecorator`` for :class:`mark decorators <pytest.MarkDecorator>`.
+- ``pytest.MarkGenerator`` for the :class:`pytest.mark <pytest.MarkGenerator>` singleton.
 
 Constructing them directly is not supported; they are only meant for use in type annotations.
 Doing so will emit a deprecation warning, and may become a hard-error in pytest 7.0.

doc/en/reference.rst

@@ -856,7 +856,7 @@ MarkDecorator
 MarkGenerator
 ~~~~~~~~~~~~~
 
-.. autoclass:: _pytest.mark.MarkGenerator
+.. autoclass:: pytest.MarkGenerator()
     :members:
 
 

src/_pytest/mark/structures.py

@@ -488,9 +488,6 @@ def test_function():
     applies a 'slowtest' :class:`Mark` on ``test_function``.
     """
 
-    _config: Optional[Config] = None
-    _markers: Set[str] = set()
-
     # See TYPE_CHECKING above.
     if TYPE_CHECKING:
         skip: _SkipMarkDecorator
@@ -500,7 +497,13 @@ def test_function():
         usefixtures: _UsefixturesMarkDecorator
         filterwarnings: _FilterwarningsMarkDecorator
 
+    def __init__(self, *, _ispytest: bool = False) -> None:
+        check_ispytest(_ispytest)
+        self._config: Optional[Config] = None
+        self._markers: Set[str] = set()
+
     def __getattr__(self, name: str) -> MarkDecorator:
+        """Generate a new :class:`MarkDecorator` with the given name."""
         if name[0] == "_":
             raise AttributeError("Marker name must NOT start with underscore")
 
@@ -541,7 +544,7 @@ def __getattr__(self, name: str) -> MarkDecorator:
         return MarkDecorator(Mark(name, (), {}, _ispytest=True), _ispytest=True)
 
 
-MARK_GEN = MarkGenerator()
+MARK_GEN = MarkGenerator(_ispytest=True)
 
 
 @final

src/pytest/__init__.py

@@ -24,6 +24,7 @@
 from _pytest.mark import Mark
 from _pytest.mark import MARK_GEN as mark
 from _pytest.mark import MarkDecorator
+from _pytest.mark import MarkGenerator
 from _pytest.mark import param
 from _pytest.monkeypatch import MonkeyPatch
 from _pytest.nodes import Collector
@@ -93,6 +94,7 @@
     "mark",
     "Mark",
     "MarkDecorator",
+    "MarkGenerator",
     "Module",
     "MonkeyPatch",
     "Package",

testing/test_mark.py

@@ -21,7 +21,7 @@ def test_pytest_exists_in_namespace_all(self, attr: str, modulename: str) -> Non
         assert attr in module.__all__  # type: ignore
 
     def test_pytest_mark_notcallable(self) -> None:
-        mark = MarkGenerator()
+        mark = MarkGenerator(_ispytest=True)
         with pytest.raises(TypeError):
             mark()  # type: ignore[operator]
 
@@ -40,7 +40,7 @@ class SomeClass:
         assert pytest.mark.foo.with_args(SomeClass) is not SomeClass  # type: ignore[comparison-overlap]
 
     def test_pytest_mark_name_starts_with_underscore(self) -> None:
-        mark = MarkGenerator()
+        mark = MarkGenerator(_ispytest=True)
         with pytest.raises(AttributeError):
             mark._some_name