Should a new method beside matches() treat names the vocabulary knows are the same as equal (Wm. Smith = William Smith, Jr. = Junior)? #1006

matches() compares two parsed names exactly, field by field, ignoring case. So two writings of the same person don't match, even where the vocabulary already knows the words are the same:

>>> parse("Wm. Smith").matches("William Smith")
False
>>> parse("John Smith Jr.").matches("John Smith Junior")
False
>>> parse("J. Doe").matches("John M. Doe")
False

#224, which added matches() and comparison_key() in 1.3.0, left leniency out on purpose: "No leniency options (initials matching, nickname equivalence) — that's record linkage territory and out of scope." That was decided before the vocabulary recorded equivalences. It does now, so the decision may be worth reconsidering.

What the vocabulary already knows

Since 2.6 the vocabulary is written per word, and a reading may carry same_as, the word it is a spelling of. On 2026-11-02, 203 readings carry one:

• given names written short: wm → william, chas → charles (13)
• generations: junior and jnr → jr (4)
• titles: capt → captain, rev → reverend, mister → mr (about 120, across the military, salutation, academic, office and style kinds)
• particles: the assimilated Arabic articles → al- (31)

Today only the given ones reach the parser (they compile to GIVEN_NAME_ABBREVIATIONS, so Chas. Smith reads given Chas.; rules/H2, the leading-abbreviation title). The rest are checked by the build and then dropped, so a comparison can't use them yet.

A new method, beside matches()

matches() keeps doing what it does today: an exact comparison, field by field. The lenient comparison would be a separate method, so a caller chooses which question to ask.

What the lenient method could forgive, roughly from safest to least safe

1. Spellings the vocabulary lists as the same word: Jr. = Junior, Capt. = Captain, Wm. = William. Every one is a curated equivalence, so this level can't produce a false match the vocabulary doesn't already claim.
2. An initial against the name it starts: J. Doe ≈ John Doe, and J. Doe ≈ John M. Doe when one name's initials contain the other's. This one can be wrong (J. Doe also fits Jane Doe), so whether it's on should be the caller's choice.
3. Fields one side leaves empty: a title, a middle name or a suffix present in only one name.
4. Nicknames (Bill ≈ William): a new, language-specific table, and outside the positional, language-agnostic design unless it is opt-in (perhaps per locale pack).

Please comment if you'd use it

Say what you are matching (author lists, deduplication, joining two datasets) and which of these differences you need it to forgive.

Open questions

• What is the new method called? It should probably sit on Parser too (as Parser.matches does), so a string argument is parsed with the caller's configuration.
• Should the comparison read equivalence from same_as? That means keeping same_as for every kind in the reading index, not only given.
• How does it treat fields matches() compares exactly: nickname, maiden, credentials?
• Could a comparison_key() variant fold level 1 (each word replaced by its same_as head), so it works for dict keys and deduplication, not only pairwise?
• Should this include transliteration of CKJ characters? 鄭和 is consistent with Zheng He?

🤖 Generated with Claude Code