fix: pickled HumanName keeps multi-word suffix entries intact

__setstate__ restored components by joining each pickled *_list into one
string and letting replace() re-split it on whitespace. That destroyed
the entry boundaries: suffix_list ["Ph. D."] came back as ["Ph.", "D."],
and the suffix view's ", " join then rendered one credential as two.

Build tokens per entry instead, tagging continuation words "joined" --
the inverse of _list_for's heal -- so list -> pickle -> list is the
identity again.

This was a regression against 1.4.0, not an inherited quirk: all eight
affected corpus names round-trip unchanged under a live 1.4.0, and now
match it byte for byte. 8 of the 486 differential-corpus names drifted
before the fix (any multi-word suffix run in one comma segment: "Jr. MD",
"Q.C. M.P.", "V Jr.", "MD PhD - FACS Fellow"); 0 drift after, checking
str(), as_dict() and all six _list attributes.

The differential harness could not have caught this -- it compares fresh
v1 and 2.0 parses and never crosses a pickle boundary.

Note the list SETTER (_set_field) splits the same way on purpose: 1.4.0
also renders hn.suffix = ["Ph. D.", "MD"] as "Ph., D., MD", so that path
is v1 parity and is deliberately left alone.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: derek73

nameparser/_facade.py

@@ -31,7 +31,7 @@
 from nameparser._config_shim import CONSTANTS, Constants, _cached_parser
 from nameparser._lexicon import _normalize
 from nameparser._parser import Parser
-from nameparser._types import FOLDED_TAG, ParsedName, Role
+from nameparser._types import FOLDED_TAG, ParsedName, Role, Token
 
 _V2_FIELD = {"first": "given", "last": "family"}  # v1 name -> v2 name
 _V1_SPELLING = {v2: v1 for v1, v2 in _V2_FIELD.items()}
@@ -662,18 +662,21 @@ def __setstate__(self, state: dict[str, Any]) -> None:
         self._suffix_delimiter = state.get("suffix_delimiter",
                                            defaults.suffix_delimiter)
         self._full_name = state.get("_full_name", "")
-        # components come back exactly as pickled (spec §2): synthetic
-        # tokens via replace(), never a re-parse. Known edge: replace()
-        # re-splits on whitespace without the "joined" tag, so joined-tag
-        # healing is lost for multi-word list elements -- v1's fix_phd
-        # suffix pickles as ["Ph. D."] but round-trips to ["Ph.", "D."],
-        # rendering the suffix as "Ph., D.". Classify in the differential
-        # harness / M12 if it surfaces.
-        parsed = ParsedName(original=str(state.get("original", "")),
-                            tokens=(), ambiguities=())
-        fields = {}
+        # Components come back exactly as pickled (spec §2): synthetic
+        # tokens, never a re-parse. Build them per *_list ENTRY rather
+        # than from one joined string -- an entry may hold several words
+        # ("Ph. D.", "Q.C. M.P."), and re-splitting the joined string on
+        # whitespace would promote each word to its own entry, which the
+        # suffix view then renders comma-separated ("Ph., D."). Marking
+        # continuation words "joined" is the inverse of _list_for's heal,
+        # so list -> pickle -> list is the identity v1 gave us.
+        tokens: list[Token] = []
         for member in _MEMBERS:
-            values = state.get(f"{member}_list") or []
-            fields[_V2_FIELD.get(member, member)] = " ".join(values)
-        self._parsed = parsed.replace(
-            **{k: v for k, v in fields.items() if v})
+            role = Role(_V2_FIELD.get(member, member))
+            for entry in state.get(f"{member}_list") or []:
+                for position, word in enumerate(entry.split()):
+                    tokens.append(Token(
+                        word, None, role,
+                        frozenset({"joined"}) if position else frozenset()))
+        self._parsed = ParsedName(
+            original=str(state.get("original", "")), tokens=tuple(tokens))

tests/v2/test_facade.py

@@ -307,6 +307,39 @@ def test_pickle_round_trip_preserves_components() -> None:
     assert loaded.C is CONSTANTS             # shared sentinel restored
 
 
+#: Every name in the 486-name differential corpus whose HumanName pickle
+#: round-trip drifted before the __setstate__ element-boundary fix. Each
+#: carries a multi-word suffix entry -- a "joined" continuation token --
+#: inside one comma segment. Verified against a live 1.4.0: all eight
+#: round-trip unchanged there, so drift here is a regression, not an
+#: inherited quirk.
+_MULTIWORD_SUFFIX_NAMES = [
+    "Andrew Perkins, Jr., Col. (Ret)",
+    "Clarke, Kenneth, Q.C. M.P.",
+    "Doe, John, MD PhD - FACS Fellow",
+    "Franklin Washington, Jr. MD",
+    "John Smith Ph. D.",
+    "John Smith, Ph. D.",
+    "John Smith, V Jr.",
+    "John Smith, V MD",
+]
+
+
+@pytest.mark.parametrize("raw", _MULTIWORD_SUFFIX_NAMES)
+def test_pickle_round_trip_preserves_multiword_suffix_entries(raw: str) -> None:
+    # __setstate__ restores components from the pickled *_list values.
+    # Joining them into one string and letting replace() re-split on
+    # whitespace destroys the entry boundaries, and the suffix view's
+    # ", " join then renders one credential as two ("Ph." + "D." ->
+    # "Ph., D."). Entries must survive as entries.
+    n = HumanName(raw)
+    loaded = pickle.loads(pickle.dumps(n))
+    assert loaded.suffix_list == n.suffix_list
+    assert loaded.suffix == n.suffix
+    assert str(loaded) == str(n)
+    assert loaded.as_dict() == n.as_dict()
+
+
 # -- Gap 2: parse_full_name() (v1's documented re-parse idiom) -------------