feat: maiden_delimiters wins on overlap; export DEFAULT_NICKNAME_DELIMITERS

derek73 · claude · derek73 · commit cc7063f6fcae · 2026-07-18T11:22:57.000-07:00
Routing parens to maiden used to require editing both delimiter
buckets in tandem, with the nickname default's contents discovered by
digging: a pair in both buckets silently parsed as nickname. Now
Policy canonicalizes the effective nickname set to
nickname_delimiters - maiden_delimiters (listing a pair in the
specific bucket IS the intent), so
Policy(maiden_delimiters={('(', ')')}) is the whole recipe -- same
canonicalization precedent as the name_order coercion, equal values
converge. The nickname default is now the public, documented
DEFAULT_NICKNAME_DELIMITERS constant for explicit set math.

The 1.x facade keeps v1's nickname-wins precedence (pinned by the v1
suite) via a shim-side pre-subtraction on the maiden bucket, pinned
by test_snapshot_overlap_keeps_v1_nickname_precedence. Case row
nickname_bucket_wins_when_shared becomes
maiden_delimiters_win_when_shared. Docs: customize one-liner example,
migrate precedence note, release-log entry, reference autodata.

Co-Authored-By: Claude Fable 5 &lt;noreply@anthropic.com&gt;
diff --git a/docs/customize.rst b/docs/customize.rst
@@ -74,11 +74,14 @@ listed below.
    * - ``nickname_delimiters``
      - ``frozenset[tuple[str, str]]``
      - Routes content enclosed by these delimiter pairs to
-       ``nickname``. Defaults to quotes and parentheses.
+       ``nickname``. Defaults to
+       :data:`~nameparser.DEFAULT_NICKNAME_DELIMITERS` — quotes and
+       parentheses.
    * - ``maiden_delimiters``
      - ``frozenset[tuple[str, str]]``
      - Routes content enclosed by these delimiter pairs to ``maiden``
-       instead. Defaults to empty — see the routing example below.
+       instead, and drops them from the effective nickname set.
+       Defaults to empty — see the routing example below.
    * - ``extra_suffix_delimiters``
      - ``frozenset[str]``
      - Adds separators (beyond a comma) that split suffix groups, e.g.
@@ -100,17 +103,16 @@ listed below.
 .. doctest::
 
     >>> from nameparser import Parser, Policy
-    >>> policy = Policy(
-    ...     nickname_delimiters=frozenset({("'", "'"), ('"', '"')}),
-    ...     maiden_delimiters=frozenset({("(", ")")}),
-    ... )
+    >>> policy = Policy(maiden_delimiters=frozenset({("(", ")")}))
     >>> Parser(policy=policy).parse("Jane (Jones) Smith").maiden
     'Jones'
 
-Routing parentheses to ``maiden`` means moving that pair out of
-``nickname_delimiters`` as well as into ``maiden_delimiters``, as
-above — a delimiter pair present in *both* buckets routes to
-``nickname``.
+A pair routes to exactly one field, and ``maiden_delimiters`` states
+the specific intent — so listing a pair there automatically drops it
+from the effective ``nickname_delimiters`` set, and the one-liner
+above is the whole recipe. To *add* delimiters instead of rerouting
+them, build on the named default:
+``nickname_delimiters=DEFAULT_NICKNAME_DELIMITERS | {("«", "»")}``.
 
 Presentation: rendering arguments
 ----------------------------------
diff --git a/docs/migrate.rst b/docs/migrate.rst
@@ -174,7 +174,10 @@ rendering argument, where the 2.0 equivalent isn't config at all):
        ``(open, close)`` pairs
    * - ``maiden_delimiters``
      - ``Policy.maiden_delimiters``
-     - Same shape change as ``nickname_delimiters``
+     - Same shape change as ``nickname_delimiters``. Precedence
+       differs: in the 2.0 API a pair listed here wins over
+       ``nickname_delimiters``; through the 1.x facade a pair in both
+       buckets keeps parsing as ``nickname`` (v1 behavior)
    * - ``regexes.bidi``
      - ``Policy.strip_bidi``
      - ``regexes.bidi = False`` becomes ``Policy(strip_bidi=False)``
diff --git a/docs/modules.rst b/docs/modules.rst
@@ -58,6 +58,8 @@ Configuration
 
 .. autodata:: nameparser.FAMILY_FIRST_GIVEN_LAST
 
+.. autodata:: nameparser.DEFAULT_NICKNAME_DELIMITERS
+
 Locales
 ~~~~~~~
 
diff --git a/docs/release_log.rst b/docs/release_log.rst
@@ -24,6 +24,7 @@ Release Log
     - Data change: ``ma``/``do`` added to ``suffix_acronyms_ambiguous`` -- ambiguous acronyms count as suffixes only when written with periods, so a bare common surname (``"Jack Ma"``, ``"Anh Do"``) keeps its family name under 2.0's keep-recognized-suffixes routing, matching 1.4's output (``tests/v2/cases.py`` row ``ambiguous_surname_acronyms``). Side effect: parenthesized/quoted ``"(MA)"``/``"(DO)"`` (no periods) no longer escape to ``suffix`` the way 1.x did -- they now fall through to nickname parsing like any other ambiguous-acronym delimited content. Not present in the differential corpus
     - Change suffix-delimiter rendering: with a custom ``Policy``/``Constants`` suffix delimiter configured (e.g. ``suffix_delimiter="/"``, ``"John Smith, RN/CRNA"``), 1.x split the token and rendered ``suffix="RN, CRNA"``; 2.0 keeps the no-space delimiter-core token whole (``suffix="RN/CRNA"``) -- role assignment is unchanged, only rendering differs (anti-#100, migration plan deviation 5; ``tests/v2/cases.py`` row ``suffix_delimiter_no_space_core``). Only fires with a non-default policy, so it does not appear in the (default-policy) differential corpus
     - Change ``comparison_key()``/``matches()`` (both APIs) to fold components with ``str.casefold()`` where 1.4 used ``str.lower()``: Unicode case-pair forms now compare equal -- ``"STRASSE"`` matches ``"Straße"``, and a Greek final-sigma variant matches its regular-sigma form. Strictly more permissive (anything 1.4 matched still matches); parse output is unaffected -- vocabulary normalization itself uses ``lower()``, v1-parity (``tests/v2/test_types.py`` row ``test_matches_casefolds_unicode_case_pairs``)
+    - Change delimiter-overlap precedence in the 2.0 API: a pair listed in ``Policy.maiden_delimiters`` is dropped from the effective ``nickname_delimiters`` set (maiden wins), so ``Policy(maiden_delimiters={("(", ")")})`` alone routes parenthesized content to ``maiden`` -- no need to rebuild the nickname set. The default nickname set is now the public ``DEFAULT_NICKNAME_DELIMITERS`` constant. The 1.x facade keeps v1's nickname-wins precedence on overlap via a shim-side pre-subtraction, so no ``HumanName`` behavior changes (``tests/v2/cases.py`` row ``maiden_delimiters_win_when_shared``; ``tests/v2/test_config_shim.py`` row ``test_snapshot_overlap_keeps_v1_nickname_precedence``)
 
     Everything else in the 486-name differential corpus (built from the
     v1 test banks as of commit ``2d5d8c2``, pre-dating the M12 test
diff --git a/nameparser/__init__.py b/nameparser/__init__.py
@@ -10,6 +10,7 @@
 from nameparser._locale import Locale
 from nameparser._parser import Parser, parse, parser_for
 from nameparser._policy import (
+    DEFAULT_NICKNAME_DELIMITERS,
     FAMILY_FIRST,
     FAMILY_FIRST_GIVEN_LAST,
     GIVEN_FIRST,
@@ -33,6 +34,7 @@
     # v2 core
     "Span", "Role", "Token", "Ambiguity", "AmbiguityKind", "ParsedName",
     "Lexicon", "Policy", "PolicyPatch", "PatronymicRule", "UNSET",
-    "GIVEN_FIRST", "FAMILY_FIRST", "FAMILY_FIRST_GIVEN_LAST", "Locale",
+    "GIVEN_FIRST", "FAMILY_FIRST", "FAMILY_FIRST_GIVEN_LAST",
+    "DEFAULT_NICKNAME_DELIMITERS", "Locale",
     "Parser", "parse", "parser_for",
 ]
diff --git a/nameparser/_config_shim.py b/nameparser/_config_shim.py
@@ -950,8 +950,12 @@ def _build_snapshot(self) -> tuple[Lexicon, Policy, _RenderDefaults]:
             middle_as_family=self.middle_name_as_last,
             nickname_delimiters=frozenset(
                 _SENTINEL_PAIRS[k] for k in self.nickname_delimiters),
+            # v1 precedence: a pair in BOTH v1 buckets parses as nickname.
+            # Policy itself resolves overlap the other way (maiden wins),
+            # so pre-subtract here to keep the facade at v1 behavior.
             maiden_delimiters=frozenset(
-                _SENTINEL_PAIRS[k] for k in self.maiden_delimiters),
+                _SENTINEL_PAIRS[k] for k in self.maiden_delimiters
+                if k not in self.nickname_delimiters),
             # suffix_delimiter is a _RenderDefaults-only field here; the
             # facade layers it onto extra_suffix_delimiters per instance
             # (a later task) -- _snapshot() itself stays pure translation
diff --git a/nameparser/_policy.py b/nameparser/_policy.py
@@ -27,6 +27,13 @@ class PatronymicRule(StrEnum):
 
 _NAME_ROLES = frozenset({Role.GIVEN, Role.MIDDLE, Role.FAMILY})
 
+#: Policy.nickname_delimiters' default (v1 parity: quotes + parentheses).
+#: Public and named so customizations read as set math against a
+#: documented value -- e.g. ``DEFAULT_NICKNAME_DELIMITERS | {("«", "»")}``
+#: -- instead of a rebuilt literal the user had to go discover.
+DEFAULT_NICKNAME_DELIMITERS = frozenset(
+    {("'", "'"), ('"', '"'), ("(", ")")})
+
 
 def _reject_bare_string_order(value: object) -> None:
     # tuple("gmf") would be ("g", "m", "f") -- catch the bare string
@@ -45,11 +52,11 @@ class Policy:
     patronymic_rules: frozenset[PatronymicRule] = frozenset()
     middle_as_family: bool = False  # v1's middle_name_as_last
     # v1 default delimiter set (#273)
-    nickname_delimiters: frozenset[tuple[str, str]] = frozenset(
-        {("'", "'"), ('"', '"'), ("(", ")")}
-    )
-    # empty by default (v1 parity); route ("(", ")") here to send
-    # parenthesized content to maiden instead of nickname (#274)
+    nickname_delimiters: frozenset[tuple[str, str]] = DEFAULT_NICKNAME_DELIMITERS
+    # empty by default (v1 parity); a pair listed here routes to maiden
+    # AND is dropped from the effective nickname set (maiden wins, see
+    # __post_init__), so maiden_delimiters={("(", ")")} is the whole
+    # parenthesized-maiden recipe (#274)
     maiden_delimiters: frozenset[tuple[str, str]] = frozenset()
     extra_suffix_delimiters: frozenset[str] = frozenset()
     lenient_comma_suffixes: bool = True
@@ -129,6 +136,16 @@ def __post_init__(self) -> None:
                         f"strings, got {pair!r}"
                     )
             object.__setattr__(self, pairs_name, frozenset(pairs))
+        # Maiden wins: a pair can route to exactly one field, and listing
+        # it in maiden_delimiters is the specific intent, so the effective
+        # nickname set drops it. Canonicalization, not validation (the
+        # name_order coercion precedent): differently-written but
+        # equivalent Policies converge to equal values. The v1 facade
+        # keeps v1's nickname-wins precedence via a pre-subtraction in
+        # _config_shim's snapshot instead.
+        object.__setattr__(
+            self, "nickname_delimiters",
+            self.nickname_delimiters - self.maiden_delimiters)
         if isinstance(self.extra_suffix_delimiters, str):
             raise TypeError(
                 f"extra_suffix_delimiters must be an iterable of strings, "
diff --git a/tests/v2/cases.py b/tests/v2/cases.py
@@ -117,13 +117,15 @@ def __post_init__(self) -> None:
          notes="v1 renders each tail comma segment as ONE suffix "
                "entry; words within an entry space-join via the "
                "'joined' tag"),
-    Case("nickname_bucket_wins_when_shared",
+    Case("maiden_delimiters_win_when_shared",
          'Baker (Johnson), Jenny',
-         {"given": "Jenny", "family": "Baker", "nickname": "Johnson"},
+         {"given": "Jenny", "family": "Baker", "maiden": "Johnson"},
          policy=Policy(maiden_delimiters=frozenset({("(", ")")})),
-         notes="when the same delimiter pair sits in both buckets the "
-               "nickname reading wins (v1 parse_nicknames order); the "
-               "bucket-move idiom removes it from nickname first"),
+         notes="listing a pair in maiden_delimiters drops it from the "
+               "effective nickname set (maiden wins, 2026-07-19) -- the "
+               "one-liner replaces the bucket-move idiom; the v1 facade "
+               "keeps v1's nickname-wins precedence via the shim's "
+               "pre-subtraction (pinned in test_config_shim)"),
     Case("family_segment_trailing_suffix", "Smith Jr., John",
          {"given": "John", "family": "Smith", "suffix": "Jr."},
          notes="v1: the family part may have suffixes in it "
diff --git a/tests/v2/test_config_shim.py b/tests/v2/test_config_shim.py
@@ -361,6 +361,23 @@ def test_snapshot_delimiter_bucket_move() -> None:
     assert ("(", ")") not in policy.nickname_delimiters
 
 
+def test_snapshot_overlap_keeps_v1_nickname_precedence() -> None:
+    # v1 semantics: a pair present in BOTH v1 buckets parses as nickname.
+    # 2.0's Policy resolves overlap the other way (maiden wins), so the
+    # snapshot pre-subtracts on the maiden side -- a v1 user who added
+    # parens to maiden_delimiters WITHOUT removing them from
+    # nickname_delimiters keeps their 1.x parse through the facade.
+    c = Constants()
+    c.maiden_delimiters["parenthesis"] = ("(", ")")  # nickname still has it
+    _, policy, _ = c._snapshot()
+    assert ("(", ")") in policy.nickname_delimiters
+    assert ("(", ")") not in policy.maiden_delimiters
+    from nameparser import HumanName
+
+    n = HumanName("Jane (Jones) Smith", constants=c)
+    assert n.nickname == "Jones" and n.maiden == ""
+
+
 def test_snapshot_ambiguous_removed_acronym_intersects() -> None:
     c = Constants()
     c.suffix_acronyms.remove("jd")          # 'jd' stays in ambiguous
diff --git a/tests/v2/test_layering.py b/tests/v2/test_layering.py
@@ -166,7 +166,8 @@ def test_public_exports() -> None:
     expected = {
         "Span", "Role", "Token", "Ambiguity", "AmbiguityKind", "ParsedName",
         "Lexicon", "Policy", "PolicyPatch", "PatronymicRule", "UNSET",
-        "GIVEN_FIRST", "FAMILY_FIRST", "FAMILY_FIRST_GIVEN_LAST", "Locale",
+        "GIVEN_FIRST", "FAMILY_FIRST", "FAMILY_FIRST_GIVEN_LAST",
+        "DEFAULT_NICKNAME_DELIMITERS", "Locale",
         "Parser", "parse", "parser_for",
     }
     assert expected <= set(nameparser.__all__)
diff --git a/tests/v2/test_policy.py b/tests/v2/test_policy.py
@@ -90,6 +90,42 @@ def test_patronymic_rules_true_points_at_the_v1_migration() -> None:
         PolicyPatch(extra_suffix_delimiters=True)  # type: ignore[arg-type]
 
 
+def test_maiden_delimiters_win_over_nickname_defaults() -> None:
+    # A pair routes to exactly one field, and listing it in
+    # maiden_delimiters is the specific intent -- so the one-liner works
+    # without knowing (or rebuilding) the nickname default set. The
+    # review that prompted this: routing parens to maiden used to
+    # require both buckets edited in tandem.
+    p = Policy(maiden_delimiters=frozenset({("(", ")")}))
+    assert ("(", ")") in p.maiden_delimiters
+    assert ("(", ")") not in p.nickname_delimiters
+    # canonicalization: the explicit-removal spelling converges to the
+    # same value (equal AND same hash -- cache keys agree)
+    explicit = Policy(
+        nickname_delimiters=frozenset({("'", "'"), ('"', '"')}),
+        maiden_delimiters=frozenset({("(", ")")}),
+    )
+    assert p == explicit and hash(p) == hash(explicit)
+
+
+def test_maiden_precedence_applies_through_policy_patch() -> None:
+    # apply_patch re-runs Policy's constructor, so a patch (e.g. from a
+    # locale pack) adding a maiden pair gets the same subtraction
+    patched = apply_patch(
+        Policy(), PolicyPatch(maiden_delimiters=frozenset({("(", ")")})))
+    assert ("(", ")") in patched.maiden_delimiters
+    assert ("(", ")") not in patched.nickname_delimiters
+
+
+def test_default_nickname_delimiters_constant_is_the_default() -> None:
+    from nameparser import DEFAULT_NICKNAME_DELIMITERS
+
+    assert Policy().nickname_delimiters == DEFAULT_NICKNAME_DELIMITERS
+    # the documented set-math idiom stays valid input
+    p = Policy(nickname_delimiters=DEFAULT_NICKNAME_DELIMITERS | {("«", "»")})
+    assert ("«", "»") in p.nickname_delimiters
+
+
 def test_policy_delimiters_coerce_to_frozensets() -> None:
     p = Policy(nickname_delimiters=[("(", ")")])  # type: ignore[arg-type]
     assert isinstance(p.nickname_delimiters, frozenset)
