[derek73]

README.rst is the PyPI project page, and its Quick Start still led with a 2.x-era example. This reworks the examples to show what 3.0 reads. The 3.0 announcement block is unchanged except for one new link.

Lead example. Dr. Juan Carlos García de la Vega III (Juanca) is parsed twice:

• With the default reading: given Juan, middle Carlos García, family de la Vega.
• With parser_for(locales.ES), which reads two family names (rules/O6, two family names): middle Carlos, family García de la Vega. The surname1, surname2 and generation views give García, de la Vega and III.
• With two_given_names (rules/O7, two given names), the given name reads Juan Carlos. The switch is a Policy field and not part of the ES pack, so the example passes it through base=.

Choosing languages. Two short blocks show what a pack's choice of languages does:

• A plain choice turns on readings the default leaves off. Lady Heidenreich reads title Lady by default, and given Lady under locales.ES. Lady Justice Jane Smith keeps title Lady Justice under it.
• A strict choice (strict=True) keeps only the chosen languages' words, the words every language shares, and words in other scripts. parser_for(locales.ES, strict=True) reads no title in Lady Justice Jane Smith. The README links to locales.html#reading-one-language-only.
• A pack can also remove a reading. Under FAMILY_FIRST_GIVEN_LAST, Nguyen Van Anh reads given Van Anh because the Dutch van chains on. parser_for(locales.VI) (Add locales.VI, a Vietnamese pack (#1108) #1112) reads family Nguyen, middle Van, given Anh: the pack reads family-first and removes van's particle reading. This replaces an earlier hand-built strict vi Locale, written before the pack existed.

More shapes, each showing something the others don't:

• a title run (The Rt Hon Sir John Smith KCB MP)
• a word that is a title only inside a title phrase (rules/H9): Dean Smith gives given Dean, and Associate Dean Jane Smith gives title Associate Dean
• a listing form whose suffix the generation and credentials views split (Smith, John V., Jr., MD, PhD)
• a Dutch index form with the particles last (Berg, Jan van der gives family van der Berg)
• an ambiguity report (Van Johnson)
• Reading.languages (the van in Ludwig van Beethoven gives ('nl',))

Views in the CJK and Arabic lines. The Korean honorific line now reads .honorifics. The Arabic line shows family and patronymic side by side, both 'بن سلمان' (rules/R9, the patronymic view). A following pair shows rules/P12 (a bound given name and the word that completes it): طارق عبد العزيز reads family عبد العزيز, because عبد before a name of God is one name. نوال عبد هاشم reads family هاشم, because هاشم is not on that list.

Russian. The old example showed only the family, so it never showed the patronymic. It now shows the default reading (given Сидоров) beside locales.RU's reading: given Иван, patronymic Петрович, family Сидоров.

Link. "configures a Lexicon by reading" in the announcement now links to https://nameparser.readthedocs.io/en/latest/customize.html#configuring-by-reading. The link is absolute so it works on PyPI too.

Jane Smith, PhD MA was cut, since the listing form covers credentials. No example has the nickname + one word + suffix shape that #815 is changing.

Adjusting readings. A new section, "When a reading is wrong for your data", comes before Learn more and uses the recipes from customize.rst:

• readings_of("dean") shows what a word may be read as.
• remove("dean", kind="given") makes Dean always a title, the other side of the Dean Smith example above.
• add("leed", "ap", kind="credential") adds a credential.
• A Policy(name_order=FAMILY_FIRST) parser reads Nagy Ádám as given Ádám, family Nagy.

Accuracy section. A new "How well it reads names" section after Learn more gives the figures that a 2026-11-05 measurement marked publishable. Each figure states its population and what it was compared with, and is dated, since nothing in the repository re-runs it:

• PatentsView inventors: 94.7% of 657,991 records, 98.0% outside Spanish- and Portuguese-speaking countries.
• UK PSC filings: 96.8% of 1,039,144 records, all four boxes.
• Czech candidates: 97.0% of 170,181, and 97.5% under locales.CS.
• ORCID, per country: Spain goes from 49.5% to 96.7% under locales.ES, and Mexico from 33.6% to 96.9%. The cost for Argentine patent inventors (93.8% by default, 86.2% under ES, 92.7% under ES_AR) is given beside it.

ORCID's overall figure and the CLDR, GND and Wikidata rates are left out. The CLDR names are fictional, and the other sources were sampled by shape rather than by frequency. The ES and Argentina figures come from the per-country score, which uses each group's first 20,000 records. The other figures come from local_agreement.py.

The old lead name is still in the user docs. Dr. Juan Q. Xavier de la Vega III also appears in docs/usage.rst:12, docs/index.rst:20, docs/concepts.rst, docs/customize.rst and docs/migrate.rst. It is still a correct default reading in each, so those are left unchanged.

Verification

• python -W error -m doctest README.rst: 60 passed at 8007cc5 on 3.11; 59 passed after merging master (with locales.VI), on 3.11 and 3.15, before the VI line was split in two. available() comes from master and lists vi. It also passes under PYTHONHASHSEED 0, 1 and 12345, and without the ja extra installed.
• python -m readme_renderer README.rst (PyPI's renderer): renders with no warnings beyond the usual one about the Markdown extra.
• The #configuring-by-reading anchor exists in the local Sphinx build and on the live Read the Docs page.

Reviews

• pr-review-toolkit:comment-analyzer (prose against the readings): every claim held. Four clarity changes were applied in cbbf81e: the default reading is described by position rather than as "English", the van example says what Reading.languages is, the Arabic example shows the family keeps the patronymic's words, and the Russian default line says it is read given-first.
• Example re-run (a general-purpose agent): ran the doctests on 3.11 and 3.15, ran PyPI's renderer, ran under several hash seeds and without the ja extra, checked for the Should 'Smitty' Jones Jr. read family 'Jones', as 'Smitty' Jones does? (N3 counts a suffix; H1 and M4 set it aside) #815 shape, and confirmed that the Ambiguity and Reading.languages reprs come out the same every run. All checks passed.
• The Dutch and title-phrase examples were added after these reviews, at the maintainer's request (cafa2a3). They were checked by the same doctest and render runs.
• pr-review-toolkit:comment-analyzer on the choosing-languages block (96187e8): the first draft said a choice "prefers" its language's reading, but for Lady it turns on a default-off given reading. It also left out that strict keeps words in other scripts. Both were fixed in b851c3b, which also adds the Lady Justice line.

🤖 Generated with Claude Code