Add facade capitalize/matches/comparison_key and v1-compatible pickling

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

Author: derek73

nameparser/_facade.py

@@ -10,6 +10,7 @@
 import re
 import warnings
 from collections.abc import Iterator
+from typing import Any
 
 from nameparser._config_shim import CONSTANTS, Constants, _cached_parser
 from nameparser._lexicon import _normalize
@@ -229,11 +230,16 @@ def _apply_full_name(self, value: str) -> None:
         if self._C.capitalize_name:
             self.capitalize()  # v1 parser.py:1653 parity
 
-    def capitalize(self) -> None:
-        """Minimal M6 body (M10 ports the full force-semantics rules):
-        re-capitalize the current parse against the bound lexicon."""
+    def capitalize(self, force: bool | None = None) -> None:
+        """Re-capitalize the current parse against the bound lexicon.
+        force=None reads the bound Constants' render default
+        (force_mixed_case_capitalization); the core's capitalized()
+        implements the single-case gate (v1 parity) -- not
+        re-implemented here."""
         self._resolve()
-        self._parsed = self._parsed.capitalized(self._lexicon, force=True)
+        if force is None:
+            force = self._C.force_mixed_case_capitalization
+        self._parsed = self._parsed.capitalized(self._lexicon, force=force)
 
     @property
     def full_name(self) -> str:
@@ -485,6 +491,17 @@ def group(items: list[str]) -> str:
             first=group(first), middle=group(middle), last=group(last))
         return self.collapse_whitespace(_s)
 
+    # -- comparison -----------------------------------------------------------
+
+    def matches(self, other: str | HumanName) -> bool:
+        """Component-wise case-insensitive comparison (v1 parity); a
+        str argument is parsed with this instance's resolved parser."""
+        target = other._parsed if isinstance(other, HumanName) else other
+        return self._parsed.matches(target, parser=self._resolve())
+
+    def comparison_key(self) -> tuple[str, ...]:
+        return self._parsed.comparison_key()
+
     # -- dunders ------------------------------------------------------------
 
     def collapse_whitespace(self, string: str) -> str:
@@ -535,3 +552,55 @@ def as_dict(self, include_empty: bool = True) -> dict[str, str]:
         if include_empty:
             return d
         return {k: v for k, v in d.items() if v}
+
+    # -- pickle (v1-shaped state; one path for 1.4 and 2.x blobs) -----------
+
+    def __getstate__(self) -> dict[str, Any]:
+        # The emitted key set matches v1.4's pickle shape (minus
+        # encoding/_had_comma/_derived_*, which are v1-internal and
+        # ignored on read), so one __setstate__ path serves both eras.
+        state: dict[str, Any] = {
+            "_full_name": self._full_name,
+            "original": self.original,
+            "C": None if self._C is CONSTANTS else self._C,
+            "string_format": self.string_format,
+            "initials_format": self.initials_format,
+            "initials_delimiter": self.initials_delimiter,
+            "initials_separator": self.initials_separator,
+            "suffix_delimiter": self.suffix_delimiter,
+        }
+        for member in _MEMBERS:
+            state[f"{member}_list"] = getattr(self, f"{member}_list")
+        return state
+
+    def __setstate__(self, state: dict[str, Any]) -> None:
+        c = state.get("C")
+        self._C = CONSTANTS if c is None else c
+        self._snapshot_gen = -1
+        defaults = self._C._snapshot()[2]
+        self._string_format = state.get("string_format",
+                                        defaults.string_format)
+        self._initials_format = state.get("initials_format",
+                                          defaults.initials_format)
+        self._initials_delimiter = state.get("initials_delimiter",
+                                             defaults.initials_delimiter)
+        self._initials_separator = state.get("initials_separator",
+                                             defaults.initials_separator)
+        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 = {}
+        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})

tests/v2/data/humanname_v14.pickle

@@ -1,11 +1,15 @@
 """The 2.0 HumanName facade (migration spec §2)."""
+import pickle
 import warnings
+from pathlib import Path
 
 import pytest
 
 from nameparser._config_shim import CONSTANTS, Constants
 from nameparser._facade import HumanName
 
+_DATA_DIR = Path(__file__).parent / "data"
+
 
 def test_basic_parse_and_v1_spellings() -> None:
     n = HumanName("Dr. Juan de la Vega III")
@@ -258,3 +262,66 @@ def test_render_default_setters_validate() -> None:
         n.suffix_delimiter = 5  # type: ignore[assignment]
     n.string_format = None                   # None allowed for these two
     n.suffix_delimiter = None
+
+
+def test_capitalize_gate_and_force() -> None:
+    n = HumanName("bob v. de la macdole-eisenhower phd")
+    n.capitalize()
+    assert str(n) == "Bob V. de la MacDole-Eisenhower Ph.D."
+    m = HumanName("Shirley Maclaine")        # mixed case: untouched
+    m.capitalize()
+    assert str(m) == "Shirley Maclaine"
+    m.capitalize(force=True)
+    assert str(m) == "Shirley MacLaine"
+
+
+def test_force_mixed_case_flag_feeds_default() -> None:
+    c = Constants()
+    c.force_mixed_case_capitalization = True
+    n = HumanName("Shirley Maclaine", constants=c)
+    n.capitalize()                           # force=None -> flag -> True
+    assert str(n) == "Shirley MacLaine"
+
+
+def test_matches_and_comparison_key() -> None:
+    # NB: the task spec's example compared "Dr. John A. Smith" against
+    # "John Smith" -- but matches()/comparison_key() are component-wise
+    # over all seven fields (v1 parity, verified against live 1.4), so a
+    # title/middle-initial mismatch always fails the match; swapped in
+    # case/order variations that actually exercise "case-insensitive,
+    # component-wise" without dropping fields.
+    n = HumanName("Dr. John A. Smith")
+    assert n.matches("dr. john a. smith")
+    assert n.matches(HumanName("smith, dr. john a."))
+    assert not n.matches("Jane Smith")
+    assert n.comparison_key() == HumanName("DR. JOHN A. SMITH").comparison_key()
+
+
+def test_pickle_round_trip_preserves_components() -> None:
+    n = HumanName("Dr. Juan de la Vega III")
+    n.first = "Johan"                        # mutated state must survive
+    loaded = pickle.loads(pickle.dumps(n))
+    assert loaded.first == "Johan"
+    assert loaded.last == "de la Vega"
+    assert loaded.original == "Dr. Juan de la Vega III"
+    assert loaded.C is CONSTANTS             # shared sentinel restored
+
+
+@pytest.mark.xfail(
+    reason="resolves to the v1 class until the M11 swap", strict=True)
+def test_v14_humanname_blob_unpickles() -> None:
+    # tests/v2/data/humanname_v14.pickle was produced by a real 1.4.0
+    # install (`uv run --no-project --with "nameparser==1.4.*" ...`) on
+    # HumanName("Dr. Juan de la Vega III"); components come back exactly
+    # as pickled, NOT re-parsed. Until the M11 swap replaces
+    # nameparser.parser.HumanName with this facade, the blob's pickled
+    # class reference still resolves to the live v1 class, so this
+    # assertion fails today by construction (mirrors
+    # test_v14_constants_blob_unpickles_into_shim in test_config_shim.py).
+    # pickle.load is safe here: humanname_v14.pickle is a repo-controlled
+    # fixture generated by this task from a real 1.4.0 install (Step 2
+    # above), not data from an untrusted source.
+    with open(_DATA_DIR / "humanname_v14.pickle", "rb") as f:
+        loaded = pickle.load(f)
+    assert isinstance(loaded, HumanName)
+    assert loaded.first == "Juan" and loaded.last == "de la Vega"