feat: deprecate multihash

Signed-off-by: nstarman <[email protected]>

plum/__init__.py

@@ -23,6 +23,9 @@
 from .type import resolve_type_hint
 from .util import *  # noqa: F401, F403
 
+# Deprecated
+from .util import multihash  # noqa: F401, F403
+
 # Ensure that type checking is always entirely correct! The default O(1) strategy
 # is super fast, but might yield unpredictable dispatch behaviour. The O(n) strategy
 # actually is not yet available, but we can already opt in to use it.

plum/signature.py

@@ -13,7 +13,7 @@
 from .repr import repr_short, rich_repr
 from .type import is_faithful, resolve_type_hint
 from .typing import get_type_hints
-from .util import Comparable, Missing, TypeHint, multihash, wrap_lambda
+from .util import Comparable, Missing, TypeHint, wrap_lambda
 
 __all__ = ["Signature", "append_default_args"]
 
@@ -131,7 +131,7 @@ def __eq__(self, other):
         return False
 
     def __hash__(self):
-        return multihash(Signature, *self.types, self.varargs)
+        return hash((Signature, *self.types, self.varargs))
 
     def expand_varargs(self, n: int) -> Tuple[TypeHint, ...]:
         """Expand variable arguments.

plum/util.py

@@ -1,6 +1,7 @@
 import abc
 import sys
-from typing import List, Sequence
+import warnings
+from typing import Hashable, List, Sequence
 
 if sys.version_info.minor <= 8:  # pragma: specific no cover 3.9 3.10 3.11
     from typing import Callable
@@ -11,7 +12,6 @@
     "Callable",
     "TypeHint",
     "Missing",
-    "multihash",
     "Comparable",
     "wrap_lambda",
     "is_in_class",
@@ -30,7 +30,7 @@
 class _MissingType(type):
     """The type of :class:`Missing`."""
 
-    def __bool__(self):
+    def __bool__(self) -> bool:
         # For some reason, Sphinx does attempt to evaluate `bool(Missing)`. Let's try
         # to keep Sphinx working correctly by not raising an exception.
         if "sphinx" in sys.modules:
@@ -43,11 +43,11 @@ class Missing(metaclass=_MissingType):
     """A class that can be used to indicate that a value is missing. This class cannot
     be instantiated and has no boolean value."""
 
-    def __init__(self):
+    def __init__(self) -> None:
         raise TypeError("`Missing` cannot be instantiated.")
 
 
-def multihash(*args):
+def multihash(*args: Hashable) -> int:
     """Multi-argument order-sensitive hash.
 
     Args:
@@ -56,6 +56,12 @@ def multihash(*args):
     Returns:
         int: Hash.
     """
+    warnings.warn(
+        "The function `multihash` is deprecated and will be removed in a future "
+        "version. Please use `hash(tuple(*args))` instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
     return hash(args)
 
 
@@ -65,26 +71,26 @@ class Comparable(metaclass=abc.ABCMeta):
     Requires the subclass to just implement `__le__`.
     """
 
-    def __eq__(self, other):
+    def __eq__(self, other) -> bool:
         return self <= other <= self
 
-    def __ne__(self, other):
+    def __ne__(self, other) -> bool:
         return not self == other
 
     @abc.abstractmethod
-    def __le__(self, other):
+    def __le__(self, other) -> bool:
         pass  # pragma: no cover
 
-    def __lt__(self, other):
+    def __lt__(self, other) -> bool:
         return self <= other and self != other
 
-    def __ge__(self, other):
+    def __ge__(self, other) -> bool:
         return other.__le__(self)
 
-    def __gt__(self, other):
+    def __gt__(self, other) -> bool:
         return self >= other and self != other
 
-    def is_comparable(self, other):
+    def is_comparable(self, other: object) -> bool:
         """Check whether this object is comparable with another one.
 
         Args: