Fix regression: keep built-in nickname delimiters live, isolate extras

Multi-agent review of PR #190 caught a critical regression: snapshotting
quoted_word/double_quotes/parenthesis into nickname_delimiters at
Constants.__init__ time silently broke the pre-existing, documented
customization path of overriding CONSTANTS.regexes.parenthesis (etc.)
and re-parsing, since the snapshot never saw later changes to regexes.

parse_nicknames() now reads the three built-ins live from self.C.regexes
(restoring that override path) and additionally iterates a renamed,
initially-empty extra_nickname_delimiters collection for new patterns,
matching what issue #112 actually asked for (add, not replace).

Also: added extra_nickname_delimiters to conftest.py's autouse
snapshot/restore list (it was missing, so mutating the global CONSTANTS
copy in a test would have leaked into later tests), added regression/
removal/pickle-roundtrip/suffix-interaction tests, and fixed the stale
parse_nicknames() docstring.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: derek73

docs/customize.rst

@@ -56,13 +56,15 @@ remove punctuation to normalize them for comparison.
 Adding Custom Nickname Delimiters
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-:py:obj:`~nameparser.config.Constants.nickname_delimiters` is a named,
-appendable group of the delimiter patterns that
-:py:meth:`~nameparser.parser.HumanName.parse_nicknames` loops through
-(``quoted_word``, ``double_quotes`` and ``parenthesis`` by default). Add
-your own pattern under a new key to recognize additional delimiters, then
-re-run :py:meth:`~nameparser.parser.HumanName.parse_full_name` to pick it
-up:
+:py:meth:`~nameparser.parser.HumanName.parse_nicknames` recognizes three
+built-in delimiters -- ``quoted_word``, ``double_quotes`` and
+``parenthesis`` -- read from :py:attr:`~nameparser.config.Constants.regexes`,
+so overriding e.g. ``CONSTANTS.regexes.parenthesis`` still works exactly as
+before. To recognize an *additional* delimiter without overriding one of the
+built-ins, add a pattern to
+:py:obj:`~nameparser.config.Constants.extra_nickname_delimiters` (empty by
+default) under any key, then re-run
+:py:meth:`~nameparser.parser.HumanName.parse_full_name` to pick it up:
 
 .. doctest::
 
@@ -71,7 +73,7 @@ up:
     >>> hn = HumanName("Benjamin {Ben} Franklin", constants=None)
     >>> hn.nickname
     ''
-    >>> hn.C.nickname_delimiters['curly_braces'] = re.compile(r'\{(.*?)\}', re.U)
+    >>> hn.C.extra_nickname_delimiters['curly_braces'] = re.compile(r'\{(.*?)\}', re.U)
     >>> hn.parse_full_name()
     >>> hn.nickname
     'Ben'

nameparser/config/__init__.py

@@ -263,7 +263,7 @@ class Constants:
     suffix_acronyms_ambiguous: SetManager
     capitalization_exceptions: TupleManager[str]
     regexes: RegexTupleManager
-    nickname_delimiters: TupleManager[re.Pattern[str]]
+    extra_nickname_delimiters: TupleManager[re.Pattern[str]]
     _pst: Set[str] | None
 
     string_format = "{title} {first} {middle} {last} {suffix} ({nickname})"
@@ -415,15 +415,13 @@ def __init__(self,
         self.suffix_acronyms_ambiguous = SetManager(suffix_acronyms_ambiguous)
         self.capitalization_exceptions = TupleManager(capitalization_exceptions)
         self.regexes = RegexTupleManager(regexes)
-        # Named, appendable group of delimiter patterns that parse_nicknames()
-        # iterates in order -- see nameparser.config.regexes for the defaults.
-        # Add a pattern here (and re-parse) to recognize a new delimiter
-        # without needing to override parse_nicknames() itself. See issue #112.
-        self.nickname_delimiters = TupleManager({
-            'quoted_word': self.regexes.quoted_word,
-            'double_quotes': self.regexes.double_quotes,
-            'parenthesis': self.regexes.parenthesis,
-        })
+        # Named, appendable group of *additional* delimiter patterns that
+        # parse_nicknames() iterates after its three built-in delimiters
+        # (quoted_word/double_quotes/parenthesis, read live from self.regexes
+        # so overriding those keeps working as before). Empty by default; add
+        # a pattern here (and re-parse) to recognize a new delimiter without
+        # needing to override parse_nicknames() itself. See issue #112.
+        self.extra_nickname_delimiters = TupleManager()
         self.patronymic_name_order = patronymic_name_order
 
     def _invalidate_pst(self) -> None:

nameparser/parser.py

@@ -784,8 +784,12 @@ def parse_nicknames(self) -> None:
         white space to allow for quotes in names like O'Connor and Kawai'ae'a.
         Double quotes and parenthesis can span white space.
 
-        Loops through 3 :py:data:`~nameparser.config.regexes.REGEXES`;
-        `quoted_word`, `double_quotes` and `parenthesis`.
+        Loops through the built-in `quoted_word`, `double_quotes` and
+        `parenthesis` patterns in :py:attr:`~nameparser.config.Constants.regexes`,
+        followed by any patterns added to
+        :py:attr:`~nameparser.config.Constants.extra_nickname_delimiters` --
+        see the "Adding Custom Nickname Delimiters" section of the
+        customization docs.
         """
 
         def handle_match(m: 're.Match[str]') -> str:
@@ -825,10 +829,18 @@ def handle_match(m: 're.Match[str]') -> str:
         # Same handle_match for every delimiter: suffix-shaped content
         # is rare in quotes but not impossible, and the logic is delimiter-
         # agnostic, so there's no reason to special-case parenthesis here.
-        # Iterating self.C.nickname_delimiters (rather than a hardcoded
-        # tuple) lets callers add new delimiter patterns at runtime -- see
-        # issue #112.
-        for _re in self.C.nickname_delimiters.values():
+        # The three built-ins are read live from self.C.regexes (not copied),
+        # so overriding e.g. self.C.regexes.parenthesis keeps working as
+        # before; extra_nickname_delimiters is iterated afterward so callers
+        # can add new delimiter patterns at runtime without needing to
+        # override parse_nicknames() itself -- see issue #112.
+        delimiters = (
+            self.C.regexes.quoted_word,
+            self.C.regexes.double_quotes,
+            self.C.regexes.parenthesis,
+            *self.C.extra_nickname_delimiters.values(),
+        )
+        for _re in delimiters:
             self._full_name = _re.sub(handle_match, self._full_name)
 
     def squash_emoji(self) -> None:

tests/conftest.py

@@ -35,6 +35,7 @@
     "first_name_prefixes",
     "capitalization_exceptions",
     "regexes",
+    "extra_nickname_delimiters",
 )
 
 

tests/test_constants.py

@@ -1,5 +1,6 @@
 import copy
 import pickle
+import re
 import timeit
 
 from nameparser import HumanName
@@ -60,6 +61,17 @@ def test_can_change_global_constants(self) -> None:
         # No manual cleanup needed: the autouse fixture in conftest.py snapshots
         # and restores the global CONSTANTS collections around every test.
 
+    def test_can_add_global_extra_nickname_delimiter(self) -> None:
+        # https://github.com/derek73/python-nameparser/issues/112
+        hn = HumanName("")
+        hn.C.extra_nickname_delimiters['curly_braces'] = re.compile(r'\{(.*?)\}', re.U)
+        hn2 = HumanName("Benjamin {Ben} Franklin")
+        self.assertEqual(hn2.has_own_config, False)
+        self.m(hn2.nickname, "Ben", hn2)
+        # No manual cleanup needed: the autouse fixture in conftest.py snapshots
+        # and restores the global CONSTANTS collections (including
+        # extra_nickname_delimiters) around every test.
+
     def test_remove_multiple_arguments(self) -> None:
         hn = HumanName("Ms Hon Solo", constants=None)
         hn.C.titles.remove('hon', 'ms')
@@ -129,6 +141,7 @@ def test_pickle_roundtrip_preserves_customizations(self) -> None:
         c.titles.add('customtitle')
         c.prefixes.add('customprefix')
         c.titles.remove('hon')
+        c.extra_nickname_delimiters['curly_braces'] = re.compile(r'\{(.*?)\}', re.U)
 
         # Safe: round-tripping a Constants the test just built, not untrusted data.
         restored = pickle.loads(pickle.dumps(c))
@@ -142,6 +155,8 @@ def test_pickle_roundtrip_preserves_customizations(self) -> None:
         # The collections must also keep their manager type, not just contents.
         self.assertEqual(type(restored.titles), SetManager)
         self.assertEqual(type(restored.prefixes), SetManager)
+        self.assertIn('curly_braces', restored.extra_nickname_delimiters)
+        self.assertEqual(type(restored.extra_nickname_delimiters), TupleManager)
 
     def test_pickle_roundtrip_preserves_instance_scalar_override(self) -> None:
         """An instance-level scalar override must survive a pickle round-trip."""

tests/test_nicknames.py

@@ -21,7 +21,28 @@ def test_add_custom_nickname_delimiter(self) -> None:
         hn = HumanName("Benjamin {Ben} Franklin", constants=None)
         # curly braces aren't a recognized delimiter by default
         self.m(hn.nickname, "", hn)
-        hn.C.nickname_delimiters['curly_braces'] = re.compile(r'\{(.*?)\}', re.U)
+        hn.C.extra_nickname_delimiters['curly_braces'] = re.compile(r'\{(.*?)\}', re.U)
+        hn.parse_full_name()
+        self.m(hn.first, "Benjamin", hn)
+        self.m(hn.last, "Franklin", hn)
+        self.m(hn.nickname, "Ben", hn)
+
+    def test_remove_custom_nickname_delimiter(self) -> None:
+        hn = HumanName("Benjamin {Ben} Franklin", constants=None)
+        hn.C.extra_nickname_delimiters['curly_braces'] = re.compile(r'\{(.*?)\}', re.U)
+        hn.parse_full_name()
+        self.m(hn.nickname, "Ben", hn)
+        del hn.C.extra_nickname_delimiters['curly_braces']
+        hn.parse_full_name()
+        self.m(hn.nickname, "", hn)
+
+    def test_overriding_builtin_regex_still_affects_nickname_parsing(self) -> None:
+        # The pre-existing customization path (overriding self.C.regexes
+        # directly, documented since before #112) must keep working now that
+        # parse_nicknames() also consults extra_nickname_delimiters.
+        hn = HumanName("Benjamin [Ben] Franklin", constants=None)
+        self.m(hn.nickname, "", hn)
+        hn.C.regexes['parenthesis'] = re.compile(r'\[(.*?)\]', re.U)
         hn.parse_full_name()
         self.m(hn.first, "Benjamin", hn)
         self.m(hn.last, "Franklin", hn)
@@ -155,6 +176,17 @@ def test_ambiguous_suffix_acronym_in_parenthesis_stays_nickname(self) -> None:
         self.m(hn.nickname, "JD", hn)
         self.m(hn.suffix, "", hn)
 
+    def test_ambiguous_suffix_acronym_in_extra_delimiter_stays_nickname(self) -> None:
+        # Same suffix-vs-nickname disambiguation as above, but through a
+        # custom delimiter added via extra_nickname_delimiters -- confirms
+        # handle_match() is applied uniformly regardless of which delimiter
+        # matched, not just the three built-ins.
+        hn = HumanName("JEFFREY {JD} BRICKEN", constants=None)
+        hn.C.extra_nickname_delimiters['curly_braces'] = re.compile(r'\{(.*?)\}', re.U)
+        hn.parse_full_name()
+        self.m(hn.nickname, "JD", hn)
+        self.m(hn.suffix, "", hn)
+
 
 # class MaidenNameTestCase(HumanNameTestBase):
 #