Add Lexicon.honorific_tails, the glued-peel vocabulary (#308)

derek73 · Jul 31, 2026 · Jul 31, 2026 · Jul 31, 2026 · Jul 31, 2026 · Jul 31, 2026
commit b9c58a29a1da890ba6fc4a92464165b348130ce9
diff --git a/nameparser/_config_shim.py b/nameparser/_config_shim.py
@@ -986,6 +986,7 @@ def _build_snapshot(self) -> tuple[Lexicon, Policy, _RenderDefaults]:
         removal path.
         """
         from nameparser.config.maiden_markers import MAIDEN_MARKERS
+        from nameparser.config.suffixes import GLUED_HONORIFICS
         from nameparser.config.surnames import KOREAN_SURNAMES
         acronyms = frozenset(self.suffix_acronyms)
         particles = frozenset(self.prefixes)
@@ -1068,6 +1069,9 @@ def _build_snapshot(self) -> tuple[Lexicon, Policy, _RenderDefaults]:
             # Unwrapped where maiden_markers above is wrapped: this
             # module is born frozen (#293), so no wrap
             surnames=KOREAN_SURNAMES,
+            # likewise no v1 manager: the glued-honorific tail set is
+            # 2.1 behavior (#308), so it rides in the snapshot only
+            honorific_tails=frozenset(GLUED_HONORIFICS),
             # TupleManager is dict[str, object] (v1 parity: values were
             # never statically str-typed); every real entry is a str,
             # same assumption _DelimiterManager's sentinel lookup makes

diff --git a/nameparser/_lexicon.py b/nameparser/_lexicon.py
@@ -24,6 +24,7 @@
     "titles", "given_name_titles", "suffix_acronyms", "suffix_words",
     "suffix_acronyms_ambiguous", "particles", "particles_ambiguous",
     "conjunctions", "bound_given_names", "maiden_markers", "surnames",
+    "honorific_tails",
 )
 
 #: (marker, base, why) triples. Each marker narrows how entries of its
@@ -335,6 +336,15 @@ class Lexicon:
     #: (:data:`~nameparser.config.surnames.KOREAN_SURNAMES`); Chinese
     #: surnames ship in locales.ZH because Han segmentation is opt-in.
     surnames: frozenset[str] = frozenset()
+    #: Honorifics that may be peeled off the END of a name token
+    #: (#308), matched longest-first: 田中さん splits into 田中 and さん
+    #: before anything else reads the name. Every entry must also be a
+    #: :attr:`suffix_words` entry -- the peeled tail is claimed by
+    #: suffix classification like any other post-nominal. Strictly
+    #: narrower than the spaced honorific vocabulary, since a glued
+    #: tail has no token boundary to lean on. Full default list:
+    #: :data:`~nameparser.config.suffixes.GLUED_HONORIFICS`.
+    honorific_tails: frozenset[str] = frozenset()
     #: Lowercase word -> exact-cased replacement used by capitalized()
     #: ("phd" -> "Ph.D."). Pair-valued: change it with
     #: dataclasses.replace(), not add()/remove(); read it as a mapping
@@ -577,7 +587,8 @@ def _default_lexicon() -> Lexicon:
     from nameparser.config.maiden_markers import MAIDEN_MARKERS
     from nameparser.config.prefixes import NON_FIRST_NAME_PREFIXES, PREFIXES
     from nameparser.config.suffixes import (
-        SUFFIX_ACRONYMS, SUFFIX_ACRONYMS_AMBIGUOUS, SUFFIX_NOT_ACRONYMS,
+        GLUED_HONORIFICS, SUFFIX_ACRONYMS, SUFFIX_ACRONYMS_AMBIGUOUS,
+        SUFFIX_NOT_ACRONYMS,
     )
     from nameparser.config.surnames import KOREAN_SURNAMES
     from nameparser.config.titles import FIRST_NAME_TITLES, TITLES
@@ -602,6 +613,7 @@ def _default_lexicon() -> Lexicon:
         # surnames.py is born frozen (#293) -- no call-site wrap needed,
         # unlike the v1 modules above (their wraps drop when #293 lands)
         surnames=KOREAN_SURNAMES,
+        honorific_tails=frozenset(GLUED_HONORIFICS),
         # pass canonical pair-tuples so this strictly-typed call site never
         # feeds a Mapping to the tuple-annotated field; __post_init__
         # still tolerates a Mapping at runtime for interactive use

diff --git a/tests/v2/test_lexicon.py b/tests/v2/test_lexicon.py
@@ -577,3 +577,13 @@ def test_default_lexicon_ships_korean_surnames_only() -> None:
     hangul = _SCRIPT_RANGES[Script.HANGUL]
     assert all(all(any(lo <= ord(c) <= hi for lo, hi in hangul) for c in s)
                and 1 <= len(s) <= 2 for s in lex.surnames)
+
+
+def test_honorific_tails_is_a_vocab_field() -> None:
+    lex = Lexicon.empty().add(honorific_tails={"씨", "さん"})
+    assert lex.honorific_tails == frozenset({"씨", "さん"})
+    assert lex.remove(honorific_tails={"씨"}).honorific_tails == \
+        frozenset({"さん"})
+    merged = (Lexicon(honorific_tails=frozenset({"씨"}))
+              | Lexicon(honorific_tails=frozenset({"様"})))
+    assert merged.honorific_tails == frozenset({"씨", "様"})