nameparser 2.5.0__tar.gz → 2.7.0__tar.gz

{nameparser-2.5.0/nameparser.egg-info → nameparser-2.7.0}/PKG-INFO

@@ -1,12 +1,11 @@
 Metadata-Version: 2.4
 Name: nameparser
-Version: 2.5.0
+Version: 2.7.0
 Summary: A simple Python module for parsing human names into their individual components.
 Author-email: Derek Gulbranson <derek73@gmail.com>
-License: LGPL
+License-Expression: LGPL-2.1-or-later
 Keywords: names,parser
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: GNU Library or Lesser General Public License (LGPL)
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
@@ -36,12 +35,15 @@ nameparser parses human names into seven fields — title, given, middle,
 family, suffix, nickname, maiden. Results are immutable, configuration is
 composable, and locale packs are opt-in.
 
-📣 **nameparser 2.5 is out.** It reads junior and senior written in 45
-languages (``Antonio Pavlović mlađi``), keeps a title written before a
-family comma out of the surname (``Dr. Smith, John``), reads Chinese and
-Japanese credential and office words (``田中社長``), and gives a lone first
-name followed by V, I or X its last name back (``Malcolm X``). The `release
-log <https://nameparser.readthedocs.io/en/latest/release_log.html>`__ has
+📣 **nameparser 2.7 is out.** It is the first release working towards
+the new language and vocabulary model described in the `vocabulary
+model RFC <https://github.com/derek73/python-nameparser/blob/master/docs/design/vocabulary-model-rfc.md>`__.
+It introduces more nuanced handling of titles and particles
+(``Chief Justice John Roberts`` reads the title ``Chief Justice``,
+while ``Justice Smith`` keeps the given name ``Justice``), adjusts the
+default vocabulary to better align with example name corpora, and
+surfaces alternative name readings in the published API. The `release log
+<https://nameparser.readthedocs.io/en/latest/release_log.html>`__ has
 the details.
 
 Chinese, Japanese and Korean names written in their own scripts are read

{nameparser-2.5.0 → nameparser-2.7.0}/README.rst

@@ -7,12 +7,15 @@ nameparser parses human names into seven fields — title, given, middle,
 family, suffix, nickname, maiden. Results are immutable, configuration is
 composable, and locale packs are opt-in.
 
-📣 **nameparser 2.5 is out.** It reads junior and senior written in 45
-languages (``Antonio Pavlović mlađi``), keeps a title written before a
-family comma out of the surname (``Dr. Smith, John``), reads Chinese and
-Japanese credential and office words (``田中社長``), and gives a lone first
-name followed by V, I or X its last name back (``Malcolm X``). The `release
-log <https://nameparser.readthedocs.io/en/latest/release_log.html>`__ has
+📣 **nameparser 2.7 is out.** It is the first release working towards
+the new language and vocabulary model described in the `vocabulary
+model RFC <https://github.com/derek73/python-nameparser/blob/master/docs/design/vocabulary-model-rfc.md>`__.
+It introduces more nuanced handling of titles and particles
+(``Chief Justice John Roberts`` reads the title ``Chief Justice``,
+while ``Justice Smith`` keeps the given name ``Justice``), adjusts the
+default vocabulary to better align with example name corpora, and
+surfaces alternative name readings in the published API. The `release log
+<https://nameparser.readthedocs.io/en/latest/release_log.html>`__ has
 the details.
 
 Chinese, Japanese and Korean names written in their own scripts are read

{nameparser-2.5.0 → nameparser-2.7.0}/nameparser/__init__.py

@@ -27,6 +27,9 @@ from nameparser._types import (
     Ambiguity,
     AmbiguityKind,
     ParsedName,
+    Reading,
+    ReadingKind,
+    ReadingSource,
     Role,
     Segmentation,
     Segmenter,
@@ -38,7 +41,8 @@ __all__ = [
     # v1 (compatibility layer)
     "HumanName",
     # v2 core
-    "Span", "Role", "Token", "Ambiguity", "AmbiguityKind", "ParsedName",
+    "Span", "Role", "Token", "Ambiguity", "AmbiguityKind", "Reading",
+    "ReadingKind", "ReadingSource", "ParsedName",
     "STABLE_TAGS", "Segmentation", "Segmenter",
     "Lexicon", "Policy", "PolicyPatch", "PatronymicRule", "Script", "UNSET",
     "CapsSuffixes",

{nameparser-2.5.0 → nameparser-2.7.0}/nameparser/_config_shim.py

@@ -731,13 +731,19 @@ def _default_vocab() -> dict[str, frozenset[str]]:
     from nameparser.config.suffixes import (
         SUFFIX_ACRONYMS, SUFFIX_ACRONYMS_AMBIGUOUS, SUFFIX_WORDS,
     )
-    from nameparser.config.titles import GIVEN_NAME_TITLES, TITLES
+    from nameparser.config._titles_2_6_0 import TITLES_2_6_0
+    from nameparser.config.titles import (
+        GIVEN_NAME_TITLES, TITLES, TITLES_AMBIGUOUS)
     return {
         "prefixes": PARTICLES,
         "suffix_acronyms": SUFFIX_ACRONYMS,
         "suffix_not_acronyms": SUFFIX_WORDS,
         "suffix_acronyms_ambiguous": SUFFIX_ACRONYMS_AMBIGUOUS,
-        "titles": TITLES,
+        # 2.6.0's titles, less any word that is no title now: one a
+        # later release made a title only inside a title phrase
+        # (rules/H9) stays a v1 title, so remove() and `in` answer as
+        # they did; _build_snapshot reads it by the phrase
+        "titles": TITLES | (TITLES_2_6_0 & TITLES_AMBIGUOUS),
         "first_name_titles": GIVEN_NAME_TITLES,
         "conjunctions": CONJUNCTIONS,
         "bound_first_names": BOUND_GIVEN_NAMES,
@@ -1045,9 +1051,15 @@ class Constants:
         removal path.
         """
         from nameparser.config.conjunctions import CONJUNCTIONS_AMBIGUOUS
+        from nameparser.config.given_names import GIVEN_NAME_ABBREVIATIONS
         from nameparser.config.maiden_markers import MAIDEN_MARKERS
-        from nameparser.config.suffixes import GLUED_HONORIFICS
+        from nameparser.config.suffixes import (
+            AGNOMENS, GLUED_HONORIFICS, SUFFIX_WORDS_AMBIGUOUS)
         from nameparser.config.surnames import KOREAN_SURNAMES
+        from nameparser.config._titles_2_6_0 import TITLES_2_6_0
+        from nameparser.config.titles import (
+            AFTER_GIVEN_TITLES, TITLE_MODIFIERS, TITLE_PHRASES, TITLE_STYLES,
+            TITLES_AMBIGUOUS)
         # Every set field and every capitalization_exceptions key passes
         # _v1_matchable BEFORE any set algebra below: an entry v1 could
         # never match, or one Lexicon folds to empty (#582), is dropped
@@ -1070,6 +1082,27 @@ class Constants:
         conjunctions = matchable("conjunctions")
         bound = matchable("bound_first_names")
         titles = matchable("titles")
+        # A title 2.6.0 listed that a later release made a title only
+        # inside a title phrase (rules/H9) is in v1's default `titles`,
+        # where 2.6.0 had it, so remove(), discard() and `in` answer as
+        # they did (decisions/H9, 2026-10-26). Kept, it is read as the
+        # default reads it, by the phrase; removed, it is no title at
+        # all, as removing it made it in 2.6.0. The one 2.6.0 reading
+        # with no v1 spelling left is the word as a title everywhere:
+        # v1 can say "a title" or "not a title", and "a title" now means
+        # the phrase reading. A word 2.6.0 never listed (`dean`) is not
+        # in `moved`, so adding it is still a title everywhere, the 1.4
+        # recipe the phrase test honours below. Compared folded, as the
+        # two cross-set computations below are (#582), so a spelling
+        # Lexicon folds onto a moved word (`king。`) is read as it is.
+        moved = TITLES_2_6_0 & TITLES_AMBIGUOUS
+        kept_moved = frozenset(w for w in titles if _normalize(w) in moved)
+        phrase_only = ((TITLES_AMBIGUOUS - moved) | kept_moved
+                       if titles else frozenset())
+        # ...and the three intersections with the phrase vocabulary read
+        # the same folded spellings, or a folded moved word kept its
+        # phrase reading but lost its modifier one (`wing。`)
+        any_title = frozenset(_normalize(w) for w in titles | phrase_only)
         first_name_titles = matchable("first_name_titles")
         non_given = matchable("non_first_name_prefixes")
         ambiguous_acronyms = matchable("suffix_acronyms_ambiguous") & acronyms
@@ -1135,7 +1168,7 @@ class Constants:
         # v1 also had, later, at capitalize().
         try:
             lexicon = Lexicon(
-                titles=titles,
+                titles=titles - kept_moved,
                 # TRANSLATE, do not filter. The two versions build the same
                 # lookup key differently: v1 joins the raw title run and
                 # then applies lc(), which strips only the whole string's
@@ -1160,8 +1193,8 @@ 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: particles.py asserts its own data has
-                # no word in both NON_GIVEN_NAME_PARTICLES and
+                # a config v1 accepted: the vocabulary build refuses a
+                # shipped 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
@@ -1192,6 +1225,15 @@ class Constants:
                 # through this intersection.
                 conjunctions_ambiguous=CONJUNCTIONS_AMBIGUOUS & conjunctions,
                 bound_given_names=bound,
+                # likewise no v1 manager: an abbreviated given name
+                # reading over rules/H2's shape is 2.7 behavior (#789),
+                # so the set rides in the snapshot only, passed whole.
+                # No v1 knob reaches it, and none needs to: a word a v1
+                # caller ADDS to `titles` is a title wherever it stands,
+                # since the leading peel asks the title vocabulary before
+                # it weighs the shape, as it did in 1.4
+                # (`c.titles.add("chas")`)
+                given_name_abbreviations=GIVEN_NAME_ABBREVIATIONS,
                 # v1 Constants has no manager for these (#274 is 2.0
                 # behavior); the data module is the only source
                 maiden_markers=MAIDEN_MARKERS,
@@ -1207,6 +1249,59 @@ class Constants:
                 # stops mattering, the same rule ambiguous_acronyms gets
                 # against suffix_acronyms above.
                 honorific_tails=GLUED_HONORIFICS & suffix_words,
+                # likewise no v1 manager: the salutations ending a given
+                # part are 2.6 behavior (#835), so they ride in the
+                # snapshot only, and the one v1 knob that reaches them is
+                # deleting the title. Lexicon does not check this pair
+                # (classify reads a member only where it is a title too),
+                # so the intersection is kept for `_snapshot() ==
+                # Lexicon.default()` legibility, as conjunctions_ambiguous'.
+                after_given_titles=AFTER_GIVEN_TITLES & titles,
+                # likewise no v1 manager: a suffix word that is also a
+                # name is 2.7 behavior (#752), so it rides in the
+                # snapshot only. Intersect with the word set, as the
+                # tails are: Lexicon enforces the subset, and deleting
+                # the suffix word is the one v1 knob, which turns the
+                # reading off. agnomens is consulted only inside it, so
+                # its intersection is kept for legibility alone.
+                # A v1 caller who added such a word to suffix_acronyms
+                # had it read as a suffix through the acronym branch,
+                # so the word leaves the gate rather than raising at
+                # Lexicon's word-gate check (folded, as the two
+                # cross-set computations above are).
+                suffix_words_ambiguous=frozenset(
+                    w for w in SUFFIX_WORDS_AMBIGUOUS & suffix_words
+                    if _normalize(w) not in {
+                        _normalize(a) for a in acronyms - ambiguous_acronyms}),
+                agnomens=AGNOMENS & SUFFIX_WORDS_AMBIGUOUS & suffix_words,
+                # likewise no v1 manager: the title phrase (rules/H9) is
+                # 2.7 behavior (#752), so its sets ride in the snapshot
+                # only. A title that may be a given name is not in
+                # TITLES, so v1's `titles` holds one only where 2.6.0
+                # listed it (`moved`, above, read by the phrase), and one
+                # 2.6.0 never listed that a v1 caller ADDS to `titles` is
+                # a title wherever it stands, as it was in 1.4
+                # (`c.titles.add("dean")`, the documented recipe): the
+                # phrase test reads a word of titles_ambiguous only where
+                # it is not in titles. The
+                # knob that reaches the other three is deleting a title,
+                # which turns its modifier, style or phrase reading off
+                # with it; Lexicon checks none of them, so the
+                # intersections are kept for legibility, as
+                # after_given_titles' is.
+                # ...save where the caller emptied `titles`, v1's way to
+                # turn title detection off (customize.rst). A caller who
+                # REPLACES the list keeps the phrase reading of the words
+                # 2.6.0 never listed: v1 has no knob for them, and what a
+                # replaced list means for words it never held is not
+                # something it says. A moved word reads by whether the
+                # replaced list holds it, as any v1 title does
+                titles_ambiguous=phrase_only,
+                title_modifiers=TITLE_MODIFIERS & any_title,
+                title_styles=TITLE_STYLES & any_title,
+                title_phrases=frozenset(
+                    p for p in TITLE_PHRASES
+                    if all(w in any_title for w in p.split(" "))),
                 # 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.

{nameparser-2.5.0 → nameparser-2.7.0}/nameparser/_facade.py

@@ -700,10 +700,11 @@ class HumanName:
             if got or not words or not all(self._is_particle(w)
                                            for w in words):
                 return got
-            # rules/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
+            # rules/R3: "A part whose every word is a particle initials
+            # those particles: they are not acting as particles there"
+            # -- the Except bullet this quote opens; nothing survived
+            # the filter, so the whole group is particles
+            # (decisions/R3). 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

{nameparser-2.5.0 → nameparser-2.7.0}/nameparser/_lexicon.py

@@ -25,7 +25,10 @@ _VOCAB_FIELDS = (
     "titles", "given_name_titles", "suffix_acronyms", "suffix_words",
     "suffix_acronyms_ambiguous", "particles", "particles_ambiguous",
     "conjunctions", "conjunctions_ambiguous", "bound_given_names",
-    "maiden_markers", "surnames", "honorific_tails",
+    "given_name_abbreviations",
+    "maiden_markers", "surnames", "honorific_tails", "after_given_titles",
+    "suffix_words_ambiguous", "agnomens", "titles_ambiguous",
+    "title_modifiers", "title_styles", "title_phrases",
 )
 
 #: (marker, base, why) triples. Each marker QUALIFIES how entries of
@@ -55,21 +58,27 @@ _VOCAB_FIELDS = (
 #:   as a tail would peel a period-gated word off a real name), and
 #:   nothing needs the acronym half: the shipped tails are CJK
 #:   honorifics, which are words.
-#:   The same relation is asserted a second time in config/suffixes.py,
-#:   over the raw GLUED_HONORIFICS/SUFFIX_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
-#:   SHIPPED vocabulary to the invariant, as it is the only thing that
-#:   ever held a caller's own.
+#:   The shipped vocabulary holds the relation by construction: its
+#:   build puts a word in GLUED_HONORIFICS only through an `attached`
+#:   property on a word reading (tools/vocab/build.py). The check here
+#:   is the only thing that holds a caller's own.
 #:
-#: Two fields are deliberately NOT here and have no check of their own.
+#: Three fields are deliberately NOT here and have no check of their own.
 #: given_name_titles -- see the note in __post_init__ for why every
 #: attempt at one rejected working configurations. conjunctions_ambiguous
 #: -- an orphan is never consulted because both the classify fork and
 #: its ambiguity emitter require the base entry as well, so an orphan
 #: decides nothing, and AGENTS.md's invariants rule guards harm, not
-#: no-ops.
+#: no-ops. after_given_titles -- the same: classify tags a word from it
+#: only where the word is in titles too, so an orphan is never read.
+#: agnomens -- the same: classify reads it only for a word already in
+#: suffix_words_ambiguous, so an orphan decides nothing.
+#: title_modifiers, title_styles and title_phrases -- the same: the
+#: title phrase test (rules/H9) reads them only for words that are
+#: titles, so an orphan decides nothing. titles_ambiguous is no subset
+#: at all: its words are titles only inside a phrase, so a caller lists
+#: one there without listing it in titles, and one in both is a title
+#: everywhere.
 _SUBSET_FIELDS = (
     ("particles_ambiguous", "particles",
      "an orphan emits a spurious particle-or-given ambiguity"),
@@ -77,6 +86,8 @@ _SUBSET_FIELDS = (
      "an orphan silently becomes a period-gated suffix"),
     ("honorific_tails", "suffix_words",
      "an orphan splits the name and leaves the tail inside it"),
+    ("suffix_words_ambiguous", "suffix_words",
+     "an orphan silently becomes a suffix gated by the count"),
 )
 
 
@@ -100,7 +111,7 @@ _SUBSET_FIELDS = (
 #: 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")
+_PHRASE_FIELDS = ("given_name_titles", "maiden_markers", "title_phrases")
 
 
 #: Every character the parser reads as a full stop at a WORD'S EDGE
@@ -569,12 +580,14 @@ class Lexicon:
     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
+    construction and can never match. Three 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
+    the whole run space-joined, or that run's last word --
     ``maiden_markers`` is matched by lookahead, longest first, over
-    words that need not be markers on their own (``"z domu"``).
+    words that need not be markers on their own (``"z domu"``), and
+    ``title_phrases`` holds two-word phrases, stored space-joined and
+    matched against two adjacent title words (``"chief justice"``).
     Field docs below show examples, not full
     contents; inspect any field's shipped vocabulary directly, e.g.
     ``Lexicon.default().conjunctions``."""
@@ -583,7 +596,7 @@ class Lexicon:
     #: list: :data:`~nameparser.config.titles.TITLES`.
     titles: frozenset[str] = frozenset()
     #: Titles whose single name word, before or after them, reads as a
-    #: GIVEN name ("sheikh", "sister", ...) rather than a family name. Full
+    #: GIVEN name ("sir", "sister", ...) rather than a family name. Full
     #: default list: :data:`~nameparser.config.titles.GIVEN_NAME_TITLES`.
     given_name_titles: frozenset[str] = frozenset()
     #: Post-nominal acronym suffixes, matched with or without periods
@@ -658,6 +671,17 @@ class Lexicon:
     #: Full default list:
     #: :data:`~nameparser.config.bound_given_names.BOUND_GIVEN_NAMES`.
     bound_given_names: frozenset[str] = frozenset()
+    #: Given names written short ("chas" for Charles, "wm" for William,
+    #: Filipino "ma" for María). Period-marked and opening the part of
+    #: the name that carries the given name, an entry reads as that
+    #: given name, where an unlisted abbreviation there reads as a
+    #: title by its shape (rules/H2): "Chas. Smith" reads given
+    #: "Chas.", "Xyz. Smith" title "Xyz.". An entry also in ``titles``
+    #: is a title there, which is what listing it as one asks; anywhere
+    #: else an entry is read as it would be unlisted. Full default
+    #: list:
+    #: :data:`~nameparser.config.given_names.GIVEN_NAME_ABBREVIATIONS`.
+    given_name_abbreviations: frozenset[str] = frozenset()
     #: Marker words introducing a birth surname, routed to the maiden
     #: field ("née", "geb.", "rozená", ...). An entry may be a PHRASE
     #: ("z domu"): entries are matched by lookahead, longest first, so
@@ -692,6 +716,73 @@ class Lexicon:
     #: vocabulary is. Full default list:
     #: :data:`~nameparser.config.suffixes.GLUED_HONORIFICS`.
     honorific_tails: frozenset[str] = frozenset()
+    #: Salutations that read as a title where one ENDS the given part
+    #: after a family comma, written bare: "Doe, Jane Mrs" reads title
+    #: "Mrs" where an office or rank word there stays a middle name
+    #: ("Doe, John Pope"), rules/H8. A period-marked title word reads as
+    #: a title there whether listed here or not (rules/H5). Entries need
+    #: not also be in ``titles``; one that is not is never consulted.
+    #: Full default list:
+    #: :data:`~nameparser.config.titles.AFTER_GIVEN_TITLES`.
+    after_given_titles: frozenset[str] = frozenset()
+    #: Subset of suffix_words that are also borne as names ("fils",
+    #: "neto"). Read as a suffix only where the name has words to
+    #: spare, as an ambiguous acronym is: "Pedro Alves Neto" ends in a
+    #: suffix, "Ana Neto" keeps her family name, and either reading is
+    #: reported (rules/S11). Written in Title case in a name of mixed
+    #: case it leans to the name even with words to spare, and in lower
+    #: case it is the suffix after a comma that names the family,
+    #: unless it is also in ``agnomens``. Full default list:
+    #: :data:`~nameparser.config.suffixes.SUFFIX_WORDS_AMBIGUOUS`.
+    suffix_words_ambiguous: frozenset[str] = frozenset()
+    #: Subset of suffix_words_ambiguous whose writing says nothing:
+    #: an agnomen ("filho", "neto") is written in the case of the name
+    #: around it, so only the words to spare decide (rules/S11). An
+    #: entry outside suffix_words_ambiguous is never consulted. Full
+    #: default list: :data:`~nameparser.config.suffixes.AGNOMENS`.
+    agnomens: frozenset[str] = frozenset()
+    #: Titles that may also be a given name ("dean", "justice",
+    #: "major"), each read as a title only inside a title phrase: after a
+    #: modifier, a style, or a title it stands in ``title_phrases``
+    #: behind; or before "of" or a title it stands in ``title_phrases``
+    #: in front of. Elsewhere it is a name word, and where it opens the
+    #: name the parse reports ``title-or-name`` if a phrase of
+    #: ``title_phrases`` the parse can read holds it (rules/H9), so "Grace Smith", which no
+    #: phrase holds, reports nothing, and emptying ``title_phrases``
+    #: silences the report: "Dean Smith"
+    #: and "Mr Major Smith" read given "Dean" and "Major", "Dean of
+    #: Students Smith" and "Major General Smith" a title. An entry also
+    #: in ``titles`` is a title wherever it stands, which is what listing
+    #: it there asks, so the default lists these words here alone. Full
+    #: default list:
+    #: :data:`~nameparser.config.titles.TITLES_AMBIGUOUS`.
+    titles_ambiguous: frozenset[str] = frozenset()
+    #: Titles that only qualify a head title ("vice", "wing", "grand").
+    #: At the head of the name one is a title only with a head title
+    #: behind it in its run of titles, so "Wing Commander Lau" keeps the
+    #: title where "Wing Lau" reads "Wing" as the given name; after a
+    #: comma it is read as any title is (rules/H9), save one also in
+    #: ``titles_ambiguous``, which is read everywhere as at the head. One
+    #: standing before a word of ``titles_ambiguous`` puts that word in
+    #: a title phrase. Entries in neither ``titles`` nor
+    #: ``titles_ambiguous`` are never consulted. Full default
+    #: list: :data:`~nameparser.config.titles.TITLE_MODIFIERS`.
+    title_modifiers: frozenset[str] = frozenset()
+    #: Honorific styles ("hon", "excellency", "highness"): one standing
+    #: before a word of ``titles_ambiguous`` puts that word in a title
+    #: phrase, as in "The Hon. Justice Smith" (rules/H9). Entries in
+    #: neither ``titles`` nor ``titles_ambiguous`` are never consulted.
+    #: Full default list:
+    #: :data:`~nameparser.config.titles.TITLE_STYLES`.
+    title_styles: frozenset[str] = frozenset()
+    #: Two-word title phrases, a title and the title it qualifies
+    #: ("chief justice", "major general"), stored space-joined: a word
+    #: of ``titles_ambiguous`` on either side of one is in a title
+    #: phrase (rules/H9). A phrase is consulted only if it is two
+    #: words, each in ``titles`` or ``titles_ambiguous``. Full default
+    #: list:
+    #: :data:`~nameparser.config.titles.TITLE_PHRASES`.
+    title_phrases: frozenset[str] = frozenset()
     #: Lowercase word -> case mask used by capitalized(): the word's
     #: own letters and digits, each in the case it takes ("phd" ->
     #: "PhD"), laid over the word as written, so the one entry
@@ -739,9 +830,10 @@ class Lexicon:
         # the expensive one -- three working configurations broken
         # across two attempts. Do not add a third.
         #
-        # 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.
+        # The v2 form of the vocabulary build's check that a bound given
+        # name which is also a particle may be given (tools/vocab/build.py,
+        # check 9). The build guards the shipped data; this guards
+        # vocabulary a caller supplies.
         contradictory = (
             self.bound_given_names & self.particles) - self.particles_ambiguous
         if contradictory:
@@ -765,6 +857,22 @@ class Lexicon:
                 f"period gate suffix_acronyms_ambiguous exists to impose"
             )
 
+        # the mirror of the check above: suffix_as_written ORs the
+        # unambiguous acronym branch too, so a gated suffix word listed
+        # there is claimed as a suffix with no count ('Ana Neto' would
+        # lose her family name, rules/S11)
+        word_gate_bypassed = self.suffix_words_ambiguous & (
+            self.suffix_acronyms - self.suffix_acronyms_ambiguous)
+        if word_gate_bypassed:
+            raise ValueError(
+                f"an ambiguous suffix word must not also be an unambiguous "
+                f"suffix acronym; in both: "
+                f"{', '.join(sorted(word_gate_bypassed))}. The acronym "
+                f"branch matches it outright, which bypasses the count "
+                f"suffix_words_ambiguous exists to impose; drop it from "
+                f"suffix_acronyms or from suffix_words_ambiguous"
+            )
+
     # -- constructors ----------------------------------------------------
 
     @classmethod
@@ -820,7 +928,10 @@ class Lexicon:
         # Lexicon field layout (version skew) -- silently loading it
         # would defer the failure to some distant attribute read.
         # Message kept in sync with _types._guarded_setstate by design
-        # (layering keeps this module import-free of _types).
+        # (layering keeps this module import-free of _types). Unlike
+        # that guard it admits no field added later (`ADDED_IN`, 2.7):
+        # every Lexicon field is still required, so a release adding one
+        # breaks older Lexicon pickles until this learns the marker.
         expected = {f.name for f in dataclasses.fields(Lexicon)} - {"_cap_map"}
         if set(state) != expected:
             missing = ", ".join(sorted(expected - set(state))) or "none"
@@ -937,17 +1048,20 @@ class Lexicon:
 def _default_lexicon() -> Lexicon:
     # v1 data modules are the single source of vocabulary through 2.x.
     from nameparser.config.bound_given_names import BOUND_GIVEN_NAMES
+    from nameparser.config.given_names import GIVEN_NAME_ABBREVIATIONS
     from nameparser.config.capitalization import CAPITALIZATION_EXCEPTIONS
     from nameparser.config.conjunctions import (
         CONJUNCTIONS, CONJUNCTIONS_AMBIGUOUS)
     from nameparser.config.maiden_markers import MAIDEN_MARKERS
     from nameparser.config.particles import NON_GIVEN_NAME_PARTICLES, PARTICLES
     from nameparser.config.suffixes import (
-        GLUED_HONORIFICS, SUFFIX_ACRONYMS, SUFFIX_ACRONYMS_AMBIGUOUS,
-        SUFFIX_WORDS,
+        AGNOMENS, GLUED_HONORIFICS, SUFFIX_ACRONYMS, SUFFIX_ACRONYMS_AMBIGUOUS,
+        SUFFIX_WORDS, SUFFIX_WORDS_AMBIGUOUS,
     )
     from nameparser.config.surnames import KOREAN_SURNAMES
-    from nameparser.config.titles import GIVEN_NAME_TITLES, TITLES
+    from nameparser.config.titles import (
+        AFTER_GIVEN_TITLES, GIVEN_NAME_TITLES, TITLE_MODIFIERS, TITLE_PHRASES,
+        TITLE_STYLES, TITLES, TITLES_AMBIGUOUS)
 
     # every vocabulary constant is a frozenset since #293, so each one
     # feeds its strictly-typed frozenset[str] field as it stands -- and
@@ -972,9 +1086,17 @@ def _default_lexicon() -> Lexicon:
         conjunctions=CONJUNCTIONS,
         conjunctions_ambiguous=CONJUNCTIONS_AMBIGUOUS,
         bound_given_names=BOUND_GIVEN_NAMES,
+        given_name_abbreviations=GIVEN_NAME_ABBREVIATIONS,
         maiden_markers=MAIDEN_MARKERS,
         surnames=KOREAN_SURNAMES,
         honorific_tails=GLUED_HONORIFICS,
+        after_given_titles=AFTER_GIVEN_TITLES,
+        suffix_words_ambiguous=SUFFIX_WORDS_AMBIGUOUS,
+        agnomens=AGNOMENS,
+        titles_ambiguous=TITLES_AMBIGUOUS,
+        title_modifiers=TITLE_MODIFIERS,
+        title_styles=TITLE_STYLES,
+        title_phrases=TITLE_PHRASES,
         # 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

{nameparser-2.5.0 → nameparser-2.7.0}/nameparser/_parser.py

@@ -41,7 +41,7 @@ class Parser:
     vocabulary DECLINES, so a locale pack's surnames always win where
     they match; returning None declines in turn and the token stays
     whole. Two promises narrow when one is supplied (the first is
-    rules/A1's Accepted clause):
+    rules/A1's Accepted bullet "The one exception to totality"):
     parse-totality gains its one exception -- an exception raised by
     the segmenter propagates, because a user-supplied callable's own
     error is a user-code error, not a content error -- and this Parser
@@ -215,7 +215,7 @@ class Parser:
             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
+            # as a name ('RA 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

{nameparser-2.5.0 → nameparser-2.7.0}/nameparser/_pipeline/_assemble.py

@@ -3,7 +3,7 @@
 Consumes: tokens (all roles set), dropped, ambiguities (by index;
 one carrying ``field_tail`` is worded from its word's final role,
 #626), and segments, for the part a withdrawn connective report's
-letter ends (rules/P3, #721).
+letter ends (rules/P8, #721).
 Produces: a validated ParsedName -- the constructor re-checks every
 invariant (span order/bounds, ambiguity subset), so a pipeline bug
 that would produce an invalid result dies HERE, not in a renderer
@@ -21,12 +21,42 @@ tests/v2/pipeline/test_assemble.py.
 """
 from __future__ import annotations
 
-from nameparser._pipeline._state import FIELD_READING, NAME_ROLES, ParseState
+from nameparser._pipeline._state import (
+    FIELD_READING, NAME_ROLES, Beside, Deferred, ParseState,
+    PendingAmbiguity,
+)
 from nameparser._types import (
-    Ambiguity, AmbiguityKind, ParsedName, Role, Token,
+    FOLDED_TAG, Ambiguity, AmbiguityKind, ParsedName, Reading, Role, Token,
 )
 
 
+def _alternative(pending: PendingAmbiguity, materialized: tuple[Token, ...],
+                 final: dict[int, Token],
+                 middle_as_family: bool) -> Reading | None:
+    """The public Reading of a report's PendingReading, its field named
+    from the final roles where the emitter deferred it (O5's other
+    primary field) and folded as `middle_as_family` folds every middle
+    (rules/O6's neighbour, the policy's own fold)."""
+    alt = pending.alternative
+    if alt is None or not materialized:
+        return None
+    role = alt.role
+    if role is Deferred.OTHER_PRIMARY:
+        role = (Role.FAMILY if materialized[0].role is Role.GIVEN
+                else Role.GIVEN)
+    elif isinstance(role, Beside) and role.index in final:
+        front = final[role.index]
+        role = (role.unfolded
+                if FOLDED_TAG in front.tags and role.unfolded is not None
+                else front.role)
+    elif isinstance(role, (Deferred, Beside)):
+        # assign found no name position to name it from
+        return None
+    if middle_as_family and role is Role.MIDDLE:
+        role = Role.FAMILY
+    return Reading(alt.kind, role, alt.source)
+
+
 # rules/A2: "a name with no name content parses to the empty
 # name — every field empty, false as a boolean — while ambiguities
 # born from its punctuation survive on the empty result"
@@ -116,7 +146,7 @@ def assemble(state: ParseState) -> ParsedName:
                 and any(t.role in (Role.SUFFIX, Role.TITLE)
                         for t in materialized)):
             continue
-        # rules/P3: "unless no name word of its part stands to its
+        # rules/P8: "unless no name word of its part stands to its
         # right" -- nothing after the letter in its segment, or only
         # suffixes, titles, a maiden clause or a nickname: it connects
         # nothing, so the report goes (#721). Asked here for the reason
@@ -143,7 +173,10 @@ def assemble(state: ParseState) -> ParsedName:
                 continue
             detail = (f"{detail}{FIELD_READING[materialized[0].role]}"
                       f"{pending.field_tail}")
-        ambiguities.append(Ambiguity(pending.kind, detail, materialized))
+        ambiguities.append(Ambiguity(
+            pending.kind, detail, materialized,
+            _alternative(pending, materialized, final,
+                         state.policy.middle_as_family)))
     return ParsedName(original=state.original,
                       tokens=tuple(final.values()),
                       ambiguities=tuple(ambiguities))