fixing mypy's Matcher[Never]

closes: #266 #264

Author: bukzor

pyproject.toml

@@ -171,3 +171,6 @@ known_third_party = ["hypothesis", "pytest", "setuptools", "six"]
     filename = "CHANGELOG.rst"
     directory = "changelog.d"
     issue_format = "`#{issue} <https://github.com/hamcrest/PyHamcrest/issues/{issue}>`_"
+
+[dependency-groups]
+dev = [ "PyHamcrest[dev]" ]

src/hamcrest/core/core/allof.py

@@ -1,4 +1,4 @@
-from typing import Optional, TypeVar, Union
+from typing import Optional, TypeVar, Union, overload
 
 from hamcrest.core.base_matcher import BaseMatcher
 from hamcrest.core.description import Description
@@ -42,6 +42,12 @@ def describe_to(self, description: Description) -> None:
         description.append_list("(", " and ", ")", self.matchers)
 
 
+@overload
+def all_of(*items: Matcher[T]) -> Matcher[T]: ...
+@overload
+def all_of(*items: T) -> Matcher[T]: ...
+
+
 def all_of(*items: Union[Matcher[T], T]) -> Matcher[T]:
     """Matches if all of the given matchers evaluate to ``True``.
 

src/hamcrest/core/core/anyof.py

@@ -1,4 +1,4 @@
-from typing import TypeVar, Union
+from typing import TypeVar, Union, overload
 
 from hamcrest.core.base_matcher import BaseMatcher
 from hamcrest.core.description import Description
@@ -26,6 +26,12 @@ def describe_to(self, description: Description) -> None:
         description.append_list("(", " or ", ")", self.matchers)
 
 
+@overload
+def any_of(*items: Matcher[T]) -> Matcher[T]: ...
+@overload
+def any_of(*items: T) -> Matcher[T]: ...
+
+
 def any_of(*items: Union[Matcher[T], T]) -> Matcher[T]:
     """Matches if any of the given matchers evaluate to ``True``.
 

src/hamcrest/library/collection/isdict_containingentries.py

@@ -1,4 +1,4 @@
-from typing import Any, Hashable, Mapping, Optional, TypeVar, Union, overload
+from typing import Any, Hashable, Mapping, Optional, TypeVar, Union, cast, overload
 
 from hamcrest.core.base_matcher import BaseMatcher
 from hamcrest.core.description import Description
@@ -73,20 +73,26 @@ def describe_to(self, description: Description) -> None:
 
 # Keyword argument form
 @overload
-def has_entries(**keys_valuematchers: Union[Matcher[V], V]) -> Matcher[Mapping[str, V]]: ...
+def has_entries(**keys_valuematchers: Matcher[V]) -> Matcher[Mapping[str, V]]: ...
+@overload
+def has_entries(**keys_valuematchers: V) -> Matcher[Mapping[str, V]]: ...
 
 
 # Key to matcher dict form
 @overload
-def has_entries(keys_valuematchers: Mapping[K, Union[Matcher[V], V]]) -> Matcher[Mapping[K, V]]: ...
+def has_entries(keys_valuematchers: Mapping[K, Matcher[V]], /) -> Matcher[Mapping[K, V]]: ...
+@overload
+def has_entries(keys_valuematchers: Mapping[K, V], /) -> Matcher[Mapping[K, V]]: ...
 
 
 # Alternating key/matcher form
 @overload
 def has_entries(*keys_valuematchers: Any) -> Matcher[Mapping[Any, Any]]: ...
 
 
-def has_entries(*keys_valuematchers, **kv_args):
+def has_entries(
+    *keys_valuematchers: Mapping[K, Union[Matcher[V], V]], **kv_args: Union[Matcher[V], V]
+) -> Matcher[Mapping[K, V]]:
     """Matches if dictionary contains entries satisfying a dictionary of keys
     and corresponding value matchers.
 
@@ -132,11 +138,13 @@ def has_entries(*keys_valuematchers, **kv_args):
         has_entries('foo', 1, 'bar', 2)
 
     """
+    base_dict: dict[K, Matcher[V]] = {}
+    key: K
+    value: Union[Matcher[V], V]
     if len(keys_valuematchers) == 1:
         try:
-            base_dict = keys_valuematchers[0].copy()
-            for key in base_dict:
-                base_dict[key] = wrap_matcher(base_dict[key])
+            for key, value in keys_valuematchers[0].items():
+                base_dict[key] = wrap_matcher(value)
         except AttributeError:
             raise ValueError(
                 "single-argument calls to has_entries must pass a dict as the argument"
@@ -146,11 +154,12 @@ def has_entries(*keys_valuematchers, **kv_args):
             raise ValueError("has_entries requires key-value pairs")
         base_dict = {}
         for index in range(int(len(keys_valuematchers) / 2)):
-            base_dict[keys_valuematchers[2 * index]] = wrap_matcher(
-                keys_valuematchers[2 * index + 1]
-            )
+            key = cast(K, keys_valuematchers[2 * index])
+            value = cast(V, keys_valuematchers[2 * index + 1])
+            base_dict[key] = wrap_matcher(value)
 
-    for key, value in kv_args.items():
+    for key_name, value in kv_args.items():
+        key = cast(K, key_name)
         base_dict[key] = wrap_matcher(value)
 
     return IsDictContainingEntries(base_dict)

src/hamcrest/library/collection/issequence_containing.py

@@ -1,4 +1,4 @@
-from typing import Sequence, TypeVar, Union, cast
+from typing import Sequence, TypeVar, Union, cast, overload
 
 from hamcrest.core.base_matcher import BaseMatcher
 from hamcrest.core.core.allof import all_of
@@ -54,6 +54,12 @@ def describe_to(self, description: Description) -> None:
         self.matcher.describe_to(description)
 
 
+@overload
+def has_item(match: Matcher[T]) -> Matcher[Sequence[T]]: ...
+@overload
+def has_item(match: T) -> Matcher[Sequence[T]]: ...
+
+
 def has_item(match: Union[Matcher[T], T]) -> Matcher[Sequence[T]]:
     """Matches if any element of sequence satisfies a given matcher.
 
@@ -72,6 +78,12 @@ def has_item(match: Union[Matcher[T], T]) -> Matcher[Sequence[T]]:
     return IsSequenceContaining(wrap_matcher(match))
 
 
+@overload
+def has_items(*items: Matcher[T]) -> Matcher[Sequence[T]]: ...
+@overload
+def has_items(*items: T) -> Matcher[Sequence[T]]: ...
+
+
 def has_items(*items: Union[Matcher[T], T]) -> Matcher[Sequence[T]]:
     """Matches if all of the given matchers are satisfied by any elements of
     the sequence.

src/hamcrest/library/collection/issequence_containinginanyorder.py

@@ -1,4 +1,4 @@
-from typing import MutableSequence, Optional, Sequence, TypeVar, Union, cast
+from typing import Generic, MutableSequence, Optional, Sequence, TypeVar, Union, cast, overload
 
 from hamcrest.core.base_matcher import BaseMatcher
 from hamcrest.core.description import Description
@@ -12,7 +12,7 @@
 T = TypeVar("T")
 
 
-class MatchInAnyOrder(object):
+class MatchInAnyOrder(Generic[T]):
     def __init__(
         self, matchers: Sequence[Matcher[T]], mismatch_description: Optional[Description]
     ) -> None:
@@ -79,6 +79,12 @@ def describe_to(self, description: Description) -> None:
         ).append_text(" in any order")
 
 
+@overload
+def contains_inanyorder(*items: Matcher[T]) -> Matcher[Sequence[T]]: ...
+@overload
+def contains_inanyorder(*items: T) -> Matcher[Sequence[T]]: ...
+
+
 def contains_inanyorder(*items: Union[Matcher[T], T]) -> Matcher[Sequence[T]]:
     """Matches if sequences's elements, in any order, satisfy a given list of
     matchers.

src/hamcrest/library/collection/issequence_containinginorder.py

@@ -1,5 +1,5 @@
 import warnings
-from typing import Optional, Sequence, TypeVar, Union
+from typing import Generic, Optional, Sequence, TypeVar, Union, cast, overload
 
 from hamcrest.core.base_matcher import BaseMatcher
 from hamcrest.core.description import Description
@@ -13,7 +13,7 @@
 T = TypeVar("T")
 
 
-class MatchingInOrder(object):
+class MatchingInOrder(Generic[T]):
     def __init__(
         self, matchers: Sequence[Matcher[T]], mismatch_description: Optional[Description]
     ) -> None:
@@ -78,6 +78,12 @@ def describe_to(self, description: Description) -> None:
         description.append_text("a sequence containing ").append_list("[", ", ", "]", self.matchers)
 
 
+@overload
+def contains_exactly(*items: Matcher[T]) -> Matcher[Sequence[T]]: ...
+@overload
+def contains_exactly(*items: T) -> Matcher[Sequence[T]]: ...
+
+
 def contains_exactly(*items: Union[Matcher[T], T]) -> Matcher[Sequence[T]]:
     """Matches if sequence's elements satisfy a given list of matchers, in order.
 
@@ -97,7 +103,13 @@ def contains_exactly(*items: Union[Matcher[T], T]) -> Matcher[Sequence[T]]:
     return IsSequenceContainingInOrder(matchers)
 
 
+@overload
+def contains(*items: Matcher[T]) -> Matcher[Sequence[T]]: ...
+@overload
+def contains(*items: T) -> Matcher[Sequence[T]]: ...
+
+
 def contains(*items: Union[Matcher[T], T]) -> Matcher[Sequence[T]]:
     """Deprecated - use contains_exactly(*items)"""
     warnings.warn("deprecated - use contains_exactly(*items)", DeprecationWarning)
-    return contains_exactly(*items)
+    return contains_exactly(*cast(tuple[T, ...], items))

src/hamcrest/library/collection/issequence_onlycontaining.py

@@ -1,4 +1,4 @@
-from typing import Sequence, TypeVar, Union
+from typing import Sequence, TypeVar, Union, overload
 
 from hamcrest.core.base_matcher import BaseMatcher
 from hamcrest.core.core.anyof import any_of
@@ -35,6 +35,12 @@ def describe_to(self, description: Description) -> None:
         )
 
 
+@overload
+def only_contains(*items: Matcher[T]) -> Matcher[Sequence[T]]: ...
+@overload
+def only_contains(*items: T) -> Matcher[Sequence[T]]: ...
+
+
 def only_contains(*items: Union[Matcher[T], T]) -> Matcher[Sequence[T]]:
     """Matches if each element of sequence satisfies any of the given matchers.
 

src/hamcrest/library/object/hasproperty.py

@@ -59,7 +59,15 @@ def __str__(self):
         return str(d)
 
 
-def has_property(name: str, match: Union[None, Matcher[V], V] = None) -> Matcher[object]:
+@overload
+def has_property(name: str, match: None = None) -> Matcher[object]: ...
+@overload
+def has_property(name: str, match: Matcher[object]) -> Matcher[object]: ...
+@overload
+def has_property(name: str, match: object) -> Matcher[object]: ...
+
+
+def has_property(name: str, match: Union[None, Matcher[object], object] = None) -> Matcher[object]:
     """Matches if object has a property with a given name whose value satisfies
     a given matcher.