[derek73]

Closes #1007. Decided in chat 2026-11-02.

Merges before 2.8.1 is released, after #1010. 2.8.1 (#1011, on 2.x) carries the deprecation warning for this removal, and its messages link to the 3.0 migration guide this PR writes, so master gets it first (decided in chat); 3.0 is not released before 2.8.1.

What goes, what replaces it

These eight modules are removed:

• nameparser.config.titles
• nameparser.config.suffixes
• nameparser.config.particles
• nameparser.config.conjunctions
• nameparser.config.bound_given_names
• nameparser.config.given_names
• nameparser.config.maiden_markers
• nameparser.config.capitalization

Each was a row of NAME = _compiled.NAME assignments under a docstring that restated the rules. Those docstrings rendered as API reference and no test checked them.

The replacement is Lexicon.words(kind=..., **properties), merged in #1009. docs/migrate.rst gets a "Vocabulary constants → Lexicon.words" table with one call per 2.x constant. A set the compiler derives from a clash between readings is a comprehension over words and readings_of (TITLES_AMBIGUOUS is a title word with a given reading and no particle reading; TITLES is the rest). TITLE_PHRASES, compiled from attaches, has no spelling, and its row says so. CAPITALIZATION_EXCEPTIONS is dict(Lexicon.default().capitalization_exceptions).

nameparser.config keeps:

• surnames, which now has __all__, so a star import no longer binds its assert_normalized;
• (regexes went with Remove nameparser.config.regexes, which the parser has not read since 2.0 (#1008) #1010.)

Code

• Lexicon.default() reads CAPITALIZATION_EXCEPTIONS from _compiled.
• tools/vocab/build.py's CONSTANTS roster is now a plain list of names, with no module column. _compiled.py's header says the sets are private, and it is rebuilt.
• Tests that imported the constants now import them from _compiled.
• test_contracts's frozen-constant sweep covers _compiled, with a floor of 24, and names _compiled.CAPITALIZATION_EXCEPTIONS as an exemption. Its quiet-import and star-import tests use surnames.
• test_layering checks that each of the eight modules raises ModuleNotFoundError.

Docs

• migrate.rst: the constants table above; a row in "What 3.0 removes"; the intro.
• customize.rst: points at words()/readings_of().
• usage.rst: the attach table names each row's reading kind instead of a module link.
• modules.rst: documents nameparser.config, surnames and regexes.
• Contributor docs: the vocab README; AGENTS.md's configuration-layer section, whose set descriptions are kept, now keyed by set rather than module; mechanisms.md's recipe.
• decisions/3-0-reevaluations: a 2026-11-02 Should from nameparser.config.titles import TITLES still work in 3.0, now that Lexicon.readings_of() answers what a word is? #1007 entry. It supersedes the Remove the 1.x vocabulary names (PREFIXES, FIRST_NAME_TITLES, …) and their bridge #357 entry's "the vocabulary modules stay" and the 2026-10-29 Lexicon-warning waiver, since 2.8.1 carries that warning now. The Standing lines are amended to match.
• Release log: a Breaking Changes bullet.

Tests and checks

• test_migrate_s_words_call_reproduces_each_2x_constant evaluates each code row of migrate.rst's table against the compiled set it replaces (20 rows).
• test_migrate_s_table_covers_every_compiled_constant checks that every 2.x constant has a row of its own, and checks the two-constant title row directly.
• Full suite: 34901 passed. mypy, ruff, sphinx-build -b doctest docs (0 failures), the HTML build and python -m doctest README.rst all pass. snapshot.py matches the snapshot.
• pytest -n0 -m serial (the benchmark guards): 42 passed, rerun at a normal load after a first run under load average 30–40 had failed on wall-clock timing.

Review

The independent review found no code defects. It found that TITLES had no row of its own (the shared row's call returns 816 words against TITLES' 786, and the coverage test passed on the name alone), a miscount in the decisions entry, two rows contradicting the removal, and stale AGENTS.md recipes; bae8c75 fixes them.

Rebased onto #1010

The branch is one commit rebased onto master after #1010 (fbcd08e). The seven conflicting files resolve so that both PRs hold:

• nameparser.config's one public module is surnames.
• The frozen-constant sweep exempts only _compiled.CAPITALIZATION_EXCEPTIONS.
• migrate.rst's removals table keeps both new rows. Its "Finding the sites" covers regexes and the eight vocabulary modules together: 2.8.1 warns where a constant is read, and a bare import stays quiet.
• The decisions file keeps both 2026-11-02 entries. The Remove the 1.x vocabulary names (PREFIXES, FIRST_NAME_TITLES, …) and their bridge #357 entry's header names both supersessions.
• The release log keeps all three Breaking bullets.

Three AGENTS.md lines that merged without a conflict marker are fixed too: the regexes bullet, and the public-surface lines that named it.

On the rebased tree, pytest (34895 passed) and the serial benchmarks (42 passed) pass, as do mypy, ruff, build.py --check, snapshot.py, sphinx-build -W -b html, the doc doctests and the README doctest.

🤖 Generated with Claude Code