Deprecate hash for unsafe_hash (#1323)

* Deprecate hash for unsafe_hash

It's the standard -- what are we gonna do.

* Add deprecation tests

* Add news fragment

Author: hynek

changelog.d/1323.deprecation.md

@@ -0,0 +1 @@
+The *hash* argument to `@attr.s`, `@attrs.define`, and `make_class()` is now deprecated in favor of *unsafe_hash*, as defined by PEP 681.

src/attr/_make.py

@@ -1270,20 +1270,30 @@ def attrs(
     .. versionadded:: 24.1.0
        If a class has an *inherited* classmethod called
        ``__attrs_init_subclass__``, it is executed after the class is created.
+    .. deprecated:: 24.1.0 *hash* is deprecated in favor of *unsafe_hash*.
     """
     if repr_ns is not None:
         import warnings
 
         warnings.warn(
             DeprecationWarning(
-                "The `repr_ns` argument is deprecated and will be removed in or after April 2025."
+                "The `repr_ns` argument is deprecated and will be removed in or after August 2025."
             ),
             stacklevel=2,
         )
 
     eq_, order_ = _determine_attrs_eq_order(cmp, eq, order, None)
 
-    # unsafe_hash takes precedence due to PEP 681.
+    # hash is deprecated & unsafe_hash takes precedence due to PEP 681.
+    if hash is not None:
+        import warnings
+
+        warnings.warn(
+            DeprecationWarning(
+                "The `hash` argument is deprecated in favor of `unsafe_hash` and will be removed in or after August 2025."
+            ),
+            stacklevel=2,
+        )
     if unsafe_hash is not None:
         hash = unsafe_hash
 
@@ -2854,6 +2864,19 @@ def make_class(
         True,
     )
 
+    hash = attributes_arguments.pop("hash", _SENTINEL)
+    if hash is not _SENTINEL:
+        import warnings
+
+        warnings.warn(
+            DeprecationWarning(
+                "The `hash` argument is deprecated in favor of `unsafe_hash` and will be removed in or after August 2025."
+            ),
+            stacklevel=2,
+        )
+
+        attributes_arguments["unsafe_hash"] = hash
+
     cls = _attrs(these=cls_dict, **attributes_arguments)(type_)
     # Only add type annotations now or "_attrs()" will complain:
     cls.__annotations__ = {
@@ -2866,7 +2889,7 @@ def make_class(
 # import into .validators / .converters.
 
 
-@attrs(slots=True, hash=True)
+@attrs(slots=True, unsafe_hash=True)
 class _AndValidator:
     """
     Compose many validators to a single one.

src/attr/_next_gen.py

@@ -184,7 +184,7 @@ def define(
                   details.
 
         hash (bool | None):
-            Alias for *unsafe_hash*. *unsafe_hash* takes precedence.
+            Deprecated alias for *unsafe_hash*. *unsafe_hash* takes precedence.
 
         cache_hash (bool):
             Ensure that the object's hash code is computed only once and stored
@@ -320,6 +320,7 @@ def define(
     .. versionadded:: 24.1.0
        If a class has an *inherited* classmethod called
        ``__attrs_init_subclass__``, it is executed after the class is created.
+    .. deprecated:: 24.1.0 *hash* is deprecated in favor of *unsafe_hash*.
 
     .. note::
 

src/attr/validators.py

@@ -88,7 +88,7 @@ def disabled():
         set_run_validators(True)
 
 
-@attrs(repr=False, slots=True, hash=True)
+@attrs(repr=False, slots=True, unsafe_hash=True)
 class _InstanceOfValidator:
     type = attrib()
 
@@ -196,7 +196,7 @@ def matches_re(regex, flags=0, func=None):
     return _MatchesReValidator(pattern, match_func)
 
 
-@attrs(repr=False, slots=True, hash=True)
+@attrs(repr=False, slots=True, unsafe_hash=True)
 class _OptionalValidator:
     validator = attrib()
 
@@ -231,7 +231,7 @@ def optional(validator):
     return _OptionalValidator(validator)
 
 
-@attrs(repr=False, slots=True, hash=True)
+@attrs(repr=False, slots=True, unsafe_hash=True)
 class _InValidator:
     options = attrib()
     _original_options = attrib(hash=False)
@@ -290,7 +290,7 @@ def in_(options):
     return _InValidator(options, repr_options)
 
 
-@attrs(repr=False, slots=False, hash=True)
+@attrs(repr=False, slots=False, unsafe_hash=True)
 class _IsCallableValidator:
     def __call__(self, inst, attr, value):
         """
@@ -328,7 +328,7 @@ def is_callable():
     return _IsCallableValidator()
 
 
-@attrs(repr=False, slots=True, hash=True)
+@attrs(repr=False, slots=True, unsafe_hash=True)
 class _DeepIterable:
     member_validator = attrib(validator=is_callable())
     iterable_validator = attrib(
@@ -377,7 +377,7 @@ def deep_iterable(member_validator, iterable_validator=None):
     return _DeepIterable(member_validator, iterable_validator)
 
 
-@attrs(repr=False, slots=True, hash=True)
+@attrs(repr=False, slots=True, unsafe_hash=True)
 class _DeepMapping:
     key_validator = attrib(validator=is_callable())
     value_validator = attrib(validator=is_callable())
@@ -554,7 +554,7 @@ def min_len(length):
     return _MinLengthValidator(length)
 
 
-@attrs(repr=False, slots=True, hash=True)
+@attrs(repr=False, slots=True, unsafe_hash=True)
 class _SubclassOfValidator:
     type = attrib()
 
@@ -592,7 +592,7 @@ def _subclass_of(type):
     return _SubclassOfValidator(type)
 
 
-@attrs(repr=False, slots=True, hash=True)
+@attrs(repr=False, slots=True, unsafe_hash=True)
 class _NotValidator:
     validator = attrib()
     msg = attrib(
@@ -665,7 +665,7 @@ def not_(validator, *, msg=None, exc_types=(ValueError, TypeError)):
     return _NotValidator(validator, msg, exc_types)
 
 
-@attrs(repr=False, slots=True, hash=True)
+@attrs(repr=False, slots=True, unsafe_hash=True)
 class _OrValidator:
     validators = attrib()
 

tests/test_dunders.py

@@ -64,16 +64,16 @@ class OrderCallableCSlots:
 # HashC is hashable by explicit definition while HashCSlots is hashable
 # implicitly.  The "Cached" versions are the same, except with hash code
 # caching enabled
-HashC = simple_class(hash=True)
-HashCSlots = simple_class(hash=None, eq=True, frozen=True, slots=True)
-HashCCached = simple_class(hash=True, cache_hash=True)
+HashC = simple_class(unsafe_hash=True)
+HashCSlots = simple_class(unsafe_hash=None, eq=True, frozen=True, slots=True)
+HashCCached = simple_class(unsafe_hash=True, cache_hash=True)
 HashCSlotsCached = simple_class(
-    hash=None, eq=True, frozen=True, slots=True, cache_hash=True
+    unsafe_hash=None, eq=True, frozen=True, slots=True, cache_hash=True
 )
 # the cached hash code is stored slightly differently in this case
 # so it needs to be tested separately
 HashCFrozenNotSlotsCached = simple_class(
-    frozen=True, slots=False, hash=True, cache_hash=True
+    frozen=True, slots=False, unsafe_hash=True, cache_hash=True
 )
 
 
@@ -443,17 +443,17 @@ def test_str_no_repr(self):
 
 # these are for use in TestAddHash.test_cache_hash_serialization
 # they need to be out here so they can be un-pickled
-@attr.attrs(hash=True, cache_hash=False)
+@attr.attrs(unsafe_hash=True, cache_hash=False)
 class HashCacheSerializationTestUncached:
     foo_value = attr.ib()
 
 
-@attr.attrs(hash=True, cache_hash=True)
+@attr.attrs(unsafe_hash=True, cache_hash=True)
 class HashCacheSerializationTestCached:
     foo_value = attr.ib()
 
 
-@attr.attrs(slots=True, hash=True, cache_hash=True)
+@attr.attrs(slots=True, unsafe_hash=True, cache_hash=True)
 class HashCacheSerializationTestCachedSlots:
     foo_value = attr.ib()
 
@@ -660,7 +660,7 @@ def test_copy_hash_cleared(self, cache_hash, frozen, slots):
 
         # Give it an explicit hash if we don't have an implicit one
         if not frozen:
-            kwargs["hash"] = True
+            kwargs["unsafe_hash"] = True
 
         @attr.s(**kwargs)
         class C:
@@ -711,7 +711,7 @@ def test_copy_two_arg_reduce(self, frozen):
         __reduce__ generated when cache_hash=True works in that case.
         """
 
-        @attr.s(frozen=frozen, cache_hash=True, hash=True)
+        @attr.s(frozen=frozen, cache_hash=True, unsafe_hash=True)
         class C:
             x = attr.ib()
 
@@ -965,7 +965,7 @@ def test_false(self):
         assert False is bool(NOTHING)
 
 
-@attr.s(hash=True, order=True)
+@attr.s(unsafe_hash=True, order=True)
 class C:
     pass
 
@@ -974,17 +974,19 @@ class C:
 OriginalC = C
 
 
-@attr.s(hash=True, order=True)
+@attr.s(unsafe_hash=True, order=True)
 class C:
     pass
 
 
 CopyC = C
 
 
-@attr.s(hash=True, order=True)
+@attr.s(unsafe_hash=True, order=True)
 class C:
-    """A different class, to generate different methods."""
+    """
+    A different class, to generate different methods.
+    """
 
     a = attr.ib()
 

tests/test_functional.py

@@ -379,26 +379,26 @@ class C:
 
     def test_hash_by_id(self):
         """
-        With dict classes, hashing by ID is active for hash=False even on
-        Python 3.  This is incorrect behavior but we have to retain it for
-        backward compatibility.
+        With dict classes, hashing by ID is active for hash=False.  This is
+        incorrect behavior but we have to retain it for
+        backwards-compatibility.
         """
 
-        @attr.s(hash=False)
+        @attr.s(unsafe_hash=False)
         class HashByIDBackwardCompat:
             x = attr.ib()
 
         assert hash(HashByIDBackwardCompat(1)) != hash(
             HashByIDBackwardCompat(1)
         )
 
-        @attr.s(hash=False, eq=False)
+        @attr.s(unsafe_hash=False, eq=False)
         class HashByID:
             x = attr.ib()
 
         assert hash(HashByID(1)) != hash(HashByID(1))
 
-        @attr.s(hash=True)
+        @attr.s(unsafe_hash=True)
         class HashByValues:
             x = attr.ib()
 
@@ -421,17 +421,22 @@ class C:
         class D(C):
             pass
 
-    def test_hash_false_eq_false(self, slots):
+    def test_unsafe_hash_false_eq_false(self, slots):
         """
-        hash=False and eq=False make a class hashable by ID.
+        unsafe_hash=False and eq=False make a class hashable by ID.
         """
 
-        @attr.s(hash=False, eq=False, slots=slots)
+        @attr.s(unsafe_hash=False, eq=False, slots=slots)
         class C:
             pass
 
         assert hash(C()) != hash(C())
 
+    def test_hash_deprecated(self):
+        """
+        Using the hash argument is deprecated.
+        """
+
     def test_eq_false(self, slots):
         """
         eq=False makes a class hashable by ID.