fix: restore suffix_acronyms_ambiguous wiring lost in a git race

nameparser/config/__init__.py's suffix_acronyms_ambiguous attribute
(import, docstring, type hint, constructor param, and __init__
assignment -- all from Task 1, commit 135395b) was accidentally
reverted by commit c2efbd8. Root cause: a review subagent was
running concurrently in this same shared worktree directory and
appears to have checked out an older commit in place (rather than in
an isolated copy) to compare pre/post-PR behavior for its "verified
against unmodified master" claims; that checkout's staged state got
swept into c2efbd8's commit alongside my own staged changes, since
`git commit` includes everything staged, not just newly `git add`ed
paths.

The working tree itself was never wrong -- parser.py's handle_match()
has referenced self.C.suffix_acronyms_ambiguous correctly this whole
time, and pytest passed after every commit since the corruption,
because pytest reads the filesystem, not git history. Only the
*committed* nameparser/config/__init__.py (and, transiently, the
already-pushed PR branch) lacked the attribute -- a fresh clone of
c2efbd8..4e91b7a would have raised AttributeError on any name
containing parens/quotes. Verified via `git show HEAD:...` and
`git diff 135395b HEAD -- nameparser/config/__init__.py` that this
commit is the only remaining gap; suffixes.py, parser.py, and the
tests were independently re-added correctly in later commits.

Also includes docs/usage.rst and docs/customize.rst updates
documenting the new suffix_acronyms_ambiguous behavior and
SUFFIX_ACRONYMS_AMBIGUOUS constant.

Author: derek73

docs/customize.rst

@@ -43,6 +43,7 @@ Editable attributes of nameparser.config.CONSTANTS
 * :py:data:`~nameparser.config.FIRST_NAME_TITLES` - Titles that, when followed by a single name, that name is a first name, e.g. "King David".
 * :py:data:`~nameparser.config.SUFFIX_ACRONYMS` - Pieces that come at the end of the name that may or may not have periods separating the letters, e.g. "m.d.".
 * :py:data:`~nameparser.config.SUFFIX_NOT_ACRONYMS` - Pieces that come at the end of the name that never have periods separating the letters, e.g. "Jr.".
+* :py:data:`~nameparser.config.SUFFIX_ACRONYMS_AMBIGUOUS` - Acronym suffixes from ``SUFFIX_ACRONYMS`` that also plausibly work as a given-name nickname on their own, e.g. "JD", "Ed". When one of these appears alone in parenthesis or quotes (e.g. ``'JEFFREY (JD) BRICKEN'``), it's kept as a nickname rather than reclassified as a suffix, since that's the more common reading in ambiguous, delimiter-only context (see the "Nickname Handling" section in the usage guide).
 * :py:data:`~nameparser.config.conjunctions.CONJUNCTIONS` - Connectors like "and" that join the preceding piece to the following piece.
 * :py:data:`~nameparser.config.prefixes.PREFIXES` - Connectors like "del" and "bin" that join to the following piece but not the preceding, similar to titles but can appear anywhere in the name.
 * :py:data:`~nameparser.config.CAPITALIZATION_EXCEPTIONS` - Dictionary of pieces that do not capitalize the first letter, e.g. "Ph.D".

docs/usage.rst

@@ -147,6 +147,47 @@ available from the nickname attribute.
       nickname: 'John'
     ]>
 
+Exception: content that looks like a suffix (a member of
+:py:data:`~nameparser.config.SUFFIX_ACRONYMS` or
+:py:data:`~nameparser.config.SUFFIX_NOT_ACRONYMS`, or anything ending in a
+period) is treated as a suffix instead of a nickname, since that's usually
+what's meant, e.g. a retired military title or a professional designation
+written in parenthesis.
+
+.. doctest:: nicknames
+    :options: +NORMALIZE_WHITESPACE
+
+    >>> name = HumanName('Andrew Perkins (MBA)')
+    >>> name
+    <HumanName : [
+      title: ''
+      first: 'Andrew'
+      middle: ''
+      last: 'Perkins'
+      suffix: 'MBA'
+      nickname: ''
+    ]>
+
+A few suffix acronyms, listed in
+:py:data:`~nameparser.config.SUFFIX_ACRONYMS_AMBIGUOUS`, also work as common
+given-name nicknames on their own (e.g. "JD", "Ed"). These stay nicknames
+when found alone in parenthesis or quotes, since that's the more common
+reading in that ambiguous context:
+
+.. doctest:: nicknames
+    :options: +NORMALIZE_WHITESPACE
+
+    >>> name = HumanName('JEFFREY (JD) BRICKEN')
+    >>> name
+    <HumanName : [
+      title: ''
+      first: 'JEFFREY'
+      middle: ''
+      last: 'BRICKEN'
+      suffix: ''
+      nickname: 'JD'
+    ]>
+
 Change the output string with string formatting
 -----------------------------------------------
 

nameparser/config/__init__.py

@@ -42,6 +42,7 @@
 from nameparser.config.conjunctions import CONJUNCTIONS
 from nameparser.config.suffixes import SUFFIX_ACRONYMS
 from nameparser.config.suffixes import SUFFIX_NOT_ACRONYMS
+from nameparser.config.suffixes import SUFFIX_ACRONYMS_AMBIGUOUS
 from nameparser.config.titles import TITLES
 from nameparser.config.titles import FIRST_NAME_TITLES
 from nameparser.config.regexes import EMPTY_REGEX, REGEXES
@@ -236,8 +237,10 @@ class Constants:
         :py:attr:`~titles.FIRST_NAME_TITLES` wrapped with :py:class:`SetManager`.
     :param set suffix_acronyms: 
         :py:attr:`~suffixes.SUFFIX_ACRONYMS`  wrapped with :py:class:`SetManager`.
-    :param set suffix_not_acronyms: 
+    :param set suffix_not_acronyms:
         :py:attr:`~suffixes.SUFFIX_NOT_ACRONYMS`  wrapped with :py:class:`SetManager`.
+    :param set suffix_acronyms_ambiguous:
+        :py:attr:`~suffixes.SUFFIX_ACRONYMS_AMBIGUOUS` wrapped with :py:class:`SetManager`.
     :param set conjunctions:
         :py:attr:`conjunctions`  wrapped with :py:class:`SetManager`.
     :param set first_name_prefixes:
@@ -257,6 +260,7 @@ class Constants:
     first_name_titles: SetManager
     conjunctions: SetManager
     first_name_prefixes: SetManager
+    suffix_acronyms_ambiguous: SetManager
     capitalization_exceptions: TupleManager[str]
     regexes: RegexTupleManager
     _pst: Set[str] | None
@@ -388,6 +392,7 @@ def __init__(self,
                  prefixes: Iterable[str] = PREFIXES,
                  suffix_acronyms: Iterable[str] = SUFFIX_ACRONYMS,
                  suffix_not_acronyms: Iterable[str] = SUFFIX_NOT_ACRONYMS,
+                 suffix_acronyms_ambiguous: Iterable[str] = SUFFIX_ACRONYMS_AMBIGUOUS,
                  titles: Iterable[str] = TITLES,
                  first_name_titles: Iterable[str] = FIRST_NAME_TITLES,
                  conjunctions: Iterable[str] = CONJUNCTIONS,
@@ -406,6 +411,7 @@ def __init__(self,
         self.first_name_titles = SetManager(first_name_titles)
         self.conjunctions = SetManager(conjunctions)
         self.first_name_prefixes = SetManager(first_name_prefixes)
+        self.suffix_acronyms_ambiguous = SetManager(suffix_acronyms_ambiguous)
         self.capitalization_exceptions = TupleManager(capitalization_exceptions)
         self.regexes = RegexTupleManager(regexes)
         self.patronymic_name_order = patronymic_name_order