nameparser 2.0.0rc1__tar.gz → 2.1.0__tar.gz

{nameparser-2.0.0rc1/nameparser.egg-info → nameparser-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nameparser
-Version: 2.0.0rc1
+Version: 2.1.0
 Summary: A simple Python module for parsing human names into their individual components.
 Author-email: Derek Gulbranson <derek73@gmail.com>
 License: LGPL
@@ -22,6 +22,8 @@ Requires-Python: >=3.11
 Description-Content-Type: text/x-rst
 License-File: LICENSE
 License-File: AUTHORS
+Provides-Extra: ja
+Requires-Dist: namedivider-python>=0.4; extra == "ja"
 Dynamic: license-file
 
 Name Parser
@@ -33,6 +35,19 @@ nameparser parses human names into seven fields — title, given, middle,
 family, suffix, nickname, maiden. Results are immutable, configuration is
 composable, and locale packs are opt-in.
 
+📣 **nameparser 2.0 is out.** Existing ``HumanName`` code keeps working
+through 2.x, and most 1.x code needs no changes. The `migration guide
+<https://nameparser.readthedocs.io/en/latest/migrate.html>`__ has the
+field-by-field map. Please `open an issue
+<https://github.com/derek73/python-nameparser/issues>`__ for anything that
+parses wrong.
+
+**2.1 adds East Asian name support.** Chinese, Japanese and Korean names
+written in their own scripts are read family-first, unspaced Korean names
+are split against the census surname list, and CJK honorifics are
+recognized. See `East Asian names
+<https://nameparser.readthedocs.io/en/latest/usage.html#east-asian-names>`__.
+
 Installation
 ------------
 
@@ -48,16 +63,41 @@ Quick Start Example
 .. code-block:: python
 
     >>> from nameparser import parse
-    >>> name = parse("Dr. Juan Q. Xavier de la Vega III")
-    >>> name.given, name.family
-    ('Juan', 'de la Vega')
+    >>> name = parse("Dr. Juan Q. Xavier de la Vega III (Doc Vega)")
+    >>> name
+    <ParsedName: [
+        title: 'Dr.'
+        given: 'Juan'
+        middle: 'Q. Xavier'
+        family: 'de la Vega'
+        suffix: 'III'
+        nickname: 'Doc Vega'
+    ]>
+    >>> name.family_base, name.family_particles
+    ('Vega', 'de la')
     >>> name.render("{family}, {given}")
     'de la Vega, Juan'
 
-Those seven fields are ``title``, ``given``, ``middle``, ``family``,
-``suffix``, ``nickname``, and ``maiden`` — plus aggregate views like
-``given_names``, ``surnames``, ``family_base``, and ``family_particles``
-for combining or splitting them further.
+    >>> parse("김민준").family                     # Korean: unspaced, split on the census list
+    '김'
+    >>> parse("高橋 みなみ").family                 # Japanese: kanji with kana, family first
+    '高橋'
+    >>> parse("김민준씨").suffix                   # an honorific written against the name
+    '씨'
+    >>> parse("г-н Иван Петров").title             # Cyrillic title
+    'г-н'
+    >>> parse("محمد بن سلمان").family              # Arabic: بن chains onto the family name
+    'بن سلمان'
+
+    >>> from nameparser import locales, parser_for
+    >>> chinese = parser_for(locales.ZH)           # Han text does not say which language
+    >>> chinese.parse("毛泽东").family              # so splitting it is opt-in
+    '毛'
+    >>> russian = parser_for(locales.RU)
+    >>> russian.parse("Сидоров Иван Петрович").family
+    'Сидоров'
+    >>> locales.available()
+    ('ja', 'ru', 'tr_az', 'zh')
 
 Learn more
 ----------

{nameparser-2.0.0rc1 → nameparser-2.1.0}/README.rst

@@ -7,6 +7,19 @@ nameparser parses human names into seven fields — title, given, middle,
 family, suffix, nickname, maiden. Results are immutable, configuration is
 composable, and locale packs are opt-in.
 
+📣 **nameparser 2.0 is out.** Existing ``HumanName`` code keeps working
+through 2.x, and most 1.x code needs no changes. The `migration guide
+<https://nameparser.readthedocs.io/en/latest/migrate.html>`__ has the
+field-by-field map. Please `open an issue
+<https://github.com/derek73/python-nameparser/issues>`__ for anything that
+parses wrong.
+
+**2.1 adds East Asian name support.** Chinese, Japanese and Korean names
+written in their own scripts are read family-first, unspaced Korean names
+are split against the census surname list, and CJK honorifics are
+recognized. See `East Asian names
+<https://nameparser.readthedocs.io/en/latest/usage.html#east-asian-names>`__.
+
 Installation
 ------------
 
@@ -22,16 +35,41 @@ Quick Start Example
 .. code-block:: python
 
     >>> from nameparser import parse
-    >>> name = parse("Dr. Juan Q. Xavier de la Vega III")
-    >>> name.given, name.family
-    ('Juan', 'de la Vega')
+    >>> name = parse("Dr. Juan Q. Xavier de la Vega III (Doc Vega)")
+    >>> name
+    <ParsedName: [
+        title: 'Dr.'
+        given: 'Juan'
+        middle: 'Q. Xavier'
+        family: 'de la Vega'
+        suffix: 'III'
+        nickname: 'Doc Vega'
+    ]>
+    >>> name.family_base, name.family_particles
+    ('Vega', 'de la')
     >>> name.render("{family}, {given}")
     'de la Vega, Juan'
 
-Those seven fields are ``title``, ``given``, ``middle``, ``family``,
-``suffix``, ``nickname``, and ``maiden`` — plus aggregate views like
-``given_names``, ``surnames``, ``family_base``, and ``family_particles``
-for combining or splitting them further.
+    >>> parse("김민준").family                     # Korean: unspaced, split on the census list
+    '김'
+    >>> parse("高橋 みなみ").family                 # Japanese: kanji with kana, family first
+    '高橋'
+    >>> parse("김민준씨").suffix                   # an honorific written against the name
+    '씨'
+    >>> parse("г-н Иван Петров").title             # Cyrillic title
+    'г-н'
+    >>> parse("محمد بن سلمان").family              # Arabic: بن chains onto the family name
+    'بن سلمان'
+
+    >>> from nameparser import locales, parser_for
+    >>> chinese = parser_for(locales.ZH)           # Han text does not say which language
+    >>> chinese.parse("毛泽东").family              # so splitting it is opt-in
+    '毛'
+    >>> russian = parser_for(locales.RU)
+    >>> russian.parse("Сидоров Иван Петрович").family
+    'Сидоров'
+    >>> locales.available()
+    ('ja', 'ru', 'tr_az', 'zh')
 
 Learn more
 ----------

{nameparser-2.0.0rc1 → nameparser-2.1.0}/nameparser/__init__.py

@@ -11,6 +11,7 @@ from nameparser._locale import Locale
 from nameparser._parser import Parser, parse, parser_for
 from nameparser._policy import (
     DEFAULT_NICKNAME_DELIMITERS,
+    DEFAULT_SCRIPT_ORDERS,
     FAMILY_FIRST,
     FAMILY_FIRST_GIVEN_LAST,
     GIVEN_FIRST,
@@ -18,12 +19,16 @@ from nameparser._policy import (
     PatronymicRule,
     Policy,
     PolicyPatch,
+    Script,
 )
 from nameparser._types import (
+    STABLE_TAGS,
     Ambiguity,
     AmbiguityKind,
     ParsedName,
     Role,
+    Segmentation,
+    Segmenter,
     Span,
     Token,
 )
@@ -33,8 +38,9 @@ __all__ = [
     "HumanName",
     # v2 core
     "Span", "Role", "Token", "Ambiguity", "AmbiguityKind", "ParsedName",
-    "Lexicon", "Policy", "PolicyPatch", "PatronymicRule", "UNSET",
+    "STABLE_TAGS", "Segmentation", "Segmenter",
+    "Lexicon", "Policy", "PolicyPatch", "PatronymicRule", "Script", "UNSET",
     "GIVEN_FIRST", "FAMILY_FIRST", "FAMILY_FIRST_GIVEN_LAST",
-    "DEFAULT_NICKNAME_DELIMITERS", "Locale",
+    "DEFAULT_NICKNAME_DELIMITERS", "DEFAULT_SCRIPT_ORDERS", "Locale",
     "Parser", "parse", "parser_for",
 ]

{nameparser-2.0.0rc1 → nameparser-2.1.0}/nameparser/_config_shim.py

@@ -33,6 +33,28 @@ from nameparser._policy import PatronymicRule, Policy
 from nameparser.util import lc
 
 
+#: The eight multi-word entries the pre-2.0 DEFAULT vocabulary shipped.
+#: Provably inert in every release (they can never match; see the
+#: 2.0.0 release log), so dropping them from a restored legacy pickle
+#: changes no parse -- and keeps the multi-word warning from firing
+#: eight times, with wrong advice, at library-internal lines, on the
+#: first parse after a supported 1.3/1.4 pickle upgrade.
+#:
+#: Gated on ALL EIGHT being present across the two fields -- the
+#: signature of a pre-2.0 blob, which froze the complete shipped set.
+#: A round-trip of 2.0-era state that carries FEWER than all eight
+#: keeps them (a user who deliberately re-added one or two does not
+#: match the signature, and .copy() never subtracts either). The trade:
+#: a 2.0 user who re-adds ALL eight exact strings is indistinguishable
+#: from a legacy blob and loses them on the next unpickle.
+_LEGACY_DEAD_ENTRIES = {
+    "titles": frozenset({"chargé d'affaires"}),
+    "suffix_acronyms": frozenset({
+        "leed ap", "nicet i", "nicet ii", "nicet iii", "nicet iv",
+        "psm i", "psm ii"}),
+}
+
+
 def _reject_bare_str_or_bytes(value: object, expected: str) -> None:
     # A bare string is an iterable of its characters, so e.g. SetManager('dr')
     # would silently shred it into {'d', 'r'} instead of raising -- shared by
@@ -964,10 +986,23 @@ class Constants:
         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)
         bound = frozenset(self.bound_first_names)
         ambiguous_acronyms = frozenset(self.suffix_acronyms_ambiguous) & acronyms
+        # Drop any ambiguous acronym from the word set rather than the
+        # other way round. Lexicon forbids the overlap because the word
+        # branch bypasses the period gate, and adding an ambiguous
+        # acronym to suffix_not_acronyms is INERT in v1 anyway:
+        # is_suffix already accepts it via the acronym branch, and
+        # reserve_last keeps it as the surname. So ignoring the
+        # addition reproduces v1 ("Jack Ma" keeps last='Ma'), where
+        # dropping it from the AMBIGUOUS set instead ungated the word
+        # and lost the family name -- a silent misparse worse than the
+        # raise it avoided.
+        suffix_words = frozenset(self.suffix_not_acronyms) - ambiguous_acronyms
         # keep in sync with _lexicon._default_lexicon() (pinned by
         # tests/v2/test_config_shim.py::test_snapshot_field_translation)
         lexicon = Lexicon(
@@ -994,18 +1029,7 @@ class Constants:
                     if e == " ".join(e.split())
                 ) if t),
             suffix_acronyms=acronyms,
-            # Drop any ambiguous acronym from the word set rather than
-            # the other way round. Lexicon forbids the overlap because
-            # the word branch bypasses the period gate, and adding an
-            # ambiguous acronym to suffix_not_acronyms is INERT in v1
-            # anyway: is_suffix already accepts it via the acronym
-            # branch, and reserve_last keeps it as the surname. So
-            # ignoring the addition reproduces v1 ("Jack Ma" keeps
-            # last='Ma'), where dropping it from the AMBIGUOUS set
-            # instead ungated the word and lost the family name --
-            # a silent misparse worse than the raise it avoided.
-            suffix_words=frozenset(
-                self.suffix_not_acronyms) - ambiguous_acronyms,
+            suffix_words=suffix_words,
             # Intersect with acronyms: Lexicon enforces ambiguous <=
             # acronyms; v1 behaves the same when an acronym is deleted
             # but its ambiguous entry lingers (the entry stops
@@ -1039,6 +1063,22 @@ class Constants:
             # v1 Constants has no manager for these (#274 is 2.0
             # behavior); the data module is the only source
             maiden_markers=frozenset(MAIDEN_MARKERS),
+            # likewise no v1 manager: the unspaced-name segmentation
+            # vocabulary is 2.0 behavior (#271), so it rides in the
+            # snapshot only -- v1's Constants surface stays frozen.
+            # 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.
+            # Wrapped, unlike surnames above: suffixes.py is still a
+            # mutable v1 module, not born-frozen like surnames.py
+            # (#293). Intersect with the word set: Lexicon enforces
+            # tails <= suffix_words, and v1 semantics are that deleting
+            # a suffix word turns the behavior off -- a lingering tail
+            # simply stops mattering, the same rule ambiguous_acronyms
+            # gets against suffix_acronyms above.
+            honorific_tails=frozenset(GLUED_HONORIFICS) & suffix_words,
             # 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
@@ -1103,10 +1143,30 @@ class Constants:
         self.__init__()  # type: ignore[misc]  # defaults, then overlay
         # (managers re-wrapped below so _on_change points at THIS
         # instance, not whatever produced the incoming state)
+        managers: dict[str, SetManager] = {}
         for name in _SET_FIELDS:
             if name in state:
-                object.__setattr__(self, name, SetManager(
-                    state[name], _on_change=self._bump))  # type: ignore[arg-type]
+                managers[name] = SetManager(
+                    state[name], _on_change=self._bump)  # type: ignore[arg-type]
+        # SetManager normalized on construction, so the frozen 1.3/1.4
+        # vocabulary's dead entries are matchable in their normalized
+        # spelling here. Subtract only when ALL EIGHT are present --
+        # the pre-2.0 signature; a 2.0 user who re-added one or two
+        # keeps them through a round-trip (see _LEGACY_DEAD_ENTRIES).
+        legacy = all(
+            name in managers and entry in managers[name]
+            for name, entries in _LEGACY_DEAD_ENTRIES.items()
+            for entry in entries
+        )
+        for name, manager in managers.items():
+            if legacy:
+                # Reach past the public discard() deliberately: this is
+                # part of restoring the state, not a mutation of it, and
+                # must not bump the generation of an instance that is
+                # still being built.
+                manager._elements -= _LEGACY_DEAD_ENTRIES.get(
+                    name, frozenset())
+            object.__setattr__(self, name, manager)
         if "capitalization_exceptions" in state:
             object.__setattr__(
                 self, "capitalization_exceptions", TupleManager(

{nameparser-2.0.0rc1 → nameparser-2.1.0}/nameparser/_facade.py

@@ -335,6 +335,8 @@ class HumanName:
         else:
             raise TypeError(
                 f"{member} must be a str, list, or None, got {value!r}")
+        # v1 setters stay on replace(): revise()'s vocabulary tags would
+        # change v1 parity
         self._parsed = self._parsed.replace(
             **{_V2_FIELD.get(member, member): joined})
 
@@ -616,7 +618,28 @@ class HumanName:
                 "slicing a HumanName was removed in 2.0 (#258); access "
                 "the named attributes instead"
             )
-        return getattr(self, key)
+        # Role is a StrEnum, so Role members (and the plain 'given'/
+        # 'family' strings) reach here too -- translate to the v1
+        # spelling the facade actually exposes as attributes.
+        return getattr(self, _V1_SPELLING.get(key, key))
+
+    def __setattr__(self, name: str, value: object) -> None:
+        # "given"/"family" are the 2.0 spellings of first/last; the
+        # facade has no such attributes, so plain assignment creates a
+        # stray instance attribute while the parse (and .first/.last)
+        # keeps the old value -- a silently forked name. Warn but
+        # still set: ad-hoc attribute stashing is a legal v1 pattern,
+        # so any code that worked keeps working. Only these two names
+        # warn -- the other five 2.0 field names are real properties
+        # whose setters work, and Role members reach here as their
+        # string values (StrEnum).
+        if name in _V1_SPELLING:
+            warnings.warn(
+                f"assigning HumanName.{name} creates an inert attribute; "
+                f"the parse is unchanged -- use .{_V1_SPELLING[name]} "
+                f"(the v1 spelling) to update the name",
+                UserWarning, stacklevel=2)
+        super().__setattr__(name, value)
 
     def as_dict(self, include_empty: bool = True) -> dict[str, str]:
         """The seven v1-named components as a dict; include_empty=False

{nameparser-2.0.0rc1 → nameparser-2.1.0}/nameparser/_lexicon.py

@@ -9,9 +9,11 @@ from __future__ import annotations
 
 import dataclasses
 import functools
+import sys
+import warnings
 from collections.abc import Iterable, Mapping
 from dataclasses import dataclass, field
-from types import MappingProxyType
+from types import FrameType, MappingProxyType
 from typing import cast
 
 #: Vocabulary set fields, in declaration order. add()/remove() operate
@@ -21,20 +23,44 @@ from typing import cast
 _VOCAB_FIELDS = (
     "titles", "given_name_titles", "suffix_acronyms", "suffix_words",
     "suffix_acronyms_ambiguous", "particles", "particles_ambiguous",
-    "conjunctions", "bound_given_names", "maiden_markers",
+    "conjunctions", "bound_given_names", "maiden_markers", "surnames",
+    "honorific_tails",
 )
 
-#: (marker, base, why) triples. Each marker narrows how entries of its
-#: base vocabulary are read and carries no vocabulary of its own, so an
-#: entry outside the base is a configuration mistake -- but the mistake
-#: differs per pair, and the reason is recorded here rather than
-#: generalized, because an orphan is NOT simply inert:
+#: (marker, base, why) triples. Each marker QUALIFIES how entries of
+#: its base vocabulary are read and carries no vocabulary of its own,
+#: so an entry outside the base is a configuration mistake -- but the
+#: mistake differs per pair, and the reason is recorded here rather
+#: than generalized, because an orphan is NOT simply inert. Nor is the
+#: qualification one-directional: the first two NARROW their base (an
+#: entry is read as vocabulary in fewer places), while honorific_tails
+#: WIDENS it, granting a suffix word the glued position on top of the
+#: whole-token match every suffix word already gets.
 #:
 #: * particles_ambiguous: _assign keys on the tag alone, so an orphan
 #:   makes the parse emit a spurious particle-or-given ambiguity.
 #: * suffix_acronyms_ambiguous: _vocab returns True on the ambiguous
 #:   set before testing suffix_acronyms, so an orphan silently turns a
 #:   word into a period-gated suffix.
+#: * honorific_tails: script_segment peels the tail into its own token
+#:   before classify ever runs, so an orphan splits the name and leaves
+#:   the fragment stranded inside it -- worse than not peeling at all.
+#:   Its base is deliberately NARROWER than what actually claims the
+#:   peeled piece: suffix_as_written ORs suffix_words with the
+#:   non-ambiguous suffix_acronyms, so a tail listed only as an acronym
+#:   would classify fine yet is rejected here. Accepted, and a decision
+#:   rather than an oversight -- the three-term predicate is easy to
+#:   get wrong in the dangerous direction (an ambiguous acronym admitted
+#:   as a tail would peel a period-gated word off a real name), and
+#:   nothing needs the acronym half: the shipped tails are CJK
+#:   honorifics, which are words.
+#:   The same relation is asserted a second time in config/suffixes.py,
+#:   over the raw GLUED_HONORIFICS/SUFFIX_NOT_ACRONYMS constants at
+#:   import. The two are not redundant in the way they look: that one
+#:   is an `assert`, stripped under `python -O`, while the check here
+#:   raises unconditionally -- so under -O this is what still holds the
+#:   SHIPPED vocabulary to the invariant, as it is the only thing that
+#:   ever held a caller's own.
 #:
 #: given_name_titles is deliberately NOT here and has no check of its
 #: own -- see the note in __post_init__ for why every attempt at one
@@ -44,6 +70,8 @@ _SUBSET_FIELDS = (
      "an orphan emits a spurious particle-or-given ambiguity"),
     ("suffix_acronyms_ambiguous", "suffix_acronyms",
      "an orphan silently becomes a period-gated suffix"),
+    ("honorific_tails", "suffix_words",
+     "an orphan splits the name and leaves the tail inside it"),
 )
 
 
@@ -112,7 +140,27 @@ def _reject_buffer(value: object, label: str, plural: str) -> None:
         )
 
 
-def _normset(entries: Iterable[str], field_name: str) -> frozenset[str]:
+def _warn_dead_entry(message: str) -> None:
+    # A fixed stacklevel always lands on library internals: the call
+    # depth differs per entry point (Lexicon(), add(), unpickle,
+    # dataclasses.replace, and the v1 shim's lazy snapshot -- built on
+    # the first parse after a Constants mutation, several facade frames
+    # below the user's own add()). Walk out of this module (and
+    # dataclasses' replace frames, and the facade layer that builds
+    # lexicons on the caller's behalf) so the warning points at the
+    # caller's own line.
+    level = 2
+    frame: FrameType | None = sys._getframe(1)
+    while frame is not None and frame.f_globals.get("__name__") in (
+            __name__, "dataclasses",
+            "nameparser._config_shim", "nameparser._facade"):
+        frame, level = frame.f_back, level + 1
+    warnings.warn(message, UserWarning, stacklevel=level)
+
+
+def _normset(
+    entries: Iterable[str], field_name: str, warn: bool = True,
+) -> frozenset[str]:
     # Reject a bare str before iterating: iterating "dr" would silently
     # yield the single characters {'d', 'r'} -- the set(str) footgun on
     # the primary customization surface.
@@ -159,6 +207,25 @@ def _normset(entries: Iterable[str], field_name: str) -> frozenset[str]:
                 f"Lexicon.{field_name} entry {w!r} normalizes to empty "
                 f"(lowercase + strip periods/whitespace leaves nothing)"
             )
+        # Every field but given_name_titles is matched one word at a
+        # time, so a multi-word entry can never match -- the library
+        # itself shipped eight such dead entries for years (repaired
+        # 2026-07-26). Warn, never raise: an inert entry produces
+        # nothing, and the given_name_titles precedent says a raise
+        # here costs working configurations (see __post_init__).
+        # warn=False is _edit()'s pass (both ops): add() warns via the
+        # new instance's __post_init__; remove() stores nothing, so
+        # warning there would name entries the caller is trying to get
+        # RID of, with "split it" advice that makes no sense for a
+        # no-op.
+        if (warn and field_name != "given_name_titles"
+                # interior whitespace test; split() covers all Unicode
+                # whitespace
+                and n != "".join(n.split())):
+            _warn_dead_entry(
+                f"Lexicon.{field_name} entries are matched one word at "
+                f"a time; multi-word entry {w!r} can never match. "
+                f"Split it into separate entries")
         normalized.add(n)
     return frozenset(normalized)
 
@@ -214,6 +281,14 @@ def _normpairs(
                 f"empty (lowercase + strip periods/whitespace leaves "
                 f"nothing)"
             )
+        # capitalized() looks words up one at a time (the _WORD regex
+        # never yields spaces), so a multi-word key is unreachable.
+        # interior whitespace test; split() covers all Unicode whitespace
+        if normalized_key != "".join(normalized_key.split()):
+            _warn_dead_entry(
+                f"capitalization_exceptions keys are matched one word "
+                f"at a time; multi-word key {k!r} can never match. "
+                f"Split it into per-word entries")
         deduped[normalized_key] = v
     return tuple(sorted(deduped.items()))
 
@@ -226,9 +301,12 @@ class Lexicon:
     :meth:`empty`, derive variants with :meth:`add` / :meth:`remove` /
     ``|`` (union), and pass the result to ``Parser(lexicon=...)``.
     Entries are normalized at construction -- lowercased, edge periods
-    stripped -- so matching is case-insensitive. Field docs below show
-    examples, not full contents; inspect any field's shipped vocabulary
-    directly, e.g. ``Lexicon.default().conjunctions``."""
+    stripped -- so matching is case-insensitive. Vocabulary entries are
+    single words -- a multi-word entry warns at construction and can
+    never match (``given_name_titles``, matched as a space-joined run,
+    is the one exception). Field docs below show examples, not full
+    contents; inspect any field's shipped vocabulary directly, e.g.
+    ``Lexicon.default().conjunctions``."""
 
     #: Pre-nominal titles ("dr", "sir", "capt", ...). Full default
     #: list: :data:`~nameparser.config.titles.TITLES`.
@@ -256,7 +334,8 @@ class Lexicon:
     particles: frozenset[str] = frozenset()
     #: Subset of particles that can also BE a given name: a leading
     #: one reads as given and records a particle-or-given ambiguity
-    #: ("Van Johnson"). No constant of its own -- the default derives
+    #: ("Van Johnson", but also "Van Buren"). No constant of its own
+    #: -- the default derives
     #: as particles minus
     #: :data:`~nameparser.config.prefixes.NON_FIRST_NAME_PREFIXES`
     #: (which marks the opposite, never-given subset).
@@ -274,6 +353,31 @@ class Lexicon:
     #: field ("née", "geb.", "roz.", ...). Full default list:
     #: :data:`~nameparser.config.maiden_markers.MAIDEN_MARKERS`.
     maiden_markers: frozenset[str] = frozenset()
+    #: Family names for the unspaced-name segmentation stage (#271),
+    #: matched longest-first against the start of the FIRST token
+    #: written wholly in a script :attr:`Policy.segment_scripts
+    #: <nameparser.Policy.segment_scripts>` activates. The default
+    #: carries the Korean census list
+    #: (: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 the tokens are classified. Every entry must also be a
+    #: :attr:`suffix_words` entry -- the peeled tail is claimed by
+    #: suffix classification like any other post-nominal. Deliberately
+    #: NOT gated on :attr:`Policy.segment_scripts
+    #: <nameparser.Policy.segment_scripts>` (unlike :attr:`surnames`
+    #: above): 田中さん peels under the default policy, where HAN is in
+    #: no activation set, because a tail entry carries its own license
+    #: to fire. Entries are matched against the RAW token text, and
+    #: only within a name containing a non-ASCII character, so an ASCII
+    #: or mixed-case entry is at best conditionally active -- a ``"Jr"``
+    #: entry is stored ``"jr"`` and matches only lowercase text. The
+    #: field is effectively CJK-scoped in 2.1, which is what the shipped
+    #: vocabulary is. 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
@@ -479,7 +583,17 @@ class Lexicon:
                     f"{', '.join(_VOCAB_FIELDS)}"
                 )
             current: frozenset[str] = getattr(self, name)
-            normalized = _normset(words, name)
+            # warn=False: this pass only computes the new set membership,
+            # never stores it directly. add() still warns exactly once,
+            # from the replaced instance's own __post_init__ -> _normset;
+            # remove() never reaches __post_init__ with the dead entry
+            # (it is subtracted out here), so it stays silent -- correct,
+            # since a removal stores nothing a warning could be about.
+            # That silence covers the entry BEING REMOVED only: a
+            # different multi-word entry still stored re-warns from the
+            # derived instance's __post_init__, since the warning is
+            # per-construction by design.
+            normalized = _normset(words, name, warn=False)
             updates[name] = (current | normalized if op == "add"
                              else current - normalized)
         # mypy's dataclasses.replace() typing checks a **dict's single
@@ -506,8 +620,10 @@ 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
 
     # v1 data modules export plain `set[str]`; wrap each at this call site
@@ -527,6 +643,10 @@ def _default_lexicon() -> Lexicon:
         conjunctions=frozenset(CONJUNCTIONS),
         bound_given_names=frozenset(BOUND_FIRST_NAMES),
         maiden_markers=frozenset(MAIDEN_MARKERS),
+        # 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