Apply the /simplify findings: snapshot caching, shared collapse, one PH/D

- Constants._snapshot() is generation-cached: rebuilding the Lexicon
  re-normalized ~1400 vocabulary entries (~185us) TWICE per
  HumanName() construction -- the legacy path ran ~428us/name against
  the core's ~35us. With the cache (plus _resolve() storing the
  resolved Parser instead of re-hashing the lru key per call) the
  facade is ~66us/name, a ~5us wrapper over the core. A facade-path
  benchmark test now exists so this regression class stays visible.
- HumanName.__str__ delegates its cleanup chain to _render._collapse
  (the #254 collapse has ONE owner; the facade layering row always
  allowed the import); collapse_whitespace keeps v1's narrower
  two-step contract over _render's regexes; the facade's three
  duplicate regex constants are gone.
- _MEMBERS derives from Role in the v1 spellings (declaration order
  is canonical, never restated).
- the fix_phd credential-pair regexes live once in _vocab, imported
  by segment and group (both are pipeline-internal; the keep-in-sync
  comment pair is gone).
- the inert per-token entry_open rewrite in group's tail loop is
  hoisted out (piece-level state, now visibly so).
- a cold-import regression test pins BOTH import orders around the
  _facade cycle-breaker (the load-bearing line an import-sort pass
  could otherwise silently reorder).

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

Author: derek73

nameparser/_config_shim.py

@@ -894,6 +894,19 @@ def __repr__(self) -> str:                            # #221
     # -- snapshot -----------------------------------------------------------
 
     def _snapshot(self) -> tuple[Lexicon, Policy, _RenderDefaults]:
+        # generation-keyed cache: rebuilding the Lexicon re-normalizes
+        # ~1400 vocabulary entries (~185us) -- the same dirty-tracking
+        # the facade uses, applied one level up. A pure read either way
+        # (no bump, no warning).
+        cached = getattr(self, "_snapshot_cache", None)
+        if cached is not None and cached[0] == self._generation:
+            return cached[1]  # type: ignore[no-any-return]
+        snapshot = self._build_snapshot()
+        object.__setattr__(
+            self, "_snapshot_cache", (self._generation, snapshot))
+        return snapshot
+
+    def _build_snapshot(self) -> tuple[Lexicon, Policy, _RenderDefaults]:
         """Resolve this v1-shaped, mutable Constants into the frozen
         2.0 value objects it corresponds to (spec §3). A pure read: no
         generation bump, no deprecation warning even on the shared

nameparser/_facade.py

@@ -7,7 +7,6 @@
 from __future__ import annotations
 
 import dataclasses
-import re
 import warnings
 from collections.abc import Iterator
 from typing import Any
@@ -28,19 +27,19 @@
 # still-executing __init__.
 import nameparser.config  # noqa: F401
 
+import nameparser._render as _render
 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
 
 _V2_FIELD = {"first": "given", "last": "family"}  # v1 name -> v2 name
-_MEMBERS = ("title", "first", "middle", "last", "suffix", "nickname",
-            "maiden")
+_V1_SPELLING = {v2: v1 for v1, v2 in _V2_FIELD.items()}
+# derived from Role: declaration order IS the canonical field order
+# (never restated), rendered in the v1 spellings
+_MEMBERS = tuple(_V1_SPELLING.get(r.value, r.value) for r in Role)
+
 
-_SPACES = re.compile(r"\s+")
-_SPACE_BEFORE_COMMA = re.compile(r"\s+,")
-# the three comma characters, same set as the pipeline's COMMA_CHARS
-_TRAILING_COMMA = re.compile(r"[,،，]$")
 
 #: v1 parsing hooks the facade never calls (spec §2 exception 2 / #280).
 _V1_HOOKS = (
@@ -230,8 +229,11 @@ def _resolve(self) -> Parser:
                     extra_suffix_delimiters=frozenset(
                         {self.suffix_delimiter}))
             self._lexicon, self._policy = lexicon, policy
+            self._parser = _cached_parser(lexicon, policy)
             self._snapshot_gen = gen
-        return _cached_parser(self._lexicon, self._policy)
+        # the fast path is a plain attribute return: hashing the two
+        # value objects for the lru lookup is the whole fast-path cost
+        return self._parser
 
     def parse_full_name(self) -> None:
         """Re-parse the stored ``full_name`` (v1's documented re-parse
@@ -572,19 +574,21 @@ def comparison_key(self) -> tuple[str, ...]:
     # -- dunders ------------------------------------------------------------
 
     def collapse_whitespace(self, string: str) -> str:
-        # v1 parser.py:976 verbatim (regexes.spaces / regexes.commas)
-        string = _SPACES.sub(" ", string.strip())
-        if string and _TRAILING_COMMA.search(string):
+        # v1 parser.py:976 verbatim, over _render's regexes (the #254
+        # collapse owns them; this public method keeps v1's narrower
+        # two-step contract for initials() and direct callers)
+        string = _render._SPACES.sub(" ", string.strip())
+        if string and _render._COMMA_CHAR.fullmatch(string[-1]):
             string = string[:-1]
         return string
 
     def __str__(self) -> str:
         if self.string_format is not None:
-            _s = self.string_format.format(
+            rendered = self.string_format.format(
                 **{k: v or "" for k, v in self.as_dict().items()})
-            _s = _s.replace(" ()", "").replace(" ''", "").replace(' ""', "")
-            _s = _SPACE_BEFORE_COMMA.sub(",", _s)
-            return self.collapse_whitespace(_s).strip(", ")
+            # the full #254 collapse is _render._collapse -- one owner
+            # for the cleanup chain the v1 __str__ spelled inline
+            return _render._collapse(rendered)
         return " ".join(self)
 
     def __repr__(self) -> str:

nameparser/_pipeline/_group.py

@@ -20,16 +20,16 @@
 from __future__ import annotations
 
 import dataclasses
-import re
 from collections.abc import Sequence, Set
 from enum import IntEnum
 
 from nameparser._pipeline._state import ParseState, Structure, WorkToken
+from nameparser._pipeline._vocab import D as _D
+from nameparser._pipeline._vocab import PH as _PH
 from nameparser._pipeline._vocab import delimiter_cores
 from nameparser._types import Role
 
-_PH = re.compile(r"^ph\.?$", re.IGNORECASE)
-_D = re.compile(r"^d\.?$", re.IGNORECASE)
+# the credential-pair regexes live in _vocab (shared with segment)
 
 Piece = list[int]
 
@@ -234,7 +234,8 @@ def group(state: ParseState) -> ParseState:
                     if entry_open or pos > 0:
                         tokens[i] = dataclasses.replace(
                             tokens[i], tags=tokens[i].tags | {"joined"})
-                    entry_open = True
+                # piece-level state: the NEXT piece continues this entry
+                entry_open = True
             if len(kept) != len(pieces):
                 pieces = [pieces[k] for k in kept]
                 ptags = [ptags[k] for k in kept]

nameparser/_pipeline/_segment.py

@@ -21,19 +21,18 @@
 
 import bisect
 import dataclasses
-import re
 
 from nameparser._pipeline._state import ParseState, PendingAmbiguity, Structure
 from nameparser._pipeline._vocab import (
+    D as _D,
+    PH as _PH,
     delimiter_cores, is_suffix_lenient, is_suffix_strict,
     period_joined_vocab, splits_into_suffixes,
 )
 from nameparser._types import AmbiguityKind
 
 
-# keep in sync with _group.py's merge pair (the fix_phd port)
-_PH = re.compile(r"^ph\.?$", re.IGNORECASE)
-_D = re.compile(r"^d\.?$", re.IGNORECASE)
+
 
 
 def segment(state: ParseState) -> ParseState:

nameparser/_pipeline/_vocab.py

@@ -117,3 +117,10 @@ def period_joined_vocab(text: str, lexicon: Lexicon) -> str | None:
            for c in chunks):
         return "suffix"
     return None
+
+
+# The fix_phd credential pair ('Ph.' + 'D.' as adjacent tokens), shared
+# by segment's suffix-comma detection and group's merge (v1 extracted
+# the credential pre-parse; the two stages must agree on the pattern).
+PH = re.compile(r"^ph\.?$", re.IGNORECASE)
+D = re.compile(r"^d\.?$", re.IGNORECASE)

tests/v2/test_benchmark.py

@@ -13,3 +13,16 @@ def test_parse_thousand_names_under_a_second() -> None:
         parse(f"Dr. Juan{i} de la Vega III")
     elapsed = time.perf_counter() - start
     assert elapsed < 1.0, f"1000 parses took {elapsed:.2f}s"
+
+
+def test_facade_thousand_names_under_a_second() -> None:
+    # the legacy-API path (what all existing users call): snapshot
+    # resolution must stay generation-cached, not rebuilt per instance
+    from nameparser import HumanName
+
+    HumanName("warm up the caches")
+    start = time.perf_counter()
+    for i in range(1000):
+        HumanName(f"Dr. Juan{i} de la Vega III")
+    elapsed = time.perf_counter() - start
+    assert elapsed < 1.0, f"1000 facade parses took {elapsed:.2f}s"

tests/v2/test_facade.py

@@ -431,3 +431,20 @@ def test_middle_as_family_list_view_matches_string_view() -> None:
     n = HumanName("Hassan, Mohamad Ahmad Ali", constants=c)
     assert n.last == "Ahmad Ali Hassan"
     assert n.last_list == ["Ahmad", "Ali", "Hassan"]
+
+
+def test_cold_import_order_config_first() -> None:
+    # the _facade cycle-breaker (import nameparser.config first) is
+    # order-dependent; this pins BOTH cold-start directions in fresh
+    # interpreters so an import-sorting pass cannot silently break one
+    import subprocess
+    import sys
+
+    for first in ("nameparser.config", "nameparser._facade"):
+        proc = subprocess.run(
+            [sys.executable, "-c",
+             f"import {first}; import nameparser; "
+             f"print(nameparser.HumanName('John Smith').last)"],
+            capture_output=True, text=True)
+        assert proc.returncode == 0, (first, proc.stderr)
+        assert proc.stdout.strip() == "Smith"