nameparser 2.1.0__tar.gz → 2.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nameparser
-Version: 2.1.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
@@ -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.3.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.3.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.3.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.3.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]):
@@ -503,34 +512,73 @@ 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)
         # 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 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),
                 group_initials(self.last_list))
@@ -685,7 +733,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 +766,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))