nameparser 2.1.0__tar.gz → 2.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nameparser
-Version: 2.1.0
+Version: 2.2.0
 Summary: A simple Python module for parsing human names into their individual components.
 Author-email: Derek Gulbranson <derek73@gmail.com>
 License: LGPL
@@ -75,6 +75,8 @@ Quick Start Example
     ]>
     >>> name.family_base, name.family_particles
     ('Vega', 'de la')
+    >>> name.given_names, name.surnames
+    ('Juan Q. Xavier', 'Q. Xavier de la Vega')
     >>> name.render("{family}, {given}")
     'de la Vega, Juan'
 

{nameparser-2.1.0 → nameparser-2.2.0}/README.rst

@@ -47,6 +47,8 @@ Quick Start Example
     ]>
     >>> name.family_base, name.family_particles
     ('Vega', 'de la')
+    >>> name.given_names, name.surnames
+    ('Juan Q. Xavier', 'Q. Xavier de la Vega')
     >>> name.render("{family}, {given}")
     'de la Vega, Juan'
 

{nameparser-2.1.0 → nameparser-2.2.0}/nameparser/__main__.py

@@ -1,4 +1,4 @@
-"""Command-line debug helper over the 2.0 API (migration spec §6).
+"""Command-line debug helper over the 2.0 API.
 
     python -m nameparser "Dr. Juan Q. Xavier de la Vega III"
     python -m nameparser --json "Doe, John"

{nameparser-2.1.0 → nameparser-2.2.0}/nameparser/_config_shim.py

@@ -1,5 +1,6 @@
-"""v1 ``Constants`` compatibility shim over Lexicon/Policy (migration
-spec §3). ``nameparser.config`` re-exports these names from the swap
+"""v1 ``Constants`` compatibility shim over Lexicon/Policy
+(mechanisms.md#CONFIG-SHIM-SNAPSHOT). ``nameparser.config``
+re-exports these names from the swap
 commit onward; the whole module is deleted in 3.0 with the facade.
 
 Layering: facade layer -- may import anything public; here that's
@@ -99,7 +100,7 @@ def _normalize_iterable_of_strings(
 class SetManager:
     """v1 ``SetManager`` surface over a plain set of ``lc()``-normalized
     strings. Mutations call ``_on_change`` (the owning Constants'
-    generation bump, wired by a later task). ``__call__`` and the
+    generation bump, wired by the facade). ``__call__`` and the
     missing-member-tolerant ``remove()`` are gone per the #243 schedule
     (warned 1.3.0, removed 2.0): ``remove()`` of a missing member raises
     ``KeyError``, matching ``set.remove``.
@@ -316,7 +317,7 @@ class TupleManager(dict[str, object]):
     ``AttributeError`` naming the key (#256, warned 1.4, enforced 2.0 --
     the v1 ``DeprecationWarning`` is gone, this shim only speaks 2.0).
     Mutations call ``_on_change`` (the owning Constants' generation
-    bump, wired by a later task).
+    bump, wired by the facade).
     """
 
     _on_change: Callable[[], None] | None
@@ -431,7 +432,7 @@ class TupleManager(dict[str, object]):
 
 
 #: The named delimiter buckets, translated to the ``Policy``
-#: (open, close) pairs they stand for (spec §3). The first three are
+#: (open, close) pairs they stand for. The first three are
 #: v1's; the rest are the #273 typographic conventions, named so the
 #: v1 keyed idioms (pop/move/del) work on them like the originals.
 #: Keep in sync with DEFAULT_NICKNAME_DELIMITERS in _policy.py (pinned
@@ -472,8 +473,8 @@ class RegexTupleManager(TupleManager):  # pickle-compat: do NOT delete
 
 class _DelimiterManager(TupleManager):
     """v1 ``nickname_delimiters``/``maiden_delimiters`` bucket. In 2.0
-    only the named sentinels in ``_DELIMITER_SENTINELS`` exist (spec
-    §3; the v1 trio plus the #273 typographic pairs) -- assigning any
+    only the named sentinels in ``_DELIMITER_SENTINELS`` exist (the v1
+    trio plus the #273 typographic pairs) -- assigning any
     other key raises so a caller reaches for a custom-delimiter Policy
     kwarg instead of a dict entry that silently does nothing. ``pop()``/
     ``__setitem__``/``__delitem__`` stay open (inherited) for the
@@ -517,7 +518,7 @@ class _RegexesProxy:
     ``CONSTANTS.regexes.word`` stays informational -- but 2.0 configures
     parsing behavior through named ``Policy`` flags, not by mutating a
     regex, so any attribute *or* item assignment raises ``TypeError``
-    (spec §3's uniform read-only rule).
+    (the shim's uniform read-only rule).
     """
 
     @staticmethod
@@ -664,36 +665,38 @@ _SHARED_MUTATION_MESSAGE = (
 )
 
 
-def _default_vocab() -> dict[str, set[str]]:
+def _default_vocab() -> dict[str, frozenset[str]]:
     # v1 data modules stay the single vocabulary source through 2.x
     # (same rule as Lexicon.default()).
-    from nameparser.config.bound_first_names import BOUND_FIRST_NAMES
+    from nameparser.config.bound_given_names import BOUND_GIVEN_NAMES
     from nameparser.config.conjunctions import CONJUNCTIONS
-    from nameparser.config.prefixes import (
-        NON_FIRST_NAME_PREFIXES, PREFIXES,
+    from nameparser.config.particles import (
+        NON_GIVEN_NAME_PARTICLES, PARTICLES,
     )
     from nameparser.config.suffixes import (
-        SUFFIX_ACRONYMS, SUFFIX_ACRONYMS_AMBIGUOUS, SUFFIX_NOT_ACRONYMS,
+        SUFFIX_ACRONYMS, SUFFIX_ACRONYMS_AMBIGUOUS, SUFFIX_WORDS,
     )
-    from nameparser.config.titles import FIRST_NAME_TITLES, TITLES
+    from nameparser.config.titles import GIVEN_NAME_TITLES, TITLES
     return {
-        "prefixes": PREFIXES,
+        "prefixes": PARTICLES,
         "suffix_acronyms": SUFFIX_ACRONYMS,
-        "suffix_not_acronyms": SUFFIX_NOT_ACRONYMS,
+        "suffix_not_acronyms": SUFFIX_WORDS,
         "suffix_acronyms_ambiguous": SUFFIX_ACRONYMS_AMBIGUOUS,
         "titles": TITLES,
-        "first_name_titles": FIRST_NAME_TITLES,
+        "first_name_titles": GIVEN_NAME_TITLES,
         "conjunctions": CONJUNCTIONS,
-        "bound_first_names": BOUND_FIRST_NAMES,
-        "non_first_name_prefixes": NON_FIRST_NAME_PREFIXES,
+        "bound_first_names": BOUND_GIVEN_NAMES,
+        "non_first_name_prefixes": NON_GIVEN_NAME_PARTICLES,
     }
 
 
 class _RenderDefaults(NamedTuple):
     """v1 scalar rendering knobs that have no home on ``Policy``
-    (spec §3): ``__str__``/initials formatting and capitalization stay
+    (mechanisms.md#CONFIG-SHIM-SNAPSHOT): ``__str__``/initials
+    formatting and capitalization stay
     per-Constants defaults, layered onto a shared ``Parser`` by the
-    facade (a later task) rather than folded into the cache key."""
+    facade (nameparser/_facade.py) rather than folded into the cache
+    key."""
 
     string_format: str | None
     initials_format: str
@@ -707,7 +710,8 @@ class _RenderDefaults(NamedTuple):
 @functools.lru_cache(maxsize=64)
 def _cached_parser(lexicon: Lexicon, policy: Policy) -> Parser:
     # keyed on hashable value objects: shared across every facade whose
-    # Constants resolve to the same snapshot (spec §3)
+    # Constants resolve to the same snapshot
+    # (mechanisms.md#CONFIG-SHIM-SNAPSHOT)
     return Parser(lexicon=lexicon, policy=policy)
 
 
@@ -716,8 +720,8 @@ class Constants:
     a frozen ``(Lexicon, Policy, _RenderDefaults)`` snapshot via
     ``_snapshot()``. ``_generation`` increments on every mutation;
     facades compare it against a cached value to decide whether their
-    snapshot is stale (dirty-tracking, spec §3 -- the facade itself is
-    a later task).
+    snapshot is stale (dirty-tracking -- the facade side lives in
+    nameparser/_facade.py).
 
     The module-level ``CONSTANTS`` singleton (below) has ``_shared``
     flipped to ``True``: any mutation reached through it emits
@@ -980,7 +984,7 @@ class Constants:
 
     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
+        2.0 value objects it corresponds to. A pure read: no
         generation bump, no deprecation warning even on the shared
         singleton -- only direct attribute mutation is on the 3.0
         removal path.
@@ -1038,9 +1042,9 @@ class Constants:
             particles=particles,
             # complement translation: v1 marks the never-given subset;
             # v2 marks the may-be-given subset. The trailing union keeps
-            # a config v1 accepted: prefixes.py asserts its own data has
-            # no word in both non_first_name_prefixes and
-            # bound_first_names, but nothing stops a caller adding one at
+            # a config v1 accepted: particles.py asserts its own data has
+            # no word in both NON_GIVEN_NAME_PARTICLES and
+            # BOUND_GIVEN_NAMES, but nothing stops a caller adding one at
             # runtime, and v1 then lets the bound rule win (leading "dos
             # Santos Silva" parses first="dos Santos"). Treating such a
             # word as may-be-given reproduces that rather than raising.
@@ -1062,23 +1066,19 @@ class Constants:
             bound_given_names=bound,
             # v1 Constants has no manager for these (#274 is 2.0
             # behavior); the data module is the only source
-            maiden_markers=frozenset(MAIDEN_MARKERS),
+            maiden_markers=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,
+            # 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=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
@@ -1099,8 +1099,8 @@ class Constants:
                 _SENTINEL_PAIRS[k] for k in self.maiden_delimiters
                 if k not in self.nickname_delimiters),
             # suffix_delimiter is a _RenderDefaults-only field here; the
-            # facade layers it onto extra_suffix_delimiters per instance
-            # (a later task) -- _snapshot() itself stays pure translation
+            # facade layers it onto extra_suffix_delimiters per
+            # instance -- _snapshot() itself stays pure translation
         )
         defaults = _RenderDefaults(
             self.string_format, self.initials_format, self.initials_delimiter,

{nameparser-2.1.0 → nameparser-2.2.0}/nameparser/_facade.py

@@ -1,4 +1,5 @@
-"""The 2.0 ``HumanName`` facade (migration spec §2): a mutable wrapper
+"""The 2.0 ``HumanName`` facade (mechanisms.md#FACADE-CONTRACT): a
+mutable wrapper
 over a frozen ParsedName, delegating parsing to the core Parser resolved
 from the bound Constants shim. Keeps every v1 spelling. Deleted in 3.0.
 
@@ -31,7 +32,8 @@ 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, Token
+from nameparser._types import (FOLDED_TAG, UNCLASSIFIED_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()}
@@ -41,7 +43,8 @@ _MEMBERS = tuple(_V1_SPELLING.get(r.value, r.value) for r in Role)
 
 
 
-#: v1 parsing hooks the facade never calls (spec §2 exception 2 / #280).
+#: v1 parsing hooks the facade never calls
+#: (mechanisms.md#FACADE-CONTRACT / #280).
 _V1_HOOKS = (
     "pre_process", "post_process", "parse_full_name", "parse_pieces",
     "parse_nicknames", "join_on_conjunctions", "squash_emoji",
@@ -152,7 +155,8 @@ class HumanName:
                 DeprecationWarning, stacklevel=3)
 
     # -- render defaults -----------------------------------------------------
-    # One-line validating setters (spec §2): assigning a non-str (or, for
+    # One-line validating setters (mechanisms.md#FACADE-CONTRACT):
+    # assigning a non-str (or, for
     # the two fields that allow it, non-str-non-None) raises TypeError at
     # assignment time instead of failing later inside .format().
 
@@ -218,7 +222,8 @@ class HumanName:
     # -- config / parsing ---------------------------------------------------
 
     def _resolve(self) -> Parser:
-        """Dirty-tracked parser resolution (spec §3): rebuild the
+        """Dirty-tracked parser resolution
+        (mechanisms.md#CONFIG-SHIM-SNAPSHOT): rebuild the
         snapshot only when the bound Constants' generation moved."""
         gen = self._C._generation
         if self._snapshot_gen != gen:
@@ -472,10 +477,14 @@ class HumanName:
         return _normalize(text) in self._lexicon.conjunctions
 
     def _split_last(self) -> tuple[list[str], list[str]]:
-        # v1 parser.py _split_last, verbatim: vocabulary lookup at ACCESS
-        # time (so assigned last names split too), with the all-particle
-        # guard (a family name is assumed not to consist entirely of
-        # particles, e.g. surname "Do" which also appears in PREFIXES)
+        # rules.md#R2: "a name part whose every word is particle
+        # vocabulary is a part where none of them is doing a
+        # particle's work" -- the all-particle guard
+        # below is this rule, and predates its statement: v1 assumed a
+        # family name does not consist entirely of particles, e.g. the
+        # surname "Do" which also appears in PARTICLES. v1
+        # parser.py _split_last otherwise verbatim, vocabulary lookup
+        # at ACCESS time so assigned last names split too.
         words = " ".join(self.last_list).split()
         i = 0
         while i < len(words) and self._is_particle(words[i]):
@@ -517,20 +526,40 @@ class HumanName:
         if len(initials) > 0:
             return self.initials_separator.join(initials)
         # Return '' (never empty_attribute_default, which may be None)
-        # when a part has no initialable words, e.g. a middle name
-        # consisting only of prefixes ("de la"). Callers drop these
-        # parts entirely.
+        # when a part has no initialable words. group_initials below
+        # decides what that means: one such element among others is
+        # dropped; a group that yields nothing AND is wholly particles
+        # initials its words; and a group that yields nothing for any
+        # other reason -- a conjunction, or particles mixed with one --
+        # is still dropped ("Vega, Santa de y" drops its middle).
         return ""
 
     def _initials_lists(self) -> tuple[list[str], list[str], list[str]]:
         """Initials for the first, middle and last name groups. Parts
-        that yield no initials (e.g. a prefix-only middle name like
-        "de la") are dropped rather than kept as empty strings.
+        that yield no initials are dropped rather than kept as empty
+        strings -- except a part that is wholly PARTICLES, whose words
+        initial as ordinary name words since #404, so the prefix-only
+        middle name "de la" is no longer an example of the dropping.
         """
         def group_initials(names: list[str],
                             firstname: bool = False) -> list[str]:
-            return [i for i in (self._process_initial(n, firstname)
-                                 for n in names if n) if i]
+            got = [i for i in (self._process_initial(n, firstname)
+                                for n in names if n) if i]
+            words = [w for n in names if n for w in n.split()]
+            if got or not words or not all(self._is_particle(w)
+                                           for w in words):
+                return got
+            # rules.md#R3: "except the particles of a part whose every
+            # word is one, which are not acting as particles there"
+            # -- nothing survived
+            # the filter, so the whole group is particles. The
+            # facade's twin of the core's
+            # UNJOINED_TAG. NOT pinned against it: both case runners
+            # compare the seven role fields only, and Case carries no
+            # initials column, so the one covering test is
+            # tests/test_initials.py::test_initials_middle_name_all_prefixes. _split_last already applies the same guard to
+            # the base, which is why last_base was never empty here.
+            return [w[0] for w in words]
         return (group_initials(self.first_list, True),
                 group_initials(self.middle_list),
                 group_initials(self.last_list))
@@ -685,7 +714,8 @@ class HumanName:
         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
+        # Components come back exactly as pickled
+        # (mechanisms.md#FACADE-CONTRACT): 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
@@ -717,8 +747,17 @@ class HumanName:
                         f"nameparser"
                     )
                 for position, word in enumerate(entry.split()):
-                    tokens.append(Token(
-                        word, None, role,
-                        frozenset({"joined"}) if position else frozenset()))
+                    # UNCLASSIFIED_TAG for the same reason replace()
+                    # stamps it: a pickle carries the *_list STRINGS
+                    # and no tags, so nothing here was read by a parse
+                    # and case repair must ask the vocabulary rather
+                    # than read an absent conjunction tag. Without it a
+                    # restored "juan ortega y gasset" repairs to
+                    # "Ortega Y Gasset", which is neither v1's answer
+                    # nor the same name's unpickled one.
+                    tags = {UNCLASSIFIED_TAG}
+                    if position:
+                        tags.add("joined")
+                    tokens.append(Token(word, None, role, frozenset(tags)))
         self._parsed = ParsedName(
             original=str(state.get("original", "")), tokens=tuple(tokens))

{nameparser-2.1.0 → nameparser-2.2.0}/nameparser/_lexicon.py

@@ -55,7 +55,7 @@ _VOCAB_FIELDS = (
 #:   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
+#:   over the raw GLUED_HONORIFICS/SUFFIX_WORDS 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
@@ -75,6 +75,25 @@ _SUBSET_FIELDS = (
 )
 
 
+#: The fields whose entries may be PHRASES: stored space-joined and
+#: folded per word (_title_key), and exempt from the dead-entry warning
+#: below. Every other field is matched one word at a time, where a
+#: multi-word entry can never match.
+#:
+#: The two are not the same mechanism, and the difference is why the
+#: exemption is a list rather than a rule. A given_name_titles run is
+#: identified per word FIRST -- 'lt' and 'col' are each title
+#: vocabulary -- and only then joined and looked up. A maiden marker
+#: phrase has no such per-word foothold: 'z' and 'domu' are not markers
+#: individually, and adding them separately (which this warning used to
+#: advise) reads 'Maria Kowalska z domu Nowak' as maiden 'domu Nowak'
+#: and strips 'Anna z Nowak' of its family name. So markers are matched
+#: by a genuine multi-token lookahead instead --
+#: _pipeline._vocab.maiden_marker_run, longest first -- and only the
+#: STORAGE rule is shared with titles.
+_PHRASE_FIELDS = ("given_name_titles", "maiden_markers")
+
+
 def _normalize(word: str) -> str:
     """Lowercase, strip whitespace and EDGE periods -- v1's lc()
     semantics. Interior periods survive on purpose: 'J.R.' must not
@@ -110,8 +129,9 @@ def _title_key(words: Iterable[str]) -> str:
     A multi-word title is matched as one key ('lt col'), so the fold has
     to run per word and rejoin -- _normalize on the whole phrase would
     leave interior periods. Defined once because it is built at match
-    time (post_rules) and at translation time (the v1 facade's
-    first_name_titles), and a divergence between the two fails silently:
+    time (post_rules for H1, group for the P5 licence -- which must
+    agree, see #369) and at translation time (the v1 facade's
+    first_name_titles), and a divergence between them fails silently:
     the entry simply stops matching.
 
     Words that fold away are DROPPED, not joined as empty. Keeping the
@@ -191,13 +211,14 @@ def _normset(
             raise TypeError(
                 f"Lexicon.{field_name} entries must be strings, got {w!r}"
             )
-        # given_name_titles is the one field whose entries are matched as
-        # a multi-word run, so it folds per word: stored as the same key
-        # post_rules builds, or 'lt. col' would be kept verbatim and
-        # never match anything (a silent no-op on the config surface).
-        # Every other field holds single words, where the two folds
-        # agree.
-        n = _title_key(w.split()) if field_name == "given_name_titles" \
+        # A phrase field's entries are matched as a multi-word run, so
+        # they fold per word: stored as the same key the match site
+        # builds, or 'lt. col' (and 'z. domu') would be kept verbatim
+        # and never match anything -- a silent no-op on the config
+        # surface. Every other field holds single words, where the two
+        # folds agree. See _PHRASE_FIELDS for how the two differ once
+        # stored.
+        n = _title_key(w.split()) if field_name in _PHRASE_FIELDS \
             else _normalize(w)
         # "." or "" is a data bug (stray split artifact, empty CSV
         # cell); dropping it silently would also let a data-module typo
@@ -207,7 +228,7 @@ def _normset(
                 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
+        # Every field outside _PHRASE_FIELDS 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
@@ -217,8 +238,10 @@ def _normset(
         # 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"
+        # no-op. Both invariants are indifferent to WHICH fields are
+        # exempt: the exemption only decides whether a warning exists to
+        # be emitted once or suppressed.
+        if (warn and field_name not in _PHRASE_FIELDS
                 # interior whitespace test; split() covers all Unicode
                 # whitespace
                 and n != "".join(n.split())):
@@ -303,8 +326,12 @@ class Lexicon:
     Entries are normalized at construction -- lowercased, edge periods
     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
+    never match. Two fields are exempt, and they differ in HOW they
+    match: ``given_name_titles`` is looked up as the space-joined run
+    of words the parse has ALREADY read as titles, while
+    ``maiden_markers`` is matched by lookahead, longest first, over
+    words that need not be markers on their own (``"z domu"``).
+    Field docs below show examples, not full
     contents; inspect any field's shipped vocabulary directly, e.g.
     ``Lexicon.default().conjunctions``."""
 
@@ -313,7 +340,7 @@ class Lexicon:
     titles: frozenset[str] = frozenset()
     #: Titles whose single following name reads as a GIVEN name
     #: ("sheikh", "sister", ...) rather than a family name. Full
-    #: default list: :data:`~nameparser.config.titles.FIRST_NAME_TITLES`.
+    #: default list: :data:`~nameparser.config.titles.GIVEN_NAME_TITLES`.
     given_name_titles: frozenset[str] = frozenset()
     #: Post-nominal acronym suffixes, matched with or without periods
     #: ("phd" matches "PhD" and "Ph.D."). Full default list:
@@ -321,7 +348,7 @@ class Lexicon:
     suffix_acronyms: frozenset[str] = frozenset()
     #: Post-nominal word suffixes ("jr", "esquire", "iii", ...). Full
     #: default list:
-    #: :data:`~nameparser.config.suffixes.SUFFIX_NOT_ACRONYMS`.
+    #: :data:`~nameparser.config.suffixes.SUFFIX_WORDS`.
     suffix_words: frozenset[str] = frozenset()
     #: Subset of suffix_acronyms counted as suffixes only when written
     #: WITH periods -- their bare forms are common surnames ("ma",
@@ -330,14 +357,32 @@ class Lexicon:
     suffix_acronyms_ambiguous: frozenset[str] = frozenset()
     #: Family-name particles that chain onto the following piece
     #: ("van", "de", "bin", ...). Full default list:
-    #: :data:`~nameparser.config.prefixes.PREFIXES`.
+    #: :data:`~nameparser.config.particles.PARTICLES`.
     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", but also "Van Buren"). No constant of its own
-    #: -- the default derives
+    #: Subset of particles that can also BE a given name ("Van
+    #: Johnson", but also "Van Buren"). Membership decides nothing
+    #: about chaining: the prefix chain skips the name's first piece
+    #: and never consults this set, so it leaves a leading particle a
+    #: piece of its own whether listed or not -- "de Mesnil" groups
+    #: into two pieces exactly as "van Gogh" does, and since #367 the
+    #: NAME in "Dr. de Mesnil" and "Dr. Van Johnson" groups into those
+    #: same two pieces behind the title piece, a title not being
+    #: part of the name it precedes. What membership
+    #: decides is what becomes of that piece afterwards. Under ANY
+    #: ``name_order`` a member records a particle-or-given ambiguity
+    #: and a non-member records none, and a non-member is additionally
+    #: folded back into the family name once roles exist WHERE IT OPENS
+    #: THE NAME, so the whole name is the surname ("de Mesnil" -- a bare "de", with nothing to
+    #: fold into, is left alone). That fold is order-independent too
+    #: (#359) -- not because the word could not be a given name, which
+    #: it can where position forces it (``parse("de")`` reports given
+    #: "de"), but because a particle OPENING the name has the rest of
+    #: the name to join forward to, and that evidence is positional
+    #: rather than vocabulary, so no declared order contradicts it. Which field a MEMBER's piece
+    #: lands in is ``name_order``'s question, not this set's.
+    #: No constant of its own -- the default derives
     #: as particles minus
-    #: :data:`~nameparser.config.prefixes.NON_FIRST_NAME_PREFIXES`
+    #: :data:`~nameparser.config.particles.NON_GIVEN_NAME_PARTICLES`
     #: (which marks the opposite, never-given subset).
     particles_ambiguous: frozenset[str] = frozenset()
     #: Words or characters that join surrounding pieces into one
@@ -347,10 +392,15 @@ class Lexicon:
     #: Given-name prefixes that bind to the following word to form one
     #: given name ("abdul" -> "Abdul Salam"); never standalone names.
     #: Full default list:
-    #: :data:`~nameparser.config.bound_first_names.BOUND_FIRST_NAMES`.
+    #: :data:`~nameparser.config.bound_given_names.BOUND_GIVEN_NAMES`.
     bound_given_names: frozenset[str] = frozenset()
     #: Marker words introducing a birth surname, routed to the maiden
-    #: field ("née", "geb.", "roz.", ...). Full default list:
+    #: field ("née", "geb.", "rozená", ...). An entry may be a PHRASE
+    #: ("z domu"): entries are matched by lookahead, longest first, so
+    #: a phrase wins where it matches and a word entry that starts one
+    #: still matches on its own everywhere else. A phrase matches only
+    #: where its words stand together -- a bracketed clause or a comma
+    #: between them ends the run. Full default list:
     #: :data:`~nameparser.config.maiden_markers.MAIDEN_MARKERS`.
     maiden_markers: frozenset[str] = frozenset()
     #: Family names for the unspaced-name segmentation stage (#271),
@@ -419,8 +469,8 @@ class Lexicon:
         # the expensive one -- three working configurations broken
         # across two attempts. Do not add a third.
         #
-        # The v2 form of prefixes.py's NON_FIRST_NAME_PREFIXES-disjoint-
-        # from-BOUND_FIRST_NAMES assertion. That module guards its own
+        # The v2 form of particles.py's NON_GIVEN_NAME_PARTICLES-disjoint-
+        # from-BOUND_GIVEN_NAMES assertion. That module guards its own
         # data at import; this guards vocabulary a caller supplies.
         contradictory = (
             self.bound_given_names & self.particles) - self.particles_ambiguous
@@ -614,39 +664,43 @@ class Lexicon:
 @functools.cache
 def _default_lexicon() -> Lexicon:
     # v1 data modules are the single source of vocabulary through 2.x.
-    from nameparser.config.bound_first_names import BOUND_FIRST_NAMES
+    from nameparser.config.bound_given_names import BOUND_GIVEN_NAMES
     from nameparser.config.capitalization import CAPITALIZATION_EXCEPTIONS
     from nameparser.config.conjunctions import CONJUNCTIONS
     from nameparser.config.maiden_markers import MAIDEN_MARKERS
-    from nameparser.config.prefixes import NON_FIRST_NAME_PREFIXES, PREFIXES
+    from nameparser.config.particles import NON_GIVEN_NAME_PARTICLES, PARTICLES
     from nameparser.config.suffixes import (
         GLUED_HONORIFICS, SUFFIX_ACRONYMS, SUFFIX_ACRONYMS_AMBIGUOUS,
-        SUFFIX_NOT_ACRONYMS,
+        SUFFIX_WORDS,
     )
     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
-    # so the strictly-typed frozenset[str] fields never see a bare set.
+    from nameparser.config.titles import GIVEN_NAME_TITLES, TITLES
+
+    # every vocabulary constant is a frozenset since #293, so each one
+    # feeds its strictly-typed frozenset[str] field as it stands -- and
+    # this cache reading them ONCE is the reason they are frozen. A
+    # mutated module set always reached a freshly built Constants, and
+    # reached this Lexicon only when the edit landed before the first
+    # call; after it, the cache was already built and the same edit was
+    # invisible here. Which of the two a program got was not something
+    # the code doing the mutating could see.
     # keep in sync with _config_shim.Constants._snapshot() (pinned by the
     # default-Constants equality test in tests/v2/test_config_shim.py)
     return Lexicon(
-        titles=frozenset(TITLES),
-        given_name_titles=frozenset(FIRST_NAME_TITLES),
-        suffix_acronyms=frozenset(SUFFIX_ACRONYMS),
-        suffix_words=frozenset(SUFFIX_NOT_ACRONYMS),
-        suffix_acronyms_ambiguous=frozenset(SUFFIX_ACRONYMS_AMBIGUOUS),
-        particles=frozenset(PREFIXES),
+        titles=TITLES,
+        given_name_titles=GIVEN_NAME_TITLES,
+        suffix_acronyms=SUFFIX_ACRONYMS,
+        suffix_words=SUFFIX_WORDS,
+        suffix_acronyms_ambiguous=SUFFIX_ACRONYMS_AMBIGUOUS,
+        particles=PARTICLES,
         # FLIPPED from v1: v1 marks the never-given subset; v2 marks the
         # may-be-given subset (migration: complement translation).
-        particles_ambiguous=frozenset(PREFIXES - NON_FIRST_NAME_PREFIXES),
-        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)
+        particles_ambiguous=PARTICLES - NON_GIVEN_NAME_PARTICLES,
+        conjunctions=CONJUNCTIONS,
+        bound_given_names=BOUND_GIVEN_NAMES,
+        maiden_markers=MAIDEN_MARKERS,
         surnames=KOREAN_SURNAMES,
-        honorific_tails=frozenset(GLUED_HONORIFICS),
+        honorific_tails=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