Revert matcher changes and fix simple issues

Author: Alejandro-FA

CONTRIBUTING.md

@@ -41,8 +41,8 @@ poetry run poe coverage
 
 In an exciting twist, since version 1.6.0, Decoy's tests rely on Decoy itself to test (and more importantly, design) the relationships between Decoy's internal APIs. This means:
 
-- Decoy's unit test suite serves as an end-to-end test of Decoy by virtue of existing (wow, very meta, actually kind of cool).
-- Changes that break a small part of Decoy may result in a large number of test failures, because if Decoy breaks it can't be used to test itself.
+-   Decoy's unit test suite serves as an end-to-end test of Decoy by virtue of existing (wow, very meta, actually kind of cool).
+-   Changes that break a small part of Decoy may result in a large number of test failures, because if Decoy breaks it can't be used to test itself.
 
 If you find yourself in a situation where Decoy's test suite has blown up, **concentrate on getting the test suites that don't use Decoy to pass**. From there, lean on the type-checker to guide you to any components that aren't properly hooked up. Decoy also has a end-to-end smoke test suite (`tests/test_decoy.py`) that can be helpful in getting things back to green.
 

decoy/matchers.py

@@ -28,10 +28,8 @@ def test_logger_called(decoy: Decoy):
 """
 
 from abc import ABC, abstractmethod
-from re import compile as compile_re, Pattern
-from typing import cast, TypeVar, Generic, Any, override, overload
-from collections.abc import Iterable, Mapping
-from warnings import deprecated
+from re import compile as compile_re
+from typing import cast, overload, Any, Generic, List, Mapping, Optional, Pattern, Type, TypeVar
 
 
 __all__ = [
@@ -47,9 +45,6 @@ def test_logger_called(decoy: Decoy):
 ]
 
 
-MatchT = TypeVar("MatchT", default=Any)
-
-
 class _AnythingOrNone:
     def __eq__(self, target: object) -> bool:
         return True
@@ -59,7 +54,7 @@ def __repr__(self) -> str:
         return "<AnythingOrNone>"
 
 
-def AnythingOrNone() -> MatchT:  # type: ignore[type-var]
+def AnythingOrNone() -> Any:
     """Match anything including None.
 
     !!! example
@@ -68,7 +63,7 @@ def AnythingOrNone() -> MatchT:  # type: ignore[type-var]
         assert None == AnythingOrNone()
         ```
     """
-    return cast(MatchT, _AnythingOrNone())
+    return _AnythingOrNone()
 
 
 class _Anything:
@@ -81,7 +76,7 @@ def __repr__(self) -> str:
         return "<Anything>"
 
 
-def Anything() -> MatchT:  # type: ignore[type-var]
+def Anything() -> Any:
     """Match anything except None.
 
     !!! example
@@ -90,17 +85,17 @@ def Anything() -> MatchT:  # type: ignore[type-var]
         assert None != Anything()
         ```
     """
-    return cast(MatchT, _Anything())
+    return _Anything()
 
 
 class _IsA:
-    _match_type: type[object]
-    _attributes: Mapping[str, object] | None
+    _match_type: type
+    _attributes: Optional[Mapping[str, Any]]
 
     def __init__(
         self,
         match_type: type[object],
-        attributes: Mapping[str, object] | None = None,
+        attributes: Optional[Mapping[str, Any]] = None,
     ) -> None:
         """Initialize the matcher with a type and optional attributes."""
         self._match_type = match_type
@@ -124,8 +119,8 @@ def __repr__(self) -> str:
 
 
 def IsA(
-    match_type: type[MatchT], attributes: Mapping[str, object] | None = None
-) -> MatchT:
+    match_type: type, attributes: Optional[Mapping[str, Any]] = None
+) -> Any:
     """Match anything that satisfies the passed in type.
 
     Arguments:
@@ -146,7 +141,7 @@ class HelloWorld:
         assert HelloWorld() == IsA(HelloWorld, {"hello": "world"})
         ```
     """
-    return cast(MatchT, _IsA(match_type, attributes))
+    return _IsA(match_type, attributes)
 
 
 class _IsNot:
@@ -165,7 +160,7 @@ def __repr__(self) -> str:
         return f"<IsNot {self._reject_value!r}>"
 
 
-def IsNot(value: MatchT) -> MatchT:
+def IsNot(value: object) -> Any:
     """Match anything that isn't the passed in value.
 
     Arguments:
@@ -178,13 +173,13 @@ def IsNot(value: MatchT) -> MatchT:
         assert 1 != IsNot(1)
         ```
     """
-    return cast(MatchT, _IsNot(value))
+    return _IsNot(value)
 
 
 class _HasAttributes:
-    _attributes: Mapping[str, object]
+    _attributes: Mapping[str, Any]
 
-    def __init__(self, attributes: Mapping[str, object]) -> None:
+    def __init__(self, attributes: Mapping[str, Any]) -> None:
         self._attributes = attributes
 
     def __eq__(self, target: object) -> bool:
@@ -203,7 +198,7 @@ def __repr__(self) -> str:
         return f"<HasAttributes {self._attributes!r}>"
 
 
-def HasAttributes(attributes: Mapping[str, object]) -> MatchT:  # type: ignore[type-var]
+def HasAttributes(attributes: Mapping[str, Any]) -> Any:
     """Match anything with the passed in attributes.
 
     Arguments:
@@ -219,25 +214,23 @@ class HelloWorld:
         assert HelloWorld() == matchers.HasAttributes({"hello": "world"})
         ```
     """
-    return cast(MatchT, _HasAttributes(attributes))
+    return _HasAttributes(attributes)
 
 
 class _DictMatching:
-    _values: Mapping[str, object]
+    _values: Mapping[str, Any]
 
-    def __init__(self, values: Mapping[str, object]) -> None:
+    def __init__(self, values: Mapping[str, Any]) -> None:
         self._values = values
 
     def __eq__(self, target: object) -> bool:
         """Return true if target matches all given keys/values."""
-        if not isinstance(target, Mapping):
-            return False
         is_match = True
 
         for key, value in self._values.items():
             if is_match:
                 try:
-                    is_match = key in target and target[key] == value
+                    is_match = key in target and target[key] == value # type: ignore[index,operator]
                 except TypeError:
                     is_match = False
 
@@ -248,7 +241,7 @@ def __repr__(self) -> str:
         return f"<DictMatching {self._values!r}>"
 
 
-def DictMatching(values: Mapping[str, MatchT]) -> Mapping[str, MatchT]:
+def DictMatching(values: Mapping[str, Any]) -> Any:
     """Match any dictionary with the passed in keys / values.
 
     Arguments:
@@ -260,18 +253,18 @@ def DictMatching(values: Mapping[str, MatchT]) -> Mapping[str, MatchT]:
         assert value == matchers.DictMatching({"hello": "world"})
         ```
     """
-    return cast(Mapping[str, MatchT], _DictMatching(values))
+    return _DictMatching(values)
 
 
 class _ListMatching:
-    _values: Iterable[object]
+    _values: List[Any]
 
-    def __init__(self, values: Iterable[object]) -> None:
+    def __init__(self, values: List[Any]) -> None:
         self._values = values
 
     def __eq__(self, target: object) -> bool:
         """Return true if target matches all given values."""
-        if not isinstance(target, Iterable):
+        if not hasattr(target, "__iter__"):
             return False
 
         return all(
@@ -283,7 +276,7 @@ def __repr__(self) -> str:
         return f"<ListMatching {self._values!r}>"
 
 
-def ListMatching(values: list[MatchT]) -> list[MatchT]:
+def ListMatching(values: List[Any]) -> Any:
     """Match any list with the passed in values.
 
     Arguments:
@@ -295,7 +288,7 @@ def ListMatching(values: list[MatchT]) -> list[MatchT]:
         assert value == matchers.ListMatching([1, 2])
         ```
     """
-    return cast(list[MatchT], _ListMatching(values))
+    return _ListMatching(values)
 
 
 class _StringMatching:
@@ -330,10 +323,10 @@ def StringMatching(match: str) -> str:
 
 
 class _ErrorMatching:
-    _error_type: type[BaseException]
-    _string_matcher: _StringMatching | None
+    _error_type: Type[BaseException]
+    _string_matcher: Optional[_StringMatching]
 
-    def __init__(self, error: type[BaseException], match: str | None = None) -> None:
+    def __init__(self, error: Type[BaseException], match: Optional[str] = None) -> None:
         """Initialize with the Exception type and optional message matcher."""
         self._error_type = error
         self._string_matcher = _StringMatching(match) if match is not None else None
@@ -359,7 +352,7 @@ def __repr__(self) -> str:
 ErrorT = TypeVar("ErrorT", bound=BaseException)
 
 
-def ErrorMatching(error: type[ErrorT], match: str | None = None) -> ErrorT:
+def ErrorMatching(error: Type[ErrorT], match: Optional[str] = None) -> ErrorT:
     """Match any error matching an Exception type and optional message matcher.
 
     Arguments:
@@ -426,24 +419,20 @@ def __init__(self, match_type: type[CapturedT]) -> None:
         self._values = []
         self._match_type = match_type
 
-    @override
     def __eq__(self, target: object) -> bool:
         if isinstance(target, self._match_type):
             self._values.append(target)
             return True
         return False
 
-    @override
     def __repr__(self) -> str:
         """Return a string representation of the matcher."""
         return "<Captor>"
 
-    @override
     def capture(self) -> CapturedT:
         return cast(CapturedT, self)
 
     @property
-    @override
     def value(self) -> CapturedT:
         if len(self._values) == 0:
             raise AssertionError("No value captured by captor.")
@@ -454,19 +443,16 @@ def values(self) -> list[CapturedT]:
         return self._values
 
 
+MatchT = TypeVar("MatchT")
+
+
 @overload
 def Captor() -> Any: ...
 @overload
 def Captor(match_type: type[MatchT]) -> MatchT: ...
-@deprecated(
-    "Use ArgumentCaptor() instead, and then call capture() to pass the matcher as an argument."
-)
 def Captor(match_type: type[object] = object) -> object:
     """Match anything, capturing its value for further assertions.
 
-    !!! warning Deprecated
-        This matcher is deprecated. Use [decoy.matchers.ArgumentCaptor][] instead.
-
     The last captured value will be set to `captor.value`. All captured
     values will be placed in the `captor.values` list, which can be
     helpful if a captor needs to be triggered multiple times.

docs/usage/matchers.md

@@ -82,14 +82,12 @@ def test_event_listener(decoy: Decoy):
     assert subject.has_heard_event is True
 ```
 
-!!! tip
-
-    If you want to only capture values of a specific type, or you would like to have stricter type checking in your tests, consider passing a type to [decoy.matchers.argument_captor][] (e.g. `argument_captor(match_type=str)`).
-
 This is a pretty verbose way of writing a test, so in general, you may want to approach using `matchers.argument_captor` as a form of potential code smell / test pain. There are often better ways to structure your code for these sorts of interactions that don't involve private functions.
 
 For further reading on when (or rather, when not) to use argument captors, check out [testdouble's documentation on its argument captor matcher](https://github.com/testdouble/testdouble.js/blob/main/docs/6-verifying-invocations.md#tdmatcherscaptor).
 
+If you would like to have stricter type checking in your tests, consider passing a type to [decoy.matchers.argument_captor][] (e.g. `argument_captor(match_type=str)`). By doing so, captured values will be cast to the specified type.
+
 ## Writing custom matchers
 
 You can write your own matcher class and use it wherever you would use a built-in matcher. All you need to do is define a class with an `__eq__` method:

tests/test_matchers.py

@@ -3,9 +3,8 @@
 import pytest
 from collections import namedtuple
 from decoy import Decoy, matchers
-from typing import NamedTuple
+from typing import Any, List, NamedTuple
 from .fixtures import SomeClass
-import warnings
 
 
 class _HelloClass(NamedTuple):
@@ -102,8 +101,9 @@ def test_dict_matching_matcher() -> None:
     )
 
     assert {"hello": "world"} != matchers.DictMatching({"goodbye": "so long"})
-    assert 1 != matchers.DictMatching({"hello": "world"})  # type: ignore[comparison-overlap]
-    assert [] != matchers.DictMatching({"hello": "world"})  # type: ignore[comparison-overlap]
+    assert 1 != matchers.DictMatching({"hello": "world"})
+    assert False != matchers.DictMatching({"hello": "world"})  # noqa: E712
+    assert [] != matchers.DictMatching({"hello": "world"})
 
 
 def test_list_matching_matcher() -> None:
@@ -124,7 +124,7 @@ def test_list_matching_matcher() -> None:
         [{"yoo": "mann"}]
     )
 
-    assert 1 != matchers.ListMatching([1])  # type: ignore[comparison-overlap]
+    assert 1 != matchers.ListMatching([1])
 
     assert str(matchers.ListMatching([1])) == "<ListMatching [1]>"
 
@@ -145,18 +145,8 @@ def test_error_matching_matcher() -> None:
 
 def test_captor_matcher() -> None:
     """It should have a captor matcher that captures the compared value."""
-    with warnings.catch_warnings():
-        warnings.filterwarnings("ignore", category=DeprecationWarning)
-        captor = matchers.Captor()
-    comparisons: list[object] = [
-        1,
-        False,
-        None,
-        {},
-        [],
-        ("hello", "world"),
-        SomeClass(),
-    ]
+    captor = matchers.Captor()
+    comparisons: List[Any] = [1, False, None, {}, [], ("hello", "world"), SomeClass()]
 
     for i, compare in enumerate(comparisons):
         assert compare == captor
@@ -207,9 +197,7 @@ def test_argument_captor_matcher_with_match_type() -> None:
 
 def test_captor_matcher_raises_if_no_value() -> None:
     """The captor matcher should raise an assertion error if no value."""
-    with warnings.catch_warnings():
-        warnings.filterwarnings("ignore", category=DeprecationWarning)
-        captor = matchers.Captor()
+    captor = matchers.Captor()
 
     with pytest.raises(AssertionError, match="No value captured"):
         captor.value  # noqa: B018