nameparser 2.0: a new core API, with full compatibility through 2.x — direction and feedback #284

nameparser 2.0 is in design. This issue is the front door: the short version, links to the full design, and the specific feedback that would help most. There is no deadline — comment whenever; implementation will proceed in parallel and alphas will be announced here.

The promise

Code that runs warning-free on 1.4 keeps running on every 2.x release with identical results, getting at most DeprecationWarnings. HumanName continues to work as a compatibility layer. The old API is removed in 3.0, not 2.x, and only after every removal has warned first. If you use HumanName and don't customize configuration, 2.0 should be a non-event.

What's new

A second, immutable API alongside HumanName:

from nameparser import parse

name = parse("Dr. Juan Q. Xavier de la Vega III")
name.given         # "Juan"      (the new API says given/family, not first/last)
name.family        # "de la Vega"
name.family_base   # "Vega"

• parse() returns a frozen value object; no mutable state anywhere in the new API
• configuration becomes immutable Lexicon (vocabulary) + Policy (behavior) objects you build at startup — no more mutating shared CONSTANTS (which keeps working through 2.x, with a warning)
• family-first name order (Policy(name_order=FAMILY_FIRST)) and opt-in locale packs (RU, TR_AZ at 2.0.0; zh/ko/vi/ja staged)
• genuinely ambiguous parses are reported (name.ambiguities) instead of silently guessed
• still deterministic, rules-based, zero dependencies; Python ≥ 3.11

Read and comment

• The full RFC: RFC: nameparser 2.0 — a new core API #285 — line comments welcome there; it covers the API, migration mechanics, timeline, and rejected alternatives
• Milestone v2.0 — the tracked removals and changes

Feedback that would help most

1. Do you compare HumanName objects with == (especially against strings), or use them in sets/dicts? (2.0 changes this to object identity — warned since 1.3.0; matches()/comparison_key() are the replacements. The one silent behavior change.)
2. Do you subclass HumanName and override parsing methods? Tell us what the override does — we'd rather absorb it as a feature than break it silently (HumanName subclasses overriding parsing hooks silently lose their overrides under the 2.0 facade; detect and warn at construction #280).
3. Do you mutate CONSTANTS after startup, not just at import time?
4. Do you assign custom regexes to CONSTANTS.regexes? What for?
5. given/family instead of first/last in the new API — help or annoy?
6. Do you build anything on top of nameparser where the promise above would still break you?