Deprecate __eq__ and __hash__ for removal in 2.0

Both emit DeprecationWarning naming the replacement (matches() /
comparison_key()); behavior is unchanged until 2.0. Rationale lives in
issue #223: case-insensitive equality, equality with plain strings, and
hashability are mutually inconsistent promises (equal objects can hash
differently), equality depends on string_format, and maiden is
invisible to it.

Existing eq/hash tests now assert the warning fires via
pytest.deprecated_call(), keeping the suite noise-free while still
covering the deprecated behavior. usage.rst's equality example moves to
matches() with a deprecation note.

Closes #224

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: derek73

docs/release_log.rst

@@ -2,6 +2,7 @@ Release Log
 ===========
 * 1.3.0 - Unreleased
     - Add ``matches()`` and ``comparison_key()`` for explicit name comparison: ``matches()`` compares parsed components case-insensitively (parsing ``str`` arguments first, so ``name.matches("Smith, John")`` and ``name.matches("John Smith")`` both match) and ``comparison_key()`` returns a hashable tuple of the seven components for dedup, dict keys, and sorting (#224)
+    - Deprecate ``HumanName.__eq__`` and ``__hash__`` for removal in 2.0 (#223): the current design's three promises — case-insensitive equality, equality with plain strings, and hashability — are mutually inconsistent (equal objects can hash differently), equality depends on ``string_format``, and ``maiden`` is invisible to it. Both now emit ``DeprecationWarning`` naming the replacement; behavior is otherwise unchanged until 2.0 (closes #224)
     - Fix the five non-cached-union ``SetManager``-backed ``Constants`` attributes (``first_name_titles``, ``conjunctions``, ``bound_first_names``, ``non_first_name_prefixes``, ``suffix_acronyms_ambiguous``) accepting non-``SetManager`` assignment silently (e.g. ``constants.conjunctions = 'and'``), degrading membership checks into substring tests with no error; assignment now raises ``TypeError`` like the four cached-union attributes already did (closes #241)
     - Fix ``HumanName.C`` accepting an invalid ``constants`` value on post-construction assignment (e.g. ``hn.C = 'garbage'``), bypassing the constructor's validation and failing later with an unrelated ``AttributeError``; ``C`` is now a property that validates on assignment too (closes #239)
     - Fix ``TupleManager`` (and ``RegexTupleManager``) accepting a bare string/bytes argument (raising a cryptic ``dict``-internals ``ValueError``) or an iterable of 2-character strings (silently shredding each into a key/value pair, e.g. ``Constants(capitalization_exceptions=['ii'])`` becoming ``{'i': 'i'}``); both now raise ``TypeError`` with a clear message (closes #242)

docs/usage.rst

@@ -65,7 +65,9 @@ Requires Python 3.10+.
     {'first': 'Jonathan', 'middle': 'A. Harris', 'last': 'Doe-Ray', 'nickname': 'John'}
     >>> name = HumanName("Dr. Juan Q. Xavier de la Vega III")
     >>> name2 = HumanName("de la vega, dr. juan Q. xavier III")
-    >>> name == name2
+    >>> name.matches(name2)
+    True
+    >>> name.matches("de la vega, dr. juan Q. xavier III")
     True
     >>> len(name)
     5
@@ -74,6 +76,11 @@ Requires Python 3.10+.
     >>> name[1:-3]
     ['Juan', 'Q. Xavier', 'de la Vega']
 
+``name == other`` and ``hash(name)`` are deprecated and will be removed in
+2.0; use ``matches()`` for comparison and ``comparison_key()`` for sets,
+dicts, and dedup (see `issue #223
+<https://github.com/derek73/python-nameparser/issues/223>`_).
+
 Empty or unparsable input does not raise an error; it produces a name whose
 attributes are all empty. Check ``len(name) == 0`` (or ``str(name) == ''``)
 to detect that nothing was parsed.

nameparser/parser.py

@@ -1,4 +1,5 @@
 import re
+import warnings
 from collections.abc import Callable, Iterable, Iterator
 from operator import itemgetter
 from itertools import groupby
@@ -199,9 +200,22 @@ def __len__(self) -> int:
 
     def __eq__(self, other: object) -> bool:
         """
+        .. deprecated:: 1.3.0
+            Removed in 2.0 (see issue #223); use :py:meth:`matches`.
+
         HumanName instances are equal to other objects whose
-        lower case unicode representation is the same.
-        """
+        lower case unicode representation is the same. Note the
+        differences from :py:meth:`matches`: this compares formatted
+        output, so it depends on ``string_format`` and cannot see
+        ``maiden``, and it stringifies operands of any type.
+        """
+        warnings.warn(
+            "HumanName == comparison is deprecated and will be removed in "
+            "2.0; use matches() instead. See "
+            "https://github.com/derek73/python-nameparser/issues/223",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         return str(self).lower() == str(other).lower()
 
     @overload
@@ -231,6 +245,18 @@ def __str__(self) -> str:
         return " ".join(self)
 
     def __hash__(self) -> int:
+        """
+        .. deprecated:: 1.3.0
+            Removed in 2.0 (see issue #223); use :py:meth:`comparison_key`
+            for sets, dicts, and dedup.
+        """
+        warnings.warn(
+            "hash(HumanName) is deprecated and will be removed in 2.0; use "
+            "comparison_key() for sets and dicts. See "
+            "https://github.com/derek73/python-nameparser/issues/223",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         # __eq__ compares lowercased strings, so hash the lowercased string
         # to keep equal instances in the same hash bucket.
         return hash(str(self).lower())

tests/test_python_api.py

@@ -1,6 +1,7 @@
 import copy
 import pickle
 import re
+import warnings
 
 import pytest
 
@@ -215,18 +216,22 @@ def test_deepcopy_default_name_preserves_singleton_identity(self) -> None:
         self.assertEqual(dup.last, hn.last)
 
     def test_comparison(self) -> None:
+        # deprecated behavior (#223/#224), still supported until 2.0:
+        # deprecated_call() asserts the warning fires while silencing it
         hn1 = HumanName("Doe-Ray, Dr. John P., CLU, CFP, LUTC")
         hn2 = HumanName("Dr. John P. Doe-Ray, CLU, CFP, LUTC")
-        self.assertTrue(hn1 == hn2)
-        self.assertIsNot(hn1, hn2)
-        self.assertTrue(hn1 == "Dr. John P. Doe-Ray CLU, CFP, LUTC")
+        with pytest.deprecated_call():
+            self.assertTrue(hn1 == hn2)
+            self.assertIsNot(hn1, hn2)
+            self.assertTrue(hn1 == "Dr. John P. Doe-Ray CLU, CFP, LUTC")
         hn1 = HumanName("Doe, Dr. John P., CLU, CFP, LUTC")
         hn2 = HumanName("Dr. John P. Doe-Ray, CLU, CFP, LUTC")
-        self.assertTrue(not hn1 == hn2)
-        self.assertTrue(not hn1 == 0)
-        self.assertTrue(not hn1 == "test")
-        self.assertTrue(not hn1 == ["test"])
-        self.assertTrue(not hn1 == {"test": hn2})
+        with pytest.deprecated_call():
+            self.assertTrue(not hn1 == hn2)
+            self.assertTrue(not hn1 == 0)
+            self.assertTrue(not hn1 == "test")
+            self.assertTrue(not hn1 == ["test"])
+            self.assertTrue(not hn1 == {"test": hn2})
 
     def test_assignment_to_full_name(self) -> None:
         hn = HumanName("John A. Kenneth Doe, Jr.")
@@ -275,30 +280,37 @@ def test_assign_list_to_attribute(self) -> None:
         self.m(hn.suffix, "test", hn)
 
     def test_comparison_case_insensitive(self) -> None:
+        # deprecated behavior (#223/#224), still supported until 2.0
         hn1 = HumanName("Doe-Ray, Dr. John P., CLU, CFP, LUTC")
         hn2 = HumanName("dr. john p. doe-Ray, CLU, CFP, LUTC")
-        self.assertTrue(hn1 == hn2)
-        self.assertIsNot(hn1, hn2)
-        self.assertTrue(hn1 == "Dr. John P. Doe-ray clu, CFP, LUTC")
+        with pytest.deprecated_call():
+            self.assertTrue(hn1 == hn2)
+            self.assertIsNot(hn1, hn2)
+            self.assertTrue(hn1 == "Dr. John P. Doe-ray clu, CFP, LUTC")
 
     def test_hash_matches_case_insensitive_equality(self) -> None:
+        # deprecated behavior (#223/#224), still supported until 2.0.
         # __eq__ compares lowercased strings, so __hash__ must too:
         # equal objects are required to have equal hashes.
         hn1 = HumanName("Doe-Ray, Dr. John P., CLU, CFP, LUTC")
         hn2 = HumanName("dr. john p. doe-Ray, CLU, CFP, LUTC")
-        self.assertEqual(hn1, hn2)
-        self.assertEqual(hash(hn1), hash(hn2))
-        self.assertEqual(len({hn1, hn2}), 1)
-        # __eq__ also accepts plain strings, so hashing str(self).lower()
-        # specifically (not e.g. an attribute tuple) is what lets strings and
-        # HumanName instances interoperate in sets and dicts
-        hn = HumanName("John Smith")
-        self.assertEqual(hash(hn), hash("john smith"))
-        self.assertIn("john smith", {hn})
+        with pytest.deprecated_call():
+            self.assertEqual(hn1, hn2)
+            self.assertEqual(hash(hn1), hash(hn2))
+            self.assertEqual(len({hn1, hn2}), 1)
+            # __eq__ also accepts plain strings, so hashing str(self).lower()
+            # specifically (not e.g. an attribute tuple) is what lets strings
+            # and HumanName instances interoperate in sets and dicts
+            hn = HumanName("John Smith")
+            self.assertEqual(hash(hn), hash("john smith"))
+            self.assertIn("john smith", {hn})
 
     def test_not_equal_operator(self) -> None:
-        self.assertTrue(HumanName("John Smith") != HumanName("Jane Smith"))
-        self.assertFalse(HumanName("John Smith") != HumanName("john smith"))
+        # deprecated behavior (#223/#224), still supported until 2.0;
+        # != routes through __eq__, so it warns too
+        with pytest.deprecated_call():
+            self.assertTrue(HumanName("John Smith") != HumanName("Jane Smith"))
+            self.assertFalse(HumanName("John Smith") != HumanName("john smith"))
 
     def test_comparison_key_components(self) -> None:
         hn = HumanName("Dr. Juan Q. Xavier de la Vega III")
@@ -359,6 +371,31 @@ def test_matches_rejects_other_types(self) -> None:
             with pytest.raises(TypeError, match="str or HumanName"):
                 hn.matches(bad)  # type: ignore[arg-type]
 
+    def test_eq_emits_deprecation_warning(self) -> None:
+        # behavior is unchanged until 2.0 (#223); 1.3.0 only warns
+        hn1 = HumanName("John Smith")
+        hn2 = HumanName("john smith")
+        with pytest.deprecated_call(match="matches"):
+            result = hn1 == hn2
+        self.assertTrue(result)
+
+    def test_hash_emits_deprecation_warning(self) -> None:
+        hn = HumanName("John Smith")
+        with pytest.deprecated_call(match="comparison_key"):
+            result = hash(hn)
+        self.assertEqual(result, hash("john smith"))
+
+    def test_new_comparison_api_does_not_warn(self) -> None:
+        # the replacements must be adoptable before 2.0 without tripping
+        # -W error test suites; matches(str) parses, so this also covers
+        # the parse path
+        hn = HumanName("John Smith")
+        with warnings.catch_warnings():
+            warnings.simplefilter("error")
+            hn.comparison_key()
+            hn.matches("Smith, John")
+            hn.matches(HumanName("John Smith"))
+
     def test_unparsable_attribute_removed(self) -> None:
         # Removed in 1.3.0: the guard that reported unparsable names was
         # unreachable, so the attribute was always False after any parse.