mark/expression: documentation/naming tweaks

Make the module a little nicer ahead of possibly exposing it publicly.

Author: bluetech

src/_pytest/mark/expression.py

@@ -16,8 +16,8 @@
 
 - Empty expression evaluates to False.
 - ident evaluates to True or False according to a provided matcher function.
-- or/and/not evaluate according to the usual boolean semantics.
 - ident with parentheses and keyword arguments evaluates to True or False according to a provided matcher function.
+- or/and/not evaluate according to the usual boolean semantics.
 """
 
 from __future__ import annotations
@@ -65,7 +65,7 @@ class Token:
 
 
 class ParseError(Exception):
-    """The expression contains invalid syntax.
+    """The :class:`Expression` contains invalid syntax.
 
     :param column: The column in the line where the error occurred (1-based).
     :param message: A description of the error.
@@ -261,13 +261,36 @@ def all_kwargs(s: Scanner) -> list[ast.keyword]:
     return ret
 
 
-class MatcherCall(Protocol):
+class ExpressionMatcher(Protocol):
+    """A callable which, given an identifier and optional kwargs, should return
+    whether it matches in an :class:`Expression` evaluation.
+
+    Should be prepared to handle arbitrary strings as input.
+
+    If no kwargs are provided, the expression of the form `foo`.
+    If kwargs are provided, the expression is of the form `foo(1, b=True, "s")`.
+
+    If the expression is not supported (e.g. don't want to accept the kwargs
+    syntax variant), should raise :class:`~pytest.UsageError`.
+
+    Example::
+
+        def matcher(name: str, /, **kwargs: str | int | bool | None) -> bool:
+            # Match `cat`.
+            if name == "cat" and not kwargs:
+                return True
+            # Match `dog(barks=True)`.
+            if name == "dog" and kwargs == {"barks": False}:
+                return True
+            return False
+    """
+
     def __call__(self, name: str, /, **kwargs: str | int | bool | None) -> bool: ...
 
 
 @dataclasses.dataclass
 class MatcherNameAdapter:
-    matcher: MatcherCall
+    matcher: ExpressionMatcher
     name: str
 
     def __bool__(self) -> bool:
@@ -280,7 +303,7 @@ def __call__(self, **kwargs: str | int | bool | None) -> bool:
 class MatcherAdapter(Mapping[str, MatcherNameAdapter]):
     """Adapts a matcher function to a locals mapping as required by eval()."""
 
-    def __init__(self, matcher: MatcherCall) -> None:
+    def __init__(self, matcher: ExpressionMatcher) -> None:
         self.matcher = matcher
 
     def __getitem__(self, key: str) -> MatcherNameAdapter:
@@ -309,23 +332,28 @@ def compile(cls, input: str) -> Expression:
         """Compile a match expression.
 
         :param input: The input expression - one line.
+
+        :raises ParseError: If the expression is malformed.
         """
         astexpr = expression(Scanner(input))
-        code: types.CodeType = compile(
+        code = compile(
             astexpr,
             filename="<pytest match expression>",
             mode="eval",
         )
         return Expression(code)
 
-    def evaluate(self, matcher: MatcherCall) -> bool:
+    def evaluate(self, matcher: ExpressionMatcher) -> bool:
         """Evaluate the match expression.
 
         :param matcher:
-            Given an identifier, should return whether it matches or not.
-            Should be prepared to handle arbitrary strings as input.
+            A callback which determines whether an identifier matches or not.
+            See the :class:`ExpressionMatcher` protocol for details and example.
 
         :returns: Whether the expression matches or not.
+
+        :raises UsageError:
+            If the matcher doesn't support the expression. Cannot happen if the
+            matcher supports all expressions.
         """
-        ret: bool = bool(eval(self.code, {"__builtins__": {}}, MatcherAdapter(matcher)))
-        return ret
+        return bool(eval(self.code, {"__builtins__": {}}, MatcherAdapter(matcher)))

testing/test_mark_expression.py

@@ -2,12 +2,12 @@
 
 from _pytest.mark import MarkMatcher
 from _pytest.mark.expression import Expression
-from _pytest.mark.expression import MatcherCall
+from _pytest.mark.expression import ExpressionMatcher
 from _pytest.mark.expression import ParseError
 import pytest
 
 
-def evaluate(input: str, matcher: MatcherCall) -> bool:
+def evaluate(input: str, matcher: ExpressionMatcher) -> bool:
     return Expression.compile(input).evaluate(matcher)