Address review feedback: harden tests, fix release log claim, document empty parse

- Correct release log: the unparsable guard broke in 2013 (v0.2.9), not
  in the earliest releases (2011-2013 releases had a working attribute)
- Pin multiple empty comma segments ("Doe, John,, Jr.,, III") so a
  break-instead-of-continue regression can't pass the single-empty test
- Pin hash interop with plain strings ("john smith" in {HumanName(...)}),
  which depends on hashing str(self).lower() specifically
- Tighten the "final piece" comments in parse_full_name and document
  are_suffixes()'s vacuous-truth contract that the piece loops rely on
- Document in usage.rst that empty/garbage input parses to an all-empty
  name, checked via len(name) == 0

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

Author: derek73

docs/release_log.rst

@@ -1,7 +1,7 @@
 Release Log
 ===========
 * 1.3.0 - Unreleased
-    - Remove the vestigial ``unparsable`` attribute: the guard that was meant to set it was unreachable, so it has reported ``False`` for every parsed name since the earliest releases
+    - Remove the vestigial ``unparsable`` attribute: the guard that was meant to set it has been unreachable since 2013 (v0.2.9), so it has reported ``False`` for every parsed name for over a decade; check ``len(name) == 0`` to detect an empty parse
     - Fix ``__hash__`` to lowercase the name like ``__eq__`` does, so equal ``HumanName`` instances hash equal and behave correctly in sets and dicts
     - Fix ``initials()`` emitting a stray empty initial (e.g. ``"J. . V."``) -- or raising ``TypeError`` when ``empty_attribute_default`` is ``None`` -- for name parts with no initialable words, e.g. a prefix-only middle name like ``"de la"``
     - Fix a trailing suffix being silently dropped after an empty comma segment, e.g. ``"Doe, John,, Jr."`` losing the ``"Jr."``

docs/usage.rst

@@ -74,6 +74,18 @@ Requires Python 3.10+.
     >>> name[1:-3]
     ['Juan', 'Q. Xavier', 'de la Vega']
 
+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.
+
+.. doctest::
+
+    >>> name = HumanName("")
+    >>> len(name)
+    0
+    >>> str(name)
+    ''
+
 
 Capitalization Support
 ----------------------

nameparser/parser.py

@@ -309,10 +309,11 @@ def initials(self) -> str:
 
         first_initials_list, middle_initials_list, last_initials_list = self._initials_lists()
 
-        # Empty parts must render as '' (not empty_attribute_default, which may be
-        # None) so str.format does not interpolate the literal "None" into the
-        # output. A fully-empty result falls back to empty_attribute_default,
-        # matching the other attribute accessors (e.g. ``first``).
+        # Empty name groups must render as '' (not empty_attribute_default,
+        # which may be None) so str.format does not interpolate the literal
+        # "None" into the output. A fully-empty result falls back to
+        # empty_attribute_default, matching the other attribute accessors
+        # (e.g. ``first``).
         initials_dict = {
             "first":  (self.initials_delimiter + self.initials_separator).join(first_initials_list) + self.initials_delimiter
             if len(first_initials_list) else "",
@@ -650,7 +651,12 @@ def is_suffix(self, piece: str) -> bool:
                 and not self.is_an_initial(piece)
 
     def are_suffixes(self, pieces: Iterable[str]) -> bool:
-        """Return True if all pieces are suffixes."""
+        """Return True if all pieces are suffixes.
+
+        Vacuously True for an empty iterable — the piece loops in
+        :py:func:`parse_full_name` rely on this to route the final piece
+        to the last-name branch.
+        """
         for piece in pieces:
             if not self.is_suffix(piece):
                 return False
@@ -1044,9 +1050,10 @@ def parse_full_name(self) -> None:
                             self.is_roman_numeral(nxt) and i == p_len - 2
                             and not self.is_an_initial(piece)
                 ):
-                    # the final piece always lands here: are_suffixes() is
-                    # vacuously True for the empty tail, making this the
-                    # last-name branch as well as the suffix branch
+                    # any piece reaching this check as the final piece lands
+                    # here: are_suffixes() is vacuously True for the empty
+                    # tail, making this the last-name branch as well as the
+                    # suffix branch
                     self.last_list.append(piece)
                     self.suffix_list += pieces[i+1:]
                     break

tests/test_python_api.py

@@ -223,6 +223,12 @@ def test_hash_matches_case_insensitive_equality(self) -> None:
         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"))

tests/test_suffixes.py

@@ -431,3 +431,8 @@ def test_empty_comma_segment_does_not_drop_following_suffix(self) -> None:
         self.m(hn.first, "John", hn)
         self.m(hn.last, "Doe", hn)
         self.m(hn.suffix, "Jr.", hn)
+        # each empty segment is skipped individually; segments after a later
+        # empty must survive too (guards against a break-instead-of-continue
+        # regression that the single-empty case above would not catch)
+        hn = HumanName("Doe, John,, Jr.,, III")
+        self.m(hn.suffix, "Jr., III", hn)