nameparser 2.2.0__tar.gz → 2.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nameparser
-Version: 2.2.0
+Version: 2.3.0
 Summary: A simple Python module for parsing human names into their individual components.
 Author-email: Derek Gulbranson <derek73@gmail.com>
 License: LGPL

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

@@ -512,16 +512,32 @@ class HumanName:
     # -- initials -------------------------------------------------------------
 
     def _process_initial(self, name_part: str, firstname: bool = False) -> str:
-        # v1 parser.py:427 verbatim: particles/conjunctions are filtered
-        # from initials unless the part is a first name. split() rather
-        # than split(" "): *_list attributes assigned directly bypass
-        # whitespace normalization, and split(" ") yields empty strings
-        # for repeated spaces (#232).
+        # after v1 parser.py:427, not verbatim: particles and
+        # conjunctions are filtered from initials unless the part is a
+        # first name. split() rather than split(" ") because split(" ")
+        # yields '' between repeated spaces and `part[0]` below would
+        # raise IndexError on it (#232). v1 stated the reason as
+        # `*_list` attributes bypassing whitespace normalization, which
+        # no longer holds -- the `*_list` properties are read-only in
+        # 2.x, and assignment through `hn.middle = ...` normalizes --
+        # but a doubled space anywhere in a part still reaches here.
         parts = name_part.split()
         initials = []
         for part in parts:
-            if not (self._is_particle(part)
-                    or self._is_conjunction(part)) or firstname:
+            # v1 parser.py:771 (1.4.0): is_conjunction was "in the
+            # conjunctions set AND NOT is_an_initial", so a dotted or
+            # bare-capital E/Y is the initial it looks like rather
+            # than the connective. The 2.0 facade dropped that half
+            # and lost the middle initial of 'Scott E. Werner' (#462).
+            # _render._INITIAL is v1's `initial` shape, kept in step
+            # with the pipeline's copy by tests/v2/test_regex_sync.py;
+            # the facade may import _render but not _pipeline
+            # (tests/v2/test_layering.py). Scoped here rather than in
+            # _is_conjunction: this is the only caller, and a future
+            # one should not inherit a decision made for initials.
+            conjunction = (self._is_conjunction(part)
+                           and not _render._INITIAL.fullmatch(part))
+            if not (self._is_particle(part) or conjunction) or firstname:
                 initials.append(part[0])
         if len(initials) > 0:
             return self.initials_separator.join(initials)
@@ -554,11 +570,14 @@ class HumanName:
             # -- 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.
+            # UNJOINED_TAG. NOT pinned against it by the case runners,
+            # which compare the seven role fields only (Case carries
+            # no initials column); the covering test is
+            # tests/test_initials.py::test_initials_middle_name_all_prefixes,
+            # and since #484 the differential compares initials() on
+            # both surfaces for names whose roles agree. _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),

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

@@ -10,8 +10,9 @@ from __future__ import annotations
 import dataclasses
 import functools
 import sys
+import unicodedata
 import warnings
-from collections.abc import Iterable, Mapping
+from collections.abc import Iterable, Mapping, Set
 from dataclasses import dataclass, field
 from types import FrameType, MappingProxyType
 from typing import cast
@@ -83,7 +84,11 @@ _SUBSET_FIELDS = (
 #: 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
+#: vocabulary -- and only then looked up, as the whole run's key or as
+#: its LAST word's (_run_addresses_by_given, #489). The whole-run arm
+#: is the one a phrase entry is matched by; the last-word arm is a
+#: single word and cannot reach a phrase, so storage stays what it was
+#: (the two are asked together, not in precedence). 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'
@@ -94,13 +99,44 @@ _SUBSET_FIELDS = (
 _PHRASE_FIELDS = ("given_name_titles", "maiden_markers")
 
 
+#: Every character the parser reads as a full stop at a WORD'S EDGE
+#: (#322/#323): the ASCII period, the fullwidth FULL STOP U+FF0E, the
+#: IDEOGRAPHIC FULL STOP U+3002 and its halfwidth form U+FF61. One
+#: string, four readers -- the lookup fold below, _vocab's script
+#: classification fold, _script_segment's surname site and honorific
+#: tail match -- so that "which characters are a period" is answered
+#: once; the bundle's fifth site, _pieces' opening-abbreviation shape,
+#: reads no stop set at all but the no-initials repertoire
+#: (_policy._NO_INITIALS) that licenses every reader here. NFKC is
+#: NOT a substitute for listing them: it folds U+FF0E to '.' and
+#: U+FF61 to U+3002, and leaves U+3002 as it is.
+#: Not every period test reads this set, and the ones that do not are
+#: named so the claim is checkable: the interior-period shapes -- the
+#: dotted acronym 'M.A.' and the split 'Ph. D.' (_vocab) -- and FOUR
+#: ASCII-only edge tests on Latin shapes, across THREE modules -- the
+#: initial 'J.' (_vocab), the bracketed credential '(Mgr.)' and the
+#: word-internal apostrophe rule (_extract), and the trailing
+#: middle-initial carve-out 'V.' (_assign) -- stay ASCII. That is a
+#: fact about those TESTS and not about this set's reach: the fold
+#: below is script-agnostic, so a LATIN word wearing a wide stop
+#: reaches vocabulary the ASCII veto would have taken it out of.
+#: 'V。' folds to 'v' and does not end in the ASCII period the
+#: trailing-suffix carve-out tests (_assign, not is_initial), so
+#: it is roman five -- suffix -- where 'V.' stays a middle
+#: initial through that same carve-out; 'Jr。' simply reaches its
+#: entry, and 'Dr。' its title.
+#: decisions.md#cjk-full-stops carries the measurements.
+FULL_STOPS = ".．。｡"
+
+
 def _normalize(word: str) -> str:
-    """Lowercase, strip whitespace and EDGE periods -- v1's lc()
-    semantics. Interior periods survive on purpose: 'J.R.' must not
-    collapse to 'jr' and hit the periodless vocabulary (v1 parity,
-    pinned live 2026-07-17). Suffix-ACRONYM membership alone uses the
-    period-free form (see _vocab.suffix_as_written), mirroring v1's
-    is_suffix, which removed periods only for the acronym test.
+    """Lowercase, NFC-compose, strip whitespace and EDGE full stops
+    (FULL_STOPS, not the ASCII period alone -- #322). Interior periods
+    survive on purpose: 'J.R.' must not collapse to 'jr' and hit the
+    periodless vocabulary (v1 parity, pinned live 2026-07-17).
+    Suffix-ACRONYM membership alone uses the period-free form (see
+    _vocab.suffix_as_written), mirroring v1's is_suffix, which removed
+    periods only for the acronym test.
 
     lower(), NOT casefold(): casefold's caseless-matching folds mutate
     the stored vocabulary itself -- 'κος' becomes the misspelling 'κοσ'
@@ -110,39 +146,122 @@ def _normalize(word: str) -> str:
     match-time lookups, so matching stays symmetric either way; lower()
     is what v1's lc() used, preserving which cross-spellings match.
 
-    Strips to a FIXED POINT. A single strip().strip(".") leaves
-    periods-around-whitespace half done ('. a .' -> ' a '), so a value
+    NFC, since #322, and only for a non-ASCII word (ASCII is already
+    NFC, and this runs per token on the parse path --
+    decisions.md#parse-cost). NFD hangul decomposes to jamo and missed
+    every vocabulary entry; composing at lookup AND at storage keeps
+    the two symmetric, and no shipped entry changes under it (measured
+    2026-09-09: fold every string member of every Lexicon.default()
+    field through NFC and count the changes; zero of 1735). This is
+    the same NFC composition script classification already applies
+    (_vocab._normalized_for_script); token text is never rewritten.
+
+    Strips to a FIXED POINT. A single strip().strip(FULL_STOPS) leaves
+    stops-around-whitespace half done ('. a .' -> ' a '), so a value
     that is re-normalized later -- on unpickle, or by a second add() --
     would change under its owner. v1 never re-normalized, so this only
     matters now that storage and match-time share one fold."""
     word = word.lower()
+    if not word.isascii():
+        word = unicodedata.normalize("NFC", word)
     while True:
-        stripped = word.strip().strip(".")
+        stripped = word.strip().strip(FULL_STOPS)
         if stripped == word:
             return word
         word = stripped
 
 
-def _title_key(words: Iterable[str]) -> str:
-    """The given_name_titles lookup key for a run of title words.
+def _fold_words(words: Iterable[str]) -> list[str]:
+    """The words of a title run, folded for storage and lookup.
 
     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 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
-    gap makes the fold non-idempotent -- 'lt .' would store 'lt ', which
-    match time can never build (post_rules joins token texts, and a lone
-    '.' is not a title token), so the entry is inert. Storage re-runs
-    this fold on unpickle and on every dataclasses.replace, so a value
-    that changes under a second pass is one Lexicon later rejects as
+    to run per word -- _normalize on the whole phrase would leave
+    interior periods.
+
+    Words that fold away are DROPPED, not kept as empty. Keeping the
+    gap makes the key non-idempotent -- 'lt .' would store 'lt ', which
+    match time can never build: a run CAN carry a lone '.' (the
+    conjunction merge puts one there), but the fold drops the empty
+    word, so the key is 'lt' and the stored entry is inert. Storage
+    re-runs this fold on unpickle and on every dataclasses.replace, so a
+    value that changes under a second pass is one Lexicon later rejects as
     "not written by this version". _normalize converges for the same
-    reason; so must anything built on top of it."""
-    return " ".join(filter(None, (_normalize(w) for w in words)))
+    reason; so must anything built on top of it.
+
+    A LIST, so that _run_addresses_by_given's last-word arm can be the
+    last word of this fold rather than a re-split of the joined key --
+    "the last word of the FOLDED key" is then structural, and the two
+    arms read one fold between them.
+
+    map/filter rather than a comprehension: both are C calls where a
+    comprehension is a Python frame on 3.11, and this runs on the parse
+    path for every name carrying a title run (decisions.md#parse-cost).
+    """
+    return list(filter(None, map(_normalize, words)))
+
+
+def _title_key(words: Iterable[str]) -> str:
+    """The given_name_titles lookup key for a run of title words: the
+    folded words, space-joined.
+
+    Defined once because it is built at match time
+    (_run_addresses_by_given, which is how post_rules' H1 and group's
+    P5 licence both reach it) and at translation time (_config_shim's
+    first_name_titles), and a divergence between them fails silently:
+    the entry simply stops matching."""
+    return " ".join(_fold_words(words))
+
+
+def _run_addresses_by_given(words: Iterable[str],
+                            vocabulary: Set[str]) -> bool:
+    """Whether a run of title words addresses by the GIVEN name.
+
+    Two sites ask it and they must agree -- post_rules for H1, group
+    for the P5 licence -- because a run read two ways is a rule
+    contradicting itself (decisions.md#P5, the 2026-08-22 #369 entry).
+    One predicate, so they cannot drift.
+
+    The WHOLE run's key, or that key's LAST word (#489): a run is
+    written as several titles and addresses the way its final one does,
+    so 'Her Majesty Queen' addresses by given name because 'queen'
+    does. The two arms are asked of one key and neither is the other's
+    fallback -- the `or` short-circuits but decides nothing, since for
+    a one-word run the key IS its last word. Both arms read one
+    _fold_words list, so the last word is the last word of the FOLDED
+    key by construction rather than by agreement, and a run token that
+    folds away cannot empty that arm: the conjunction merge can put a
+    lone '.' in the run ('Sir and . John'), and the fold drops it.
+    What the drop leaves as the last word can then be the CONJUNCTION
+    -- 'Sir and . John' keys 'sir and' and reads family 'John', where
+    'Sir and Dame John' keys 'sir and dame' and reads given. Harmless
+    on the shipped vocabulary, which holds no entry ending in a
+    connective, and a caller who stored one would be asking for it
+    (measured 2026-09-09).
+
+    The whole-run arm is what keeps a caller's multi-word phrase entry
+    working: 'lt col' is stored as one key and matched as one run. Over
+    the SHIPPED vocabulary it is dead -- every shipped entry is a single
+    word (asserted in test_lexicon.py), so it can only ever match a
+    one-word run, which is a run the last-word arm reads the same way.
+
+    H2's unlisted abbreviations ride in the run. One can never match as
+    the last-word key, being in no vocabulary by definition -- written
+    as the inputs that produce those runs, 'Xyz. Sir John' keys 'xyz
+    sir', matches on 'sir' and reads given 'John', while 'Sir Xyz.
+    John' keys 'sir xyz', matches on neither arm and reads family
+    'John'. It CAN sit inside a whole-run key that matches, because
+    given_name_titles is deliberately not validated against titles: a
+    caller who stores 'sir xyz' makes 'Sir Xyz. John' read given.
+
+    The vocabulary is passed in rather than read off a default: a
+    caller's own Lexicon is the one that has to be consulted, and this
+    module is where Lexicon is defined."""
+    folded = _fold_words(words)
+    if not folded:
+        # every word folded away, so there is no key and no last word:
+        # the joined spelling built "" here, which matched nothing
+        return False
+    return " ".join(folded) in vocabulary or folded[-1] in vocabulary
 
 
 def _reject_buffer(value: object, label: str, plural: str) -> None:
@@ -226,7 +345,7 @@ def _normset(
         if not n:
             raise ValueError(
                 f"Lexicon.{field_name} entry {w!r} normalizes to empty "
-                f"(lowercase + strip periods/whitespace leaves nothing)"
+                f"(lowercase + strip full stops/whitespace leaves nothing)"
             )
         # Every field outside _PHRASE_FIELDS is matched one word at a
         # time, so a multi-word entry can never match -- the library
@@ -301,7 +420,7 @@ def _normpairs(
         if not normalized_key:
             raise ValueError(
                 f"capitalization_exceptions key {k!r} normalizes to "
-                f"empty (lowercase + strip periods/whitespace leaves "
+                f"empty (lowercase + strip full stops/whitespace leaves "
                 f"nothing)"
             )
         # capitalized() looks words up one at a time (the _WORD regex
@@ -323,12 +442,13 @@ class Lexicon:
     Start from :meth:`default` (the shipped vocabulary) or
     :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. Vocabulary entries are
-    single words -- a multi-word entry warns at construction and can
-    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
+    Entries are normalized at construction -- lowercased, NFC-composed,
+    edge full stops stripped -- so matching is case-insensitive.
+    Vocabulary entries are single words -- a multi-word entry warns at
+    construction and can never match. Two fields are exempt, and they
+    differ in HOW they match: ``given_name_titles`` is looked up
+    against the run of words the parse has ALREADY read as titles --
+    the whole run space-joined, or that run's last word -- 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

{nameparser-2.2.0 → nameparser-2.3.0}/nameparser/_parser.py

@@ -17,11 +17,12 @@ from nameparser._lexicon import Lexicon
 from nameparser._locale import Locale
 from nameparser._pipeline import run
 from nameparser._pipeline._assemble import assemble
+from nameparser._pipeline._post_rules import suffix_entries
 from nameparser._pipeline._state import ParseState
 from nameparser._pipeline._vocab import _SCRIPT_MATCHERS
 from nameparser._policy import UNSET, Policy, PolicyPatch, _Unset, apply_patch
 from nameparser._types import (
-    FOLDED_TAG, ParsedName, Segmenter, Token, _guarded_getstate,
+    FOLDED_TAG, ParsedName, Role, Segmenter, Token, _guarded_getstate,
     _guarded_setstate, _validated_field_strings,
 )
 
@@ -165,16 +166,30 @@ class Parser:
         capitalized()) behave as if the text had been parsed. The
         value is classified ON ITS OWN, though -- a word whose reading
         depends on surrounding context may classify differently than
-        it would in place (a standalone "B. S." reads as initials, not
-        a suffix run). The sub-parse's role choices and ambiguities
-        are discarded -- every harvested token takes the named field's
-        role -- and its structural behavior applies: delimiter
-        characters do not become tokens, and a maiden marker is
-        consumed as in parsing -- mid-value always, and leading a
-        DELIMITED value under a policy routing that pair to maiden,
-        where "(née Jones)" revises to "Jones" while the bare
-        "née Jones" keeps its marker, a leading marker in an
+        it would in place, and a glued CJK honorific the whole name
+        kept on an initial may peel in the value. The sub-parse's role
+        choices and ambiguities are discarded -- every harvested token
+        takes the named field's role -- and its structural behavior
+        applies: delimiter characters do not become tokens, and a
+        maiden marker is consumed as in parsing -- mid-value always,
+        and leading a DELIMITED value under a policy routing that pair
+        to maiden, where "(née Jones)" revises to "Jones" while the
+        bare "née Jones" keeps its marker, a leading marker in an
         undelimited value being no marker at all (#329).
+        A suffix value's ENTRY structure is derived from the value's
+        own commas after the role is forced, by the rule a whole name
+        uses: a comma parts two credentials and a space joins them, so
+        ``revise(n, suffix="MD PhD")`` is one entry and a name's
+        rendered suffix revises back to itself wherever the value's
+        words read as the whole name read them -- the honorific peel
+        above is the one corpus exception of 368 suffix-bearing names,
+        2026-09-06 (#511). A delimiter the policy names through
+        ``extra_suffix_delimiters`` parts a value only where the
+        value's own words, read as a name, give it a tail segment for
+        the core to be dropped on; a run of post-nominals has none,
+        with or without a comma of its own (``"MD PhD - FACS"`` and
+        ``"MD, PhD - FACS"`` both keep the dash as a word), so write a
+        comma at the boundary you want rather than the delimiter.
         Tokens are synthetic (span=None); original is unchanged; a
         value with no name content (empty, whitespace, or punctuation
         only) clears the field; ambiguities referencing replaced
@@ -182,12 +197,46 @@ class Parser:
         if not isinstance(name, ParsedName):
             raise TypeError(f"revise() takes a ParsedName, got {name!r}")
         replaced = _validated_field_strings(fields)
-        harvested = {
-            role: tuple(
+        harvested: dict[Role, tuple[Token, ...]] = {}
+        for role, value in replaced.items():
+            # the same construction parse() makes, spelled twice
+            # rather than through a helper: routing parse() through
+            # one cost a frame per parse on the hot path (py3.11,
+            # 2026-09-06: 415 calls/name against 414 without it, in a
+            # 402-418 band), the same trade _mark_suffix_entries
+            # refused, one row over
+            state = run(ParseState(original=value, lexicon=self.lexicon,
+                                   policy=self.policy,
+                                   segmenter=self.segmenter))
+            dropped = set(state.dropped)
+            # Force the role BEFORE the entry pass: it keys on
+            # Role.SUFFIX, and a bare value's sub-parse reads its words
+            # as a name ('MD PhD' is a title and a family there), so
+            # inside the sub-parse it joined nothing. The sub-parse's
+            # tags are KEPT, "joined" included: a within-piece mark
+            # (the Ph. D. merge) is role-blind and right for every
+            # role, and a clear was measured and backed out --
+            # decisions.md#C1 (2026-09-06 #511) carries the rest: the
+            # between-piece mark that rides onto a non-suffix role, and
+            # which views read it. Dropped tokens keep their role: the
+            # pass filters them by index and assemble omits them.
+            forced = tuple(
+                tok if i in dropped
+                else dataclasses.replace(tok, role=role)
+                for i, tok in enumerate(state.tokens))
+            # rules.md#R1: "a run of post-nominals written with spaces
+            # renders with spaces, and one written with commas keeps
+            # them" -- the same pass post_rules runs last, over the
+            # value's own comma offsets, so the harvest carries exactly
+            # the entry structure the value's commas describe. Run for
+            # every role: for a non-suffix role it is a no-op, kept
+            # unconditional as the simpler contract, revise() being off
+            # the call-count band.
+            entried = suffix_entries(
+                dataclasses.replace(state, tokens=forced))
+            harvested[role] = tuple(
                 Token(t.text, None, role, t.tags - {FOLDED_TAG})
-                for t in self.parse(value).tokens)
-            for role, value in replaced.items()
-        }
+                for t in assemble(entried).tokens)
         return name._with_field_tokens(harvested)
 
     # -- comparison -------------------------------------------------------