[derek73]

This PR deletes the 1.x compatibility layer that 2.8.0 deprecated (#925, #935). It could be the first 3.0 alpha. Each kind of change is its own commit: the test port, the tools, the code, then the docs, each with its suite passing on its own. Four more commits fold in two review rounds, each followed by a review of its own fixes, and the last two settle the questions answered in review (below).

What goes

• HumanName (nameparser/_facade.py), nameparser.parser, and HumanName in nameparser.__all__.
• nameparser.config's Constants, CONSTANTS, SetManager, TupleManager and RegexTupleManager (nameparser/_config_shim.py). config/__init__.py is now a docstring only.
• nameparser.util.
• Remove the 1.x vocabulary names (PREFIXES, FIRST_NAME_TITLES, …) and their bridge #357's retired 1.x names: config/_deprecated.py, the prefixes.py and bound_first_names.py modules, FIRST_NAME_TITLES and SUFFIX_NOT_ACRONYMS.
• config/_titles_2_6_0.py, which only the facade read (Keep the titles 2.6.0 listed in v1's Constants().titles (#752) #904).
• The pickle-migration shims.
• The deprecation warnings, their filterwarnings entries, and tests/removals.py.

What stays

• The vocabulary data modules under nameparser.config, with __all__ now listing only their live constants.
• The core API, unchanged.

tests/v2/test_layering.py now checks that the removed names and modules stay gone. The ALLOWED table drops the facade's entries. _lexicon still imports only the config data modules.

Tests: sorted by the code they exercise

Collected tests drop from 32,931 on master to 30,696.

	Before	Ported to parse() / core	Deleted (facade only)
The 1.x suite, tests/test_*.py	750	577, plus 3 core readings whose only tests went through the facade	173
test_facade, test_facade_cases, test_config_shim, test_deprecations, test_config_aliases	2,084	10, moved into test_parser, test_render and test_contracts	2,074
Facade halves of other v2 tests (test_render, test_properties, test_locales, test_types, test_lexicon, test_benchmark, the tools tests)		each test keeps its core assertion	1 render test, 1 P7 site row, 2 benchmark rows, 1 lexicon entry-point row

test_layering also gains 16 rows that hold the removed names and modules gone.

The 1.x suite. A ported test keeps its assertion, with first/last read as given/family. Where a test configured Constants, it now builds a Lexicon or Policy. No expected value changed, and both xfails (#490) still fail under parse().

Deleted as facade-only: setters, *_list views, string equality, len/iteration, string_format and the other stored render defaults, Constants and its managers, pickling, and the deprecation warnings.

tests/base.py renames its helpers: ParsedNameTestBase, and FlaggedPolicyTestBase with policy_kwargs. TEST_NAMES now compares all seven fields across the comma variants on parse(), and picks the same five suffix names it did through the facade.

test_facade_cases.py ran the cases.py rows through the facade. test_cases.py runs every row through the core, so nothing is lost.

Recorded counts in test_properties.py that included the facade's arm (INV7's 7,860 and 8,054, and a few smaller controls) are dated, so they cannot be re-taken without the old tree. They are labelled as counted with the facade's half. The live controls still fail with the facade gone. Without it they read case-only substitution 64 (127 before), NFD initials 204 (408) and NFD repair 1,089 (2,629).

The facade's initials fallback for a spliced field gave j. s. where the core's replace() then initials() gives j. e. s.. It was facade-only, so it went with the facade. rules/R3 and decisions/R3 described it, and are amended.

Tools

• snapshot.py stops recording the facade key. The re-record drops it from the three rows that had it, the Ph. D. initials.
• load() sets a facade key aside, so --since v2.8.0 and old local snapshots compare cleanly. --since v2.8.0 reads "matches the snapshot".
• compare.py reads a 2.x baseline on the 2.0 surface, and a 1.x baseline through that release's own HumanName. The tree is read on parse() either way.
• --baseline 2.8.0 reads 0 of 6,533 entries differently.
• --baseline 1.4.0 reads 1,749 of 5,719 differently, against 1,751 on master (measured 2026-10-28). The two that dropped are Ph. D., John and one CLDR rendering. For the merged element, 1.4.0 and parse() both write P. D. where the facade wrote P D..
• tools/perf/call_count.py measures parse() alone. It reads 305 on 3.11, inside the band around 307. Its docstring now says the --modules tables recorded before 3.0 profiled HumanName.
• build_corpus.py read only HumanName(...) calls, so over the ported tests it returned 183 names with no warning. The working tree is now read by parse() and the helpers wrapping it (566 names). A --ref is still read by HumanName alone, so the pinned recipe reproduces corpus.jsonl byte for byte.

Docs

• migrate.rst is now "Migrating to 3.0". It covers what 3.0 removes and the replacement for each, how to find the sites, and the attribute and config maps as 1.x/2.x → 3.0.
  • Finding the sites means 2.8 under -W error::DeprecationWarning, plus a search for what 2.8 left quiet: reads of CONSTANTS, and imports whose names are never used or are used without construction (a subclass, isinstance, an annotation).
  • Every doctest that used HumanName now asserts the same reading through parse().
• The HumanName sections are removed from usage.rst, customize.rst, modules.rst (the data modules' autodoc stays, under "Default vocabulary"), concepts.rst and CONTRIBUTING.md.
• README: a 3.0 announcement replaces the 2.8 one.
• Release log: one bullet under 3.0.0 Unreleased.
• Root AGENTS.md: the facade bullets and the v1 Gotchas are gone (the facade layer, the shim TRANSLATES, HumanName.C, TupleManager, the delimiter sentinels, Constants attribute docstrings, the two-tier config, the debug-logging snippet for a logger the core never had). The test conventions now describe the ported suite. The Pickling bullet now says that Lexicon's copy of the guard admits no field added later (no ADDED_IN), so adding a Lexicon field breaks older Lexicon, Parser and locale-pack pickles; whether it should learn the marker is left open. The same bullet's "values are NOT re-validated" now names the shared guard only: Lexicon's __setstate__ re-runs __post_init__ and refuses entries that are not already normalized.
• docs/design:
  • mechanisms.md retires FACADE-CONTRACT and CONFIG-SHIM-SNAPSHOT (Trim the design docs: archive the differential ledger, tidy mechanisms.md, compact shipped measurements #759's precedent) and drops the facade from the entries that named it as a live site.
  • rules/R3, P8 and R4 stop describing the facade's initials view.
  • decisions/3-0-reevaluations records the removal and rewrites its Standing. M1, N1, P7, P8, R3, R4, R5, S9, comparison-surface, differential-ledger and parse-cost each gain a 2026-10-28 Remove the 1.x vocabulary names (PREFIXES, FIRST_NAME_TITLES, …) and their bridge #357 entry. The older entries those overtake are marked SUPERSEDED (edit kind 1).
  • rules_budget.json is re-recorded for the three rules that got shorter.

Checks

Run locally on the final tree:

• the full suite: 30,624 passed, 28 skipped, 3 xfailed
• -n0 -m serial: 41 passed. Two fewer than before, the facade's budget and timing rows
• uv run --python 3.15 pytest: 30,624 passed
• sphinx-build -b doctest and -b html: clean
• python -m doctest README.rst and readme_renderer: clean
• mypy and ruff: clean
• tools/vocab/build.py --check: current

#357's acceptance:

• grep -rn "PREFIXES\|NON_FIRST_NAME_PREFIXES\|BOUND_FIRST_NAMES\|FIRST_NAME_TITLES\|SUFFIX_NOT_ACRONYMS" nameparser/ docs/ AGENTS.md --exclude-dir=decisions hits only docs/release_log.rst. To get there, migrate.rst's bridge table went; the 2.2.0 release-log entry still maps the names.
  • The grep exempts docs/design/decisions/, and only that folder: a dated decisions entry records what was true when it was written and may name removed things, while the grep exists to keep live docs from teaching them. rules/ and mechanisms.md stay covered.
  • The check still bites: a probe line naming FIRST_NAME_TITLES appended to docs/usage.rst was reported, then removed.
• from nameparser.config.prefixes import PREFIXES raises ModuleNotFoundError, and from nameparser.config.titles import FIRST_NAME_TITLES raises ImportError. tests/v2/test_layering.py::test_the_1x_imports_fail runs both, plus SUFFIX_NOT_ACRONYMS and HumanName.
• No DeprecationWarning remains in nameparser/config/.

Review

The first round had three reviewers: code and tests, design docs, and user docs and claims. Its fixes are commit 5, and a review of that commit gave commit 6.

The second round had four: code and project rules, test coverage, stale comments across the whole tree, and the comparison tools. Its fixes are commit 7, and a review of that commit gave commit 8. It found no defect in live code. It found:

• comments in about 20 places that still described the removed layer, including notes on a facade runner in cases.py;
• one core reading tested only through the facade's setters, replace() splitting on whitespace runs, now in test_types.py;
• the star-import check, which covered two of the five config modules with an __all__;
• the build_corpus.py miss above, now also recorded in AGENTS.md;
• the case-only control, re-taken on the core alone: it fails on 64 repairs.

The comparison-tools reviewer showed each path reports a real difference (--since v2.7.0 27, --baseline 2.7.0 21, the 1.4.0 arm against the real wheel 1,749), and that a missing key raises rather than compares None == None.

The user-docs reviewer checked claims by running them:

• Every removed import fails as documented.
• 2.8.0 HumanName and Constants pickles fail to load with ModuleNotFoundError, and a 2.8.0 ParsedName pickle loads.
• Each attribute-map and config-map row works as written.
• Every converted doctest keeps its inputs and outputs.

Answered in review

• The folded family's particle views. The core's reading stands: family_base is the family without its particles, every one of them (da Silva do Amaral, Miguel gives base Silva Amaral). test_particle_views_after_fold pins it, and docs/migrate.rst's family_base row now says so (it said "leading particles split off", already wrong on master). The family_base and family_particles rows also record where they part from HumanName's last_base and last_prefixes, which split off only the leading particles ('Silva do Amaral', 'da', measured on the 2.8.0 wheel). rules/R2 still says "leading" and is amended to match the code in the separate 3.0 design PR. The test's comment quotes R2's current wording, so whichever of the two PRs merges second updates that quote, and the citation test fails on it until then.
• The decisions entry edited for the acceptance grep. Restored: decisions/3-0-reevaluations' 2026-10-28 Remove the 1.x vocabulary names (PREFIXES, FIRST_NAME_TITLES, …) and their bridge #357 entry quotes its alias example as written again, and the grep exempts docs/design/decisions/ (see Checks).

Closes #357

🤖 Generated with Claude Code