Add comparison_key() and matches() for explicit name comparison

comparison_key() returns the seven parsed components as a lowercased
tuple — a canonical, hashable identity built from the *_list attributes,
so it is independent of string_format/empty_attribute_default and
includes maiden, which the default string_format omits. matches()
compares keys, parsing str arguments with the instance's own Constants,
so any written form of the same name matches ("Smith, John" and
"John Smith"), and raises TypeError for other types.

These are the replacements for __eq__/__hash__ ahead of their 2.0
removal (#223); the deprecation warnings land separately. Part of #224.

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

Author: derek73

docs/release_log.rst

@@ -1,6 +1,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)
     - 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)

nameparser/parser.py

@@ -273,6 +273,62 @@ 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``.
+
+        .. 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:
+
+        .. 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

@@ -300,6 +300,65 @@ def test_not_equal_operator(self) -> None:
         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:
+        c = Constants()
+        c.titles.add('chancellor')
+        hn = HumanName("Chancellor Jane Smith", constants=c)
+        # the str operand is parsed with self.C, so the custom title is
+        # recognized in the comma form; the shared CONSTANTS would not
+        # parse 'chancellor' as a title here
+        self.assertTrue(hn.matches("smith, chancellor jane"))
+
+    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_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.