nameparser 2.0.0rc1__tar.gz → 2.0.0rc2__tar.gz

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

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

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

@@ -20,6 +20,7 @@ from nameparser._policy import (
     PolicyPatch,
 )
 from nameparser._types import (
+    STABLE_TAGS,
     Ambiguity,
     AmbiguityKind,
     ParsedName,
@@ -33,6 +34,7 @@ __all__ = [
     "HumanName",
     # v2 core
     "Span", "Role", "Token", "Ambiguity", "AmbiguityKind", "ParsedName",
+    "STABLE_TAGS",
     "Lexicon", "Policy", "PolicyPatch", "PatronymicRule", "UNSET",
     "GIVEN_FIRST", "FAMILY_FIRST", "FAMILY_FIRST_GIVEN_LAST",
     "DEFAULT_NICKNAME_DELIMITERS", "Locale",

{nameparser-2.0.0rc1 → nameparser-2.0.0rc2}/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
@@ -1103,10 +1125,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.0.0rc2}/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,10 @@ 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 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.0.0rc2}/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
@@ -112,7 +114,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 +181,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 +255,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 +275,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 +308,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).
@@ -479,7 +532,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

{nameparser-2.0.0rc1 → nameparser-2.0.0rc2}/nameparser/_parser.py

@@ -19,7 +19,10 @@ from nameparser._pipeline import run
 from nameparser._pipeline._assemble import assemble
 from nameparser._pipeline._state import ParseState
 from nameparser._policy import UNSET, Policy, PolicyPatch, apply_patch
-from nameparser._types import ParsedName, _guarded_getstate, _guarded_setstate
+from nameparser._types import (
+    FOLDED_TAG, ParsedName, Token, _guarded_getstate, _guarded_setstate,
+    _validated_field_strings,
+)
 
 
 @dataclass(frozen=True, slots=True)
@@ -75,6 +78,65 @@ class Parser:
                            policy=self.policy)
         return assemble(run(state))
 
+    # -- editing ----------------------------------------------------------
+
+    def revise(self, name: ParsedName, **fields: str) -> ParsedName:
+        """:meth:`ParsedName.replace` with this parser's vocabulary:
+        each value is tokenized and classified by a full sub-parse, so
+        the stable tags survive and the tag-driven views
+        (family_particles, initials(), the suffix join) 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 mid-value maiden marker is consumed as in parsing.
+        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
+        tokens are dropped."""
+        if not isinstance(name, ParsedName):
+            raise TypeError(f"revise() takes a ParsedName, got {name!r}")
+        replaced = _validated_field_strings(fields)
+        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()
+        }
+        return name._with_field_tokens(harvested)
+
+    # -- comparison -------------------------------------------------------
+
+    def matches(self, a: str | ParsedName, b: str | ParsedName) -> bool:
+        """Component-wise case-insensitive comparison of two names,
+        parsing str arguments with THIS parser.
+        :meth:`ParsedName.matches` parses its str argument with the
+        DEFAULT parser instead -- for names parsed with a custom
+        Parser, use this method."""
+        if isinstance(a, str):
+            a = self.parse(a)
+        elif not isinstance(a, ParsedName):
+            raise TypeError(f"matches() takes str or ParsedName, got {a!r}")
+        if isinstance(b, str):
+            b = self.parse(b)
+        elif not isinstance(b, ParsedName):
+            raise TypeError(f"matches() takes str or ParsedName, got {b!r}")
+        return a.comparison_key() == b.comparison_key()
+
+    # -- rendering delegates ----------------------------------------------
+
+    def capitalized(self, name: ParsedName, *,
+                    force: bool = False) -> ParsedName:
+        """:meth:`ParsedName.capitalized` under THIS parser's lexicon.
+        The no-argument form of that method uses the DEFAULT lexicon --
+        for names parsed with a custom Parser, use this method."""
+        if not isinstance(name, ParsedName):
+            raise TypeError(f"capitalized() takes a ParsedName, got {name!r}")
+        return name.capitalized(self.lexicon, force=force)
+
 
 @functools.cache
 def _default_parser() -> Parser:

{nameparser-2.0.0rc1 → nameparser-2.0.0rc2}/nameparser/_policy.py

@@ -45,7 +45,32 @@ FAMILY_FIRST = (Role.FAMILY, Role.GIVEN, Role.MIDDLE)
 #: ``Policy(name_order=...)`` values.
 FAMILY_FIRST_GIVEN_LAST = (Role.FAMILY, Role.MIDDLE, Role.GIVEN)
 
-_NAME_ROLES = frozenset({Role.GIVEN, Role.MIDDLE, Role.FAMILY})
+_ORDER_CONSTANT_NAMES: dict[tuple[Role, ...], str] = {
+    GIVEN_FIRST: "GIVEN_FIRST",
+    FAMILY_FIRST: "FAMILY_FIRST",
+    FAMILY_FIRST_GIVEN_LAST: "FAMILY_FIRST_GIVEN_LAST",
+}
+
+
+def _order_repr(value: tuple[Role, ...]) -> str:
+    # Unreachable via Policy's constructor (its __post_init__ restricts
+    # name_order to the three named orders) but REACHABLE via
+    # PolicyPatch, which defers name_order validation to apply time by
+    # design -- value may hold non-Role, even unhashable, elements. A
+    # value smuggled in through __setstate__ (which validates layout,
+    # not values) can also be a non-tuple container or not iterable at
+    # all. repr must never raise, so the named-lookup path is taken
+    # only for a TUPLE whose every element is confirmed a Role;
+    # everything else renders via repr(value). (The annotation states
+    # the Policy-side truth; the PolicyPatch call site passes
+    # getattr-Any.)
+    if isinstance(value, tuple) and all(isinstance(r, Role) for r in value):
+        named = _ORDER_CONSTANT_NAMES.get(value)
+        if named is not None:
+            return named
+        return "(" + ", ".join(r.name for r in value) + ")"
+    return repr(value)
+
 
 # Single source for the migration hint raised by both Policy and
 # PolicyPatch when patronymic_rules gets a non-iterable (True is the
@@ -225,6 +250,10 @@ class Policy:
     def __post_init__(self) -> None:
         _reject_bare_string_order(self.name_order)
         order = tuple(_require_iterable(self.name_order, "name_order"))
+        # Sole rejection point for plain-string tuples: Role is a StrEnum,
+        # so the named-order membership check below compares EQUAL for
+        # ("given", "middle", "family") -- do not remove this loop as
+        # redundant.
         for element in order:
             if not isinstance(element, Role):
                 raise TypeError(
@@ -326,28 +355,32 @@ class Policy:
     def __repr__(self) -> str:
         # Bounded: only fields that deviate from the default are shown
         # (design rule, see nameparser._types module docstring).
-        constant_names = {
-            GIVEN_FIRST: "GIVEN_FIRST",
-            FAMILY_FIRST: "FAMILY_FIRST",
-            FAMILY_FIRST_GIVEN_LAST: "FAMILY_FIRST_GIVEN_LAST",
-        }
         parts = []
         for f in dataclasses.fields(self):
             value = getattr(self, f.name)
             if value == f.default:
                 continue
             if f.name == "name_order":
-                # __post_init__ restricts to the three named orders, so
-                # the fallback is unreachable via the constructor; kept
-                # because repr must never raise (e.g. a smuggled
-                # __setstate__ value -- layout is validated, values not).
-                order_repr = constant_names.get(
-                    value, "(" + ", ".join(r.name for r in value) + ")")
-                parts.append(f"name_order={order_repr}")
+                parts.append(f"name_order={_order_repr(value)}")
             else:
                 parts.append(f"{f.name}={value!r}")
         return f"Policy({', '.join(parts)})"
 
+    # -- editing ------------------------------------------------------
+
+    def patched(self, patch: PolicyPatch) -> Policy:
+        """Fold a :class:`PolicyPatch` onto this Policy and return the
+        combined Policy. Set-valued fields union with the patch's;
+        scalar fields are overridden by the patch; UNSET fields are
+        left alone. Patch VALUES are validated here (Policy's
+        constructor re-runs on the result), not at patch construction
+        -- see PolicyPatch. The maiden-wins canonicalization applies
+        to the combined result exactly as if it had been constructed
+        directly."""
+        if not isinstance(patch, PolicyPatch):
+            raise TypeError(f"patched() takes a PolicyPatch, got {patch!r}")
+        return apply_patch(self, patch)
+
 
 class _Unset(Enum):
     UNSET = auto()
@@ -432,6 +465,21 @@ class PolicyPatch:
         # class docstring ("Values are validated when the patch is
         # applied... not at patch construction").
 
+    def __repr__(self) -> str:
+        # Bounded: only fields the patch actually sets are shown; UNSET
+        # fields are omitted (design rule, see nameparser._types module
+        # docstring -- the sibling of Policy's deviation-only repr).
+        parts = []
+        for f in dataclasses.fields(self):
+            value = getattr(self, f.name)
+            if value is UNSET:
+                continue
+            if f.name == "name_order":
+                parts.append(f"name_order={_order_repr(value)}")
+            else:
+                parts.append(f"{f.name}={value!r}")
+        return f"PolicyPatch({', '.join(parts)})"
+
 
 def apply_patch(policy: Policy, patch: PolicyPatch) -> Policy:
     """Fold a PolicyPatch onto a Policy. Policy.__post_init__ re-runs via

{nameparser-2.0.0rc1 → nameparser-2.0.0rc2}/nameparser/_types.py

@@ -24,12 +24,15 @@ if TYPE_CHECKING:
     from nameparser._parser import Parser
 
 
-class Role(Enum):
+class Role(StrEnum):
     """The seven fields of a parsed name, one per :class:`Token`.
     Declaration order is the canonical field order everywhere
-    (``as_dict()``, ``comparison_key()``, rendering). Pass a member to
-    :meth:`ParsedName.tokens_for`; a member's ``.value`` is the field's
-    string name (``Role.GIVEN.value == "given"``)."""
+    (``as_dict()``, ``comparison_key()``, rendering). A StrEnum, like
+    :class:`AmbiguityKind`: members ARE their string values, so
+    ``token.role == "given"`` compares directly and
+    ``str(Role.GIVEN) == "given"``. Members order as strings, so
+    ``sorted()`` yields alphabetical order -- iterate ``Role`` itself
+    for the canonical order."""
 
     # Declaration order IS the canonical field order (conventions §3):
     # every listing of the seven fields anywhere derives from this.
@@ -74,10 +77,16 @@ class Span(NamedTuple):
         )
 
 
-#: Stable, documented tag vocabulary (API). All other tags are
-#: namespaced ("vocab:...", "patronymic:...") and unstable. "joined"
-#: marks a continuation token of a merged piece (the ph-d merge) and
-#: drives the suffix view's space-vs-comma join.
+#: The four :attr:`Token.tags` values that are stable API.
+#: "particle" marks a word from the particle vocabulary ("de", "van")
+#: wherever it lands -- including a given-name "Van" -- so combine it
+#: with Role.FAMILY (as family_particles does) to get actual family
+#: particles; "conjunction" a joining word ("and", "y"); "initial" an
+#: initial-shaped word ("J.", "Q");
+#: "joined" a continuation of the previous token within one merged
+#: piece ("Ph." + "D."), which the suffix view joins with a space
+#: instead of ", ". Every other tag is namespaced ("vocab:...") and is
+#: unstable debugging provenance -- never match against those.
 STABLE_TAGS = frozenset({"particle", "conjunction", "initial", "joined"})
 
 #: The one sanctioned view-reorder marker (namespaced = unstable API).
@@ -154,10 +163,10 @@ class Token:
     span: Span | None
     #: The field this token belongs to.
     role: Role
-    #: Classification labels. Exactly the four in STABLE_TAGS
-    #: ("particle", "conjunction", "initial", "joined") are API;
-    #: namespaced tags like "vocab:..." are unstable debugging
-    #: provenance -- never match against them.
+    #: Classification labels. Exactly the four members of
+    #: :data:`~nameparser.STABLE_TAGS` ("particle", "conjunction",
+    #: "initial", "joined") are API; namespaced tags like "vocab:..."
+    #: are unstable debugging provenance -- never match against them.
     tags: frozenset[str] = frozenset()
 
     # in the class body so @dataclass(slots=True) keeps them
@@ -253,9 +262,10 @@ class AmbiguityKind(StrEnum):
     #: Smith B"). Which name part was declined depends on position and
     #: ``name_order``, so ``detail`` names it rather than the kind.
     SUFFIX_OR_NAME = "suffix-or-name"
-    #: A leading ambiguous particle was read as a given name -- "Van
-    #: Johnson" parses given="Van", but "Van" is also a family-name
-    #: particle in other names.
+    #: A leading ambiguous particle was read as a given name -- the
+    #: right call for "Van Johnson" (the actor's given name), the
+    #: wrong one for a bare "Van Buren" (the presidential surname);
+    #: the two-word shape cannot distinguish them.
     PARTICLE_OR_GIVEN = "particle-or-given"
     #: A nickname/maiden delimiter opened without closing (or closed
     #: without opening); the text was kept as literal name content, so
@@ -317,12 +327,31 @@ class Ambiguity:
         return f"Ambiguity({self.kind.value!r}: {texts})"
 
 
+def _validated_field_strings(fields: dict[str, str]) -> dict[Role, str]:
+    """Shared by ParsedName.replace and Parser.revise: validate a
+    **fields mapping of role names to replacement strings and key it
+    by Role. TypeErrors match replace()'s historical wording."""
+    by_value = {role.value: role for role in Role}
+    for key, value in fields.items():
+        if key not in by_value:
+            raise TypeError(
+                f"unknown field {key!r}; expected one of "
+                f"{', '.join(by_value)}"
+            )
+        if not isinstance(value, str):
+            raise TypeError(
+                f"field {key!r} must be a str, got {value!r}"
+            )
+    return {by_value[k]: v for k, v in fields.items()}
+
+
 @dataclass(frozen=True, slots=True)
 class ParsedName:
     """The immutable result of parsing one name string. Read the seven
     fields as strings (``.given``, ``.family``, ...); inspect structure
     through :attr:`tokens` / :meth:`tokens_for`; correct a parse with
-    :meth:`replace` (returns a new value); produce output with
+    :meth:`replace` (returns a new value; Parser.revise is the
+    tag-preserving form); produce output with
     :meth:`render`, :meth:`initials`, :meth:`capitalized`, or ``str()``.
 
     Constructor-enforced invariants: spans ascending, non-overlapping,
@@ -492,10 +521,14 @@ class ParsedName:
 
     # -- structured access ----------------------------------------------
 
-    def tokens_for(self, role: Role) -> tuple[Token, ...]:
+    def tokens_for(self, role: Role | str) -> tuple[Token, ...]:
+        """The tokens of one field, in document order. Takes a Role
+        member or its string value; anything else raises ValueError
+        naming the valid roles."""
+        role = _coerce_enum(role, Role, "Role", "roles")
         return tuple(t for t in self.tokens if t.role is role)
 
-    def as_dict(self, include_empty: bool = True) -> dict[str, str]:
+    def as_dict(self, *, include_empty: bool = True) -> dict[str, str]:
         # _text_for handles the suffix ", "-join (single-role SUFFIX call)
         d = {role.value: self._text_for(role) for role in Role}
         if not include_empty:
@@ -509,35 +542,49 @@ class ParsedName:
         synthetic tokens (span=None). Whitespace-splits each value; an
         empty value clears the field. original is unchanged (provenance).
         Ambiguities referencing replaced tokens are dropped.
-        """
-        by_value = {role.value: role for role in Role}
-        for key, value in fields.items():
-            if key not in by_value:
-                raise TypeError(
-                    f"unknown field {key!r}; expected one of "
-                    f"{', '.join(by_value)}"
-                )
-            if not isinstance(value, str):
-                raise TypeError(
-                    f"field {key!r} must be a str, got {value!r}"
-                )
-
-        def synthetic(value: str, role: Role) -> list[Token]:
-            return [Token(word, None, role) for word in value.split()]
 
-        replaced = {by_value[k]: v for k, v in fields.items()}
+        Replacement tokens carry NO tags, so tag-driven views degrade:
+        family_particles empties, particles regain their initials, and
+        a multi-word suffix is comma-joined. Parser.revise() is the
+        tag-preserving alternative.
+        """
+        replaced = _validated_field_strings(fields)
+        synthetic = {
+            role: tuple(Token(word, None, role) for word in value.split())
+            for role, value in replaced.items()
+        }
+        return self._with_field_tokens(synthetic)
+
+    def _with_field_tokens(
+        self, replaced: Mapping[Role, tuple[Token, ...]],
+    ) -> ParsedName:
+        """Shared tail of replace()/Parser.revise(): splice each role's
+        replacement tokens in at the role's first position (appended in
+        canonical order when the role had no tokens); drop ambiguities
+        whose referents were replaced."""
+        # Private contract, made self-enforcing: a token filed under a
+        # key that is not its own role is the one way this shared tail
+        # could build a semantically wrong ParsedName (the splice keys
+        # on the mapping, the views key on the token).
+        for role, toks in replaced.items():
+            for tok in toks:
+                if tok.role is not role:
+                    raise ValueError(
+                        f"replacement token {tok.text!r} has role "
+                        f"{tok.role.value}, not {role.value}"
+                    )
         new_tokens: list[Token] = []
         emitted: set[Role] = set()
         for tok in self.tokens:
             if tok.role in replaced:
                 if tok.role not in emitted:
-                    new_tokens.extend(synthetic(replaced[tok.role], tok.role))
+                    new_tokens.extend(replaced[tok.role])
                     emitted.add(tok.role)
                 continue
             new_tokens.append(tok)
         for role in Role:
             if role in replaced and role not in emitted:
-                new_tokens.extend(synthetic(replaced[role], role))
+                new_tokens.extend(replaced[role])
         kept = tuple(
             amb for amb in self.ambiguities
             if all(t in new_tokens for t in amb.tokens)
@@ -557,7 +604,10 @@ class ParsedName:
                 parser: Parser | None = None) -> bool:
         """Component-wise case-insensitive comparison (the semantic
         layer; __eq__ stays strict). A str argument is parsed with
-        `parser`, or the default parser when None."""
+        `parser`, or with the DEFAULT parser when None -- if this name
+        came from a custom Parser, pass that parser (or use
+        Parser.matches); otherwise the comparison silently runs under
+        the wrong configuration."""
         if isinstance(other, str):
             import nameparser._parser as _parser
             active = parser if parser is not None else _parser._default_parser()
@@ -600,7 +650,9 @@ class ParsedName:
                     force: bool = False) -> ParsedName:
         """Case-fixing transform -> new ParsedName, same spans, new
         token texts. Needs a lexicon for capitalization_exceptions and
-        particle rules; None uses the default lexicon. force=False
-        preserves mixed-case input (v1 parity). Idempotent."""
+        particle rules; None uses the DEFAULT lexicon -- if this name
+        came from a custom Parser, pass its lexicon or use
+        Parser.capitalized. force=False preserves mixed-case input
+        (v1 parity). Idempotent."""
         import nameparser._render as _render
         return _render.capitalized(self, lexicon, force=force)

{nameparser-2.0.0rc1 → nameparser-2.0.0rc2}/nameparser/_version.py

@@ -5,5 +5,5 @@ VERSION = (2, 0, 0)
 #: PEP 440 pre-release/dev segment appended to the numeric version, or
 #: "" for a final release. Joined WITHOUT a dot ("2.0.0rc1", not
 #: "2.0.0.rc1"); setuptools reads __version__ as the package version.
-PRE_RELEASE = "rc1"
+PRE_RELEASE = "rc2"
 __version__ = ".".join(map(str, VERSION)) + PRE_RELEASE