Merge pull request #247 from derek73/feature/issue-224-matches-comparison-key

Add matches() and comparison_key(); deprecate __eq__/__hash__

Author: derek73

docs/release_log.rst

@@ -1,6 +1,8 @@
 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())
@@ -273,6 +299,69 @@ def as_dict(self, include_empty: bool = True) -> dict[str, str]:
                     d[m] = val
         return d
 
+    def comparison_key(self) -> tuple[str, ...]:
+        """
+        The seven name components (title, first, middle, last, suffix,
+        nickname, maiden) as a lowercased tuple: a canonical, hashable
+        identity for the parsed name. Use it for dedup, dict keys, and
+        sorting or grouping, e.g.
+        ``unique = {n.comparison_key(): n for n in names}.values()``.
+
+        Built from the ``*_list`` attributes, so it is unaffected by
+        display settings like ``string_format`` and
+        ``empty_attribute_default``.
+
+        Empty or unparsable input yields the all-empty key, so such names
+        all compare equal and collide in dedup; screen them out with
+        ``len(name) == 0`` first.
+
+        .. doctest::
+
+            >>> HumanName("Dr. Juan Q. Xavier de la Vega III").comparison_key()
+            ('dr.', 'juan', 'q. xavier', 'de la vega', 'iii', '', '')
+
+        """
+        return tuple(
+            " ".join(getattr(self, member + "_list")).lower()
+            for member in self._members
+        )
+
+    def matches(self, other: 'str | HumanName') -> bool:
+        """
+        Compare parsed components case-insensitively; the semantic
+        replacement for the deprecated ``==``. A ``str`` argument is parsed
+        first, using this instance's configuration, so any written form of
+        the same name matches; a ``HumanName`` argument is compared as
+        already parsed — its own configuration determined its components.
+        Two empty or unparsable names match each other; check
+        ``len(name) == 0`` to screen them.
+
+        .. doctest::
+
+            >>> name = HumanName("Dr. Juan Q. Xavier de la Vega III")
+            >>> name.matches("de la vega, dr. juan Q. xavier III")
+            True
+            >>> name.matches("Juan de la Vega")
+            False
+
+        Unlike the deprecated ``==``, all seven components participate
+        (including ``maiden``, which the default ``string_format`` omits)
+        and display settings have no effect. Raises ``TypeError`` for
+        anything that is not a ``str`` or ``HumanName``; guard optional
+        values explicitly, e.g. ``x is not None and name.matches(x)``.
+
+        Parses string arguments on every call. When matching one name
+        against many candidates, parse the candidates once or compare
+        :py:meth:`comparison_key` values instead.
+        """
+        if isinstance(other, HumanName):
+            return self.comparison_key() == other.comparison_key()
+        if isinstance(other, str):
+            return self.comparison_key() == type(self)(other, self.C).comparison_key()
+        raise TypeError(
+            f"matches() requires a str or HumanName, got {type(other).__name__}"
+        )
+
     def _process_initial(self, name_part: str, firstname: bool = False) -> str:
         """
             Name parts may include prefixes or conjunctions. This function filters these from the name unless it is

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,147 @@ 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")
+        self.assertEqual(
+            hn.comparison_key(),
+            ('dr.', 'juan', 'q. xavier', 'de la vega', 'iii', '', ''))
+
+    def test_comparison_key_case_insensitive_across_formats(self) -> None:
+        hn1 = HumanName("Dr. Juan Q. Xavier de la Vega III")
+        hn2 = HumanName("de la vega, dr. juan Q. xavier III")
+        self.assertEqual(hn1.comparison_key(), hn2.comparison_key())
+
+    def test_comparison_key_independent_of_string_format(self) -> None:
+        # unlike ==, which compares str(self) and so changes meaning when
+        # display config changes, the key is built from the parsed lists
+        hn1 = HumanName("John Smith")
+        hn2 = HumanName("John Smith", string_format="{last}")
+        self.assertEqual(hn1.comparison_key(), hn2.comparison_key())
+
+    def test_comparison_key_includes_maiden(self) -> None:
+        # maiden isn't in the default string_format, so == can't see it;
+        # the key includes all seven members
+        hn1 = HumanName(first="Jenny", last="Baker", maiden="Johnson")
+        hn2 = HumanName(first="Jenny", last="Baker")
+        self.assertNotEqual(hn1.comparison_key(), hn2.comparison_key())
+
+    def test_comparison_key_usable_for_dedup(self) -> None:
+        names = [HumanName("John Smith"), HumanName("Smith, John"),
+                 HumanName("JOHN SMITH"), HumanName("Jane Smith")]
+        unique = {n.comparison_key(): n for n in names}
+        self.assertEqual(len(unique), 2)
+
+    def test_matches_str_is_semantic_not_textual(self) -> None:
+        # any written form of the same name matches, unlike == which only
+        # matches strings that render exactly like str(self)
+        hn = HumanName("Dr. Juan Q. Xavier de la Vega III")
+        self.assertTrue(hn.matches("de la vega, dr. juan Q. xavier III"))
+        self.assertTrue(hn.matches("Dr. Juan Q. Xavier de la Vega III"))
+        self.assertFalse(hn.matches("Juan de la Vega"))
+
+    def test_matches_humanname_operand(self) -> None:
+        hn = HumanName("John Smith")
+        self.assertTrue(hn.matches(HumanName("JOHN SMITH")))
+        self.assertFalse(hn.matches(HumanName("Jane Smith")))
+
+    def test_matches_parses_str_with_instance_constants(self) -> None:
+        # the custom title must not be a default one ('chancellor' is!), or
+        # this passes without the self.C parse path ever mattering
+        c = Constants()
+        c.titles.add('zephyrmark')
+        self.assertNotIn('zephyrmark', CONSTANTS.titles)
+        hn = HumanName("Zephyrmark Jane Smith", constants=c)
+        # the str operand is parsed with self.C, so the custom title is
+        # recognized in the comma form; parsed with the shared CONSTANTS,
+        # 'zephyrmark' would land in first/middle and the keys would differ
+        self.assertTrue(hn.matches("smith, zephyrmark jane"))
+
+    def test_matches_humanname_operand_keeps_its_own_parse(self) -> None:
+        # asymmetry, pinned deliberately: a str operand is reparsed with
+        # self.C, but a HumanName operand is compared as already parsed --
+        # its own constants determined its components
+        c = Constants()
+        c.titles.add('zephyrmark')
+        with_title = HumanName("Zephyrmark Jane Smith", constants=c)
+        default_parse = HumanName("Zephyrmark Jane Smith")
+        self.assertTrue(with_title.matches("Zephyrmark Jane Smith"))
+        self.assertFalse(with_title.matches(default_parse))
+
+    def test_empty_parses_share_a_comparison_key(self) -> None:
+        # documented caveat: empty/unparsable input collapses to the
+        # all-empty key, so such names match each other and collide in
+        # dedup; screen with len(name) == 0 first
+        self.assertTrue(HumanName("").matches(HumanName(",")))
+        self.assertEqual(HumanName("()").comparison_key(),
+                         HumanName("").comparison_key())
+
+    def test_matches_non_ascii_case_insensitive(self) -> None:
+        hn = HumanName("JOSÉ GARCÍA")
+        self.assertTrue(hn.matches("José García"))
+
+    def test_matches_rejects_other_types(self) -> None:
+        hn = HumanName("John Smith")
+        for bad in (None, 42, b"John Smith", ["John Smith"]):
+            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