nameparser 2.6.0__tar.gz → 2.8.0__tar.gz

{nameparser-2.6.0/nameparser.egg-info → nameparser-2.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nameparser
-Version: 2.6.0
+Version: 2.8.0
 Summary: A simple Python module for parsing human names into their individual components.
 Author-email: Derek Gulbranson <derek73@gmail.com>
 License-Expression: LGPL-2.1-or-later
@@ -35,24 +35,30 @@ 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.6 is out.** It keeps surnames that earlier releases
-read as credentials (``Luo Si``, ``Maria de Sa``, ``Ram Bahadur B.K.``),
-reads ``Wm`` and ``Md`` as the given names they abbreviate, recognizes more credentials after a comma
-(``John Smith, MBChB``), and adds an opt-in reading for names with two
-family names (``Gabriel García Márquez``). The `release log
+📣 **nameparser 2.8 is out, the last 2.x feature release.**
+
+⚠️ **HumanName is deprecated, and 3.0 removes it.** From 2.8 the 1.x
+compatibility layer — ``HumanName``, ``Constants`` and the shared
+``CONSTANTS`` — emits a ``DeprecationWarning`` where your code
+constructs it, loads it from a pickle, or changes the shared
+``CONSTANTS``. It keeps working through 2.x; ``parse()`` is the
+replacement, and `Coming from 1.x`_ below says where to start. After
+2.8 the 2.x line takes fixes only, and new work goes into 3.0.
+
+2.8 also carries on 2.7's reading of titles that are also given names:
+a title only inside a title phrase, so ``Queen Latifah`` keeps the
+given name ``Queen`` while ``Her Majesty Queen Elizabeth`` reads the
+title. The `release log
 <https://nameparser.readthedocs.io/en/latest/release_log.html>`__ has
-the details.
+the details. Please `open an
+issue <https://github.com/derek73/python-nameparser/issues>`__ for anything
+that parses wrong.
 
 Chinese, Japanese and Korean names written in their own scripts are read
 family-first, unspaced Korean names are split against the census surname
 list, and CJK honorifics are recognized. See `East Asian names
 <https://nameparser.readthedocs.io/en/latest/usage.html#east-asian-names>`__.
 
-Existing ``HumanName`` code from 1.x keeps working through 2.x, and most
-of it needs no changes; see `Coming from 1.x`_ below. Please `open an
-issue <https://github.com/derek73/python-nameparser/issues>`__ for anything
-that parses wrong.
-
 Installation
 ------------
 
@@ -124,8 +130,10 @@ Learn more
 Coming from 1.x
 ----------------
 
-``HumanName`` and ``CONSTANTS`` keep working in 2.0 — same imports, same
-attributes, same mutation API. What 2.0 removes is the batch of
+``HumanName`` and ``CONSTANTS`` keep working through 2.x — same imports,
+same attributes, same mutation API — and warn from 2.8 on, since 3.0
+removes them. Run your tests under ``python -W error::DeprecationWarning``
+to find the sites; a read of ``CONSTANTS`` does not warn. What 2.0 removes is the batch of
 deprecations 1.3 and 1.4 announced, so if your test suite runs clean on
 1.4 under ``python -W error::DeprecationWarning``, you are nearly done.
 Two things that check will not catch: four removals 1.4 never warned

{nameparser-2.6.0 → nameparser-2.8.0}/README.rst

@@ -7,24 +7,30 @@ 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.6 is out.** It keeps surnames that earlier releases
-read as credentials (``Luo Si``, ``Maria de Sa``, ``Ram Bahadur B.K.``),
-reads ``Wm`` and ``Md`` as the given names they abbreviate, recognizes more credentials after a comma
-(``John Smith, MBChB``), and adds an opt-in reading for names with two
-family names (``Gabriel García Márquez``). The `release log
+📣 **nameparser 2.8 is out, the last 2.x feature release.**
+
+⚠️ **HumanName is deprecated, and 3.0 removes it.** From 2.8 the 1.x
+compatibility layer — ``HumanName``, ``Constants`` and the shared
+``CONSTANTS`` — emits a ``DeprecationWarning`` where your code
+constructs it, loads it from a pickle, or changes the shared
+``CONSTANTS``. It keeps working through 2.x; ``parse()`` is the
+replacement, and `Coming from 1.x`_ below says where to start. After
+2.8 the 2.x line takes fixes only, and new work goes into 3.0.
+
+2.8 also carries on 2.7's reading of titles that are also given names:
+a title only inside a title phrase, so ``Queen Latifah`` keeps the
+given name ``Queen`` while ``Her Majesty Queen Elizabeth`` reads the
+title. The `release log
 <https://nameparser.readthedocs.io/en/latest/release_log.html>`__ has
-the details.
+the details. Please `open an
+issue <https://github.com/derek73/python-nameparser/issues>`__ for anything
+that parses wrong.
 
 Chinese, Japanese and Korean names written in their own scripts are read
 family-first, unspaced Korean names are split against the census surname
 list, and CJK honorifics are recognized. See `East Asian names
 <https://nameparser.readthedocs.io/en/latest/usage.html#east-asian-names>`__.
 
-Existing ``HumanName`` code from 1.x keeps working through 2.x, and most
-of it needs no changes; see `Coming from 1.x`_ below. Please `open an
-issue <https://github.com/derek73/python-nameparser/issues>`__ for anything
-that parses wrong.
-
 Installation
 ------------
 
@@ -96,8 +102,10 @@ Learn more
 Coming from 1.x
 ----------------
 
-``HumanName`` and ``CONSTANTS`` keep working in 2.0 — same imports, same
-attributes, same mutation API. What 2.0 removes is the batch of
+``HumanName`` and ``CONSTANTS`` keep working through 2.x — same imports,
+same attributes, same mutation API — and warn from 2.8 on, since 3.0
+removes them. Run your tests under ``python -W error::DeprecationWarning``
+to find the sites; a read of ``CONSTANTS`` does not warn. What 2.0 removes is the batch of
 deprecations 1.3 and 1.4 announced, so if your test suite runs clean on
 1.4 under ``python -W error::DeprecationWarning``, you are nearly done.
 Two things that check will not catch: four removals 1.4 never warned

{nameparser-2.6.0 → nameparser-2.8.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.6.0 → nameparser-2.8.0}/nameparser/_config_shim.py

@@ -4,7 +4,7 @@ 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
-``nameparser.util`` for ``lc()``, ``nameparser.config.regexes`` for
+``nameparser.util`` for ``lc()`` (as ``_lc``, the name that does not warn), ``nameparser.config.regexes`` for
 the read-only regexes proxy's underlying compiled patterns, and
 ``nameparser._lexicon``/``_policy``/``_parser`` for the ``_snapshot()``
 translation and the shared parser cache.
@@ -20,12 +20,16 @@ that cycle.
 """
 from __future__ import annotations
 
+import copy
 import functools
+import re
+import sys
 import warnings
 from collections.abc import (
     Callable, ItemsView, Iterable, Iterator, KeysView, Mapping, Set,
     ValuesView,
 )
+from types import FrameType
 from typing import NamedTuple, Self
 
 from nameparser._lexicon import (
@@ -33,7 +37,7 @@ from nameparser._lexicon import (
 )
 from nameparser._parser import Parser
 from nameparser._policy import PatronymicRule, Policy
-from nameparser.util import lc
+from nameparser.util import _lc as lc
 
 
 #: The eight multi-word entries the pre-2.0 DEFAULT vocabulary shipped.
@@ -712,12 +716,64 @@ _UNSET = object()
 _UNSET_KWARG = object()
 
 
+#: The migration guide every 2.8 removal message points at.
+MIGRATION_GUIDE = "https://nameparser.readthedocs.io/en/latest/migrate.html"
+
+# The 2.8 removal messages (decisions/3-0-reevaluations, 2026-10-28).
+# Each names code that type-checks and runs, pinned by
+# tests/v2/test_deprecations.py, and each opens with a fixed phrase
+# pyproject's filterwarnings ignores by message.
 _SHARED_MUTATION_MESSAGE = (
     "mutating the shared CONSTANTS singleton is deprecated and will be "
-    "removed in 3.0; build a Lexicon/Policy (or a private Constants "
-    "passed as HumanName(constants=...)) instead. See the migration "
-    "guide."
+    "removed in 3.0 with HumanName and Constants; configure a Parser "
+    "instead, e.g. Parser(lexicon=Lexicon.default().add(titles={'dean'})). "
+    f"See {MIGRATION_GUIDE}"
+)
+CONSTANTS_DEPRECATION = (
+    "Constants is deprecated and will be removed in 3.0 with HumanName; "
+    "configure a Parser instead, e.g. "
+    "Parser(lexicon=Lexicon.default().add(titles={'dean'})). "
+    f"See {MIGRATION_GUIDE}"
+)
+CONSTANTS_PICKLE_DEPRECATION = (
+    "Constants pickles stop loading in 3.0, when Constants is removed; "
+    "pickle a Parser instead, e.g. "
+    "Parser(lexicon=Lexicon.default().add(titles={'dean'})). "
+    f"See {MIGRATION_GUIDE}"
 )
+#: one message per manager class, keyed by name, for
+#: nameparser.config.__getattr__
+MANAGER_DEPRECATIONS = {
+    name: (
+        f"nameparser.config.{name} is deprecated and will be removed in "
+        f"3.0 with Constants; Lexicon fields take plain sets, e.g. "
+        f"Lexicon.default().add(titles={{'dean'}}). See {MIGRATION_GUIDE}"
+    )
+    for name in ("SetManager", "TupleManager", "RegexTupleManager")
+}
+
+
+def _quiet_setstate(new: object, state: dict[str, object], base: type,
+                    message: str) -> None:
+    """Restore a copy through its class's own ``__setstate__``.
+
+    ``copy.copy``/``copy.deepcopy`` reconstruct through ``__setstate__``,
+    which since 2.8 warns that a pickle was loaded, and a copy is no
+    load. ``base``'s own hook restores privately; a subclass's override
+    is called, as it was before 2.8, with only the load warning
+    filtered, by message. The filter is taken only then: entering
+    ``catch_warnings`` clears every module's warnings registry, so on
+    every copy it would re-show warnings the caller's filters show once
+    per line. A copy of the shared ``CONSTANTS`` stays quiet, as before:
+    a ``HumanName`` built on the copy still warns.
+    """
+    if type(new).__setstate__ is base.__setstate__:  # type: ignore[attr-defined]
+        new._restore(state)  # type: ignore[attr-defined]
+        return
+    with warnings.catch_warnings():
+        warnings.filterwarnings("ignore", message=re.escape(message),
+                                category=DeprecationWarning)
+        new.__setstate__(state)  # type: ignore[attr-defined]
 
 
 def _default_vocab() -> dict[str, frozenset[str]]:
@@ -731,13 +787,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,
@@ -780,9 +842,11 @@ class Constants:
 
     The module-level ``CONSTANTS`` singleton (below) has ``_shared``
     flipped to ``True``: any mutation reached through it emits
-    ``DeprecationWarning`` pointing at ``Lexicon``/``Policy`` and
-    ``HumanName(constants=...)``. A private ``Constants()`` never
-    warns -- only the shared instance is on the 3.0 removal path.
+    ``DeprecationWarning`` pointing at ``Lexicon``/``Policy``. Since 2.8
+    constructing a ``Constants``, copying one with ``copy()`` and
+    loading one from a pickle warn too, since the whole class goes in
+    3.0; the singleton is built without the warning, so importing
+    ``nameparser`` stays quiet.
     """
 
     _shared = False  # the CONSTANTS singleton flips this to True
@@ -830,6 +894,41 @@ class Constants:
         regexes: object = _UNSET_KWARG,
         patronymic_name_order: bool = False,
         middle_name_as_last: bool = False,
+    ) -> None:
+        # every construction warns, at the caller's line; the warnings
+        # registry, not a flag here, dedups repeats from one line
+        # (decisions/3-0-reevaluations, 2026-10-28)
+        warnings.warn(CONSTANTS_DEPRECATION, DeprecationWarning,
+                      stacklevel=2)
+        self._init(
+            prefixes=prefixes, suffix_acronyms=suffix_acronyms,
+            suffix_not_acronyms=suffix_not_acronyms,
+            suffix_acronyms_ambiguous=suffix_acronyms_ambiguous,
+            titles=titles, first_name_titles=first_name_titles,
+            conjunctions=conjunctions, bound_first_names=bound_first_names,
+            non_first_name_prefixes=non_first_name_prefixes,
+            capitalization_exceptions=capitalization_exceptions,
+            regexes=regexes, patronymic_name_order=patronymic_name_order,
+            middle_name_as_last=middle_name_as_last)
+
+    def _init(
+        self,
+        *,
+        prefixes: Iterable[str] | object = _UNSET_KWARG,
+        suffix_acronyms: Iterable[str] | object = _UNSET_KWARG,
+        suffix_not_acronyms: Iterable[str] | object = _UNSET_KWARG,
+        suffix_acronyms_ambiguous: Iterable[str] | object = _UNSET_KWARG,
+        titles: Iterable[str] | object = _UNSET_KWARG,
+        first_name_titles: Iterable[str] | object = _UNSET_KWARG,
+        conjunctions: Iterable[str] | object = _UNSET_KWARG,
+        bound_first_names: Iterable[str] | object = _UNSET_KWARG,
+        non_first_name_prefixes: Iterable[str] | object = _UNSET_KWARG,
+        capitalization_exceptions:
+            Mapping[str, str] | Iterable[tuple[str, str]] | object
+            = _UNSET_KWARG,
+        regexes: object = _UNSET_KWARG,
+        patronymic_name_order: bool = False,
+        middle_name_as_last: bool = False,
     ) -> None:
         # v1.4 parity constructor kwargs (#238/#242/#244 hardening); the
         # signature is spelled out rather than **kwargs so an unknown
@@ -915,19 +1014,20 @@ class Constants:
         """
 
     def _bump(self) -> None:
-        # stacklevel=3 is exact for the direct scalar-assignment path
-        # (user code -> Constants.__setattr__ -> here) and lands one
-        # frame short -- inside the manager's own add()/remove()/
-        # __setitem__ -- for the indirect manager-mutation path (user
-        # code -> manager method -> _changed() -> here), since a
-        # single warn() call can't be exact for both call depths at
-        # once. Either way the warning still fires from this module,
-        # not the manager's true caller, which is enough: only the
-        # DeprecationWarning's presence/category/message are load-
-        # bearing (see the specified test), not the reported line.
+        # A fixed stacklevel lands on the caller only for one call depth:
+        # a scalar arrives through __setattr__, a set's add() through
+        # _changed(), a dict's update() and |= through __setitem__ per
+        # key. Walk out of this module instead, as _lexicon's
+        # _warn_dead_entry does, so the warning names the caller's line;
+        # attributed here, Python's default filters hid it.
         if self._shared:
+            level = 2
+            frame: FrameType | None = sys._getframe(1)
+            while (frame is not None
+                   and frame.f_globals.get("__name__") == __name__):
+                frame, level = frame.f_back, level + 1
             warnings.warn(_SHARED_MUTATION_MESSAGE, DeprecationWarning,
-                          stacklevel=3)
+                          stacklevel=level)
         object.__setattr__(self, "_generation", self._generation + 1)
 
     def __setattr__(self, name: str, value: object) -> None:
@@ -981,7 +1081,27 @@ class Constants:
         v1 (which deepcopied __dict__): attributes OUTSIDE the known
         field surface -- e.g. ad-hoc names stashed on the instance --
         are not carried by copy() or pickling; only the enumerated
-        fields survive."""                          # #260
+        fields survive. Warns since 2.8, as construction does: a copy
+        is a new private ``Constants``, and ``CONSTANTS.copy()`` builds
+        one without calling the constructor."""      # #260
+        warnings.warn(CONSTANTS_DEPRECATION, DeprecationWarning,
+                      stacklevel=2)
+        return self._copy()
+
+    def __copy__(self) -> Constants:
+        new = object.__new__(type(self))
+        _quiet_setstate(new, self.__getstate__(), Constants,
+                        CONSTANTS_PICKLE_DEPRECATION)
+        return new
+
+    def __deepcopy__(self, memo: dict[int, object]) -> Constants:
+        new = object.__new__(type(self))
+        memo[id(self)] = new
+        _quiet_setstate(new, copy.deepcopy(self.__getstate__(), memo),
+                        Constants, CONSTANTS_PICKLE_DEPRECATION)
+        return new
+
+    def _copy(self) -> Constants:
         # An independent instance with its own generation counter and
         # its own manager callbacks -- not a shared-state alias like a
         # naive attribute-for-attribute copy would produce. v1's copy()
@@ -1045,10 +1165,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 import AFTER_GIVEN_TITLES
+        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
@@ -1071,6 +1196,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
@@ -1136,7 +1282,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
@@ -1193,6 +1339,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,
@@ -1216,6 +1371,51 @@ class Constants:
                 # 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.
@@ -1290,7 +1490,22 @@ class Constants:
         # DROPPED (#255: empty is always '' in 2.0).
         state = {k: v for k, v in state.items()
                  if k != "empty_attribute_default"}
-        self.__init__()  # type: ignore[misc]  # defaults, then overlay
+        warnings.warn(CONSTANTS_PICKLE_DEPRECATION, DeprecationWarning,
+                      stacklevel=2)
+        self._restore(state)
+
+    def _restore(self, state: dict[str, object]) -> None:
+        # defaults, then overlay. A subclass's own __init__ runs here as
+        # it did before 2.8; its super().__init__() would warn that a
+        # Constants was constructed, which a restore is not
+        if type(self).__init__ is Constants.__init__:
+            self._init()
+        else:
+            with warnings.catch_warnings():
+                warnings.filterwarnings(
+                    "ignore", message=re.escape(CONSTANTS_DEPRECATION),
+                    category=DeprecationWarning)
+                self.__init__()  # type: ignore[misc]
         # (managers re-wrapped below so _on_change points at THIS
         # instance, not whatever produced the incoming state)
         managers: dict[str, SetManager] = {}
@@ -1331,5 +1546,7 @@ class Constants:
                 object.__setattr__(self, name, state[name])
 
 
-CONSTANTS = Constants()
+# built past __init__, so importing nameparser never warns
+CONSTANTS = object.__new__(Constants)
+CONSTANTS._init()
 object.__setattr__(CONSTANTS, "_shared", True)

{nameparser-2.6.0 → nameparser-2.8.0}/nameparser/_facade.py

@@ -7,6 +7,7 @@ Layering: facade layer -- may import anything public plus _render.
 """
 from __future__ import annotations
 
+import copy
 import dataclasses
 import warnings
 from collections.abc import Iterator, Mapping
@@ -29,7 +30,8 @@ from typing import Any
 import nameparser.config  # noqa: F401
 
 import nameparser._render as _render
-from nameparser._config_shim import CONSTANTS, Constants, _cached_parser
+from nameparser._config_shim import (CONSTANTS, MIGRATION_GUIDE, Constants,
+                                     _cached_parser, _quiet_setstate)
 from nameparser._lexicon import _normalize, _spells_an_initial
 from nameparser._parser import Parser
 from nameparser._types import (FOLDED_TAG, UNCLASSIFIED_TAG,
@@ -60,6 +62,19 @@ _V1_HOOKS = (
 # whole module is deleted with the facade layer in 3.0.
 _WARNED_SUBCLASSES: set[type] = set()
 
+# The 2.8 removal messages (decisions/3-0-reevaluations, 2026-10-28);
+# the code each offers is pinned by tests/v2/test_deprecations.py.
+HUMANNAME_DEPRECATION = (
+    "HumanName is deprecated and will be removed in 3.0; use "
+    "nameparser.parse(text), whose fields are given and family where "
+    f"HumanName has first and last. See {MIGRATION_GUIDE}"
+)
+HUMANNAME_PICKLE_DEPRECATION = (
+    "HumanName pickles stop loading in 3.0, when HumanName is removed; "
+    "store parse(text).as_dict() or the original string instead. "
+    f"See {MIGRATION_GUIDE}"
+)
+
 
 def _empty_parsed() -> ParsedName:
     return ParsedName(original="", tokens=(), ambiguities=())
@@ -71,7 +86,8 @@ class HumanName:
     resolved from the bound ``Constants`` shim (dirty-tracked via its
     ``_generation``). Keeps every v1 spelling (``first``/``last`` over
     the core ``given``/``family``); the v1 parsing hooks are never
-    called (#280). Deleted with the facade layer in 3.0.
+    called (#280). Deprecated since 2.8, warning at every construction,
+    and deleted with the facade layer in 3.0.
     """
 
     def __init__(
@@ -101,6 +117,12 @@ class HumanName:
             raise TypeError(
                 f"constants must be a Constants instance, got {constants!r}"
             )
+        # every construction warns, at the caller's line (a subclass's
+        # super().__init__() is its author's line); never once per
+        # process, so a dependency's first HumanName cannot consume the
+        # warning meant for the caller's own
+        warnings.warn(HUMANNAME_DEPRECATION, DeprecationWarning,
+                      stacklevel=2)
         self._warn_overridden_hooks()
         self._C = constants
         self._snapshot_gen = -1  # forces first resolve
@@ -151,7 +173,8 @@ class HumanName:
                 f"{cls.__name__} overrides v1 parsing hooks "
                 f"({', '.join(overridden)}) that the 2.0 facade never "
                 f"calls; parsing is delegated to the core Parser. "
-                f"Migrate to the Lexicon/Policy API. See "
+                f"Migrate to the Lexicon/Policy API; HumanName is "
+                f"removed in 3.0. See "
                 f"https://github.com/derek73/python-nameparser/issues/280",
                 DeprecationWarning, stacklevel=3)
 
@@ -888,6 +911,28 @@ class HumanName:
         return state
 
     def __setstate__(self, state: dict[str, Any]) -> None:
+        # unpickling skips __init__, so the construction warning never
+        # reaches a pickle; this one does, at the pickle.loads line
+        warnings.warn(HUMANNAME_PICKLE_DEPRECATION, DeprecationWarning,
+                      stacklevel=2)
+        self._restore(state)
+
+    def __copy__(self) -> HumanName:
+        # copy.copy/deepcopy go through the state hooks, a subclass's
+        # included, and a copy is no pickle load (_quiet_setstate)
+        new = object.__new__(type(self))
+        _quiet_setstate(new, self.__getstate__(), HumanName,
+                        HUMANNAME_PICKLE_DEPRECATION)
+        return new
+
+    def __deepcopy__(self, memo: dict[int, object]) -> HumanName:
+        new = object.__new__(type(self))
+        memo[id(self)] = new
+        _quiet_setstate(new, copy.deepcopy(self.__getstate__(), memo),
+                        HumanName, HUMANNAME_PICKLE_DEPRECATION)
+        return new
+
+    def _restore(self, state: dict[str, Any]) -> None:
         c = state.get("C")
         self._C = CONSTANTS if c is None else c
         self._snapshot_gen = -1