test: add regex boundary and nickname-interaction coverage; clarify docs (#109)

Add tests for the leading-period-abbreviation feature's remaining
untested boundaries per PR #196 review: digit/apostrophe exclusion,
case-insensitivity, and interaction with parenthetical nicknames.
Also tighten doc wording that implied only the literal first token in
a name could become a title, when the rule applies to the whole
leading title run (chained abbreviations included).

Author: derek73

docs/release_log.rst

@@ -30,7 +30,7 @@ Release Log
       ``CONSTANTS.first_name_prefixes.clear()``. **Default-on: changes parsing
       output for names with these prefixes.** (#150)
     - Add ``middle_name_as_last`` flag to ``Constants`` and ``HumanName`` for opt-in folding of middle names into the last name, for naming systems with no middle-name concept (e.g. Arabic patronymic chaining) (#133)
-    - Treat an unrecognized, multi-letter token ending in a period at the start of a name (e.g. ``"Major."``) as a ``title`` instead of a ``first`` name; internal-period abbreviations (``"E.T."``) and single-letter initials (``"J."``) are unaffected. **Default-on: changes parsing of names with a leading unknown period-abbreviation** (closes #109)
+    - Treat an unrecognized, multi-letter token ending in a period in the leading title run (before the first name is set), e.g. ``"Major."``, as a ``title`` instead of a ``first`` name; internal-period abbreviations (``"E.T."``) and single-letter initials (``"J."``) are unaffected. **Default-on: changes parsing of names with a leading unknown period-abbreviation** (closes #109)
 * 1.2.1 - June 19, 2026
     - Fix ``initials()`` interpolating the literal ``None`` for empty name parts when ``empty_attribute_default = None`` (e.g. ``"J. None D."``); empty parts now render as an empty string and a fully-empty result returns ``empty_attribute_default``
     - Add ``python -m nameparser "Name String"`` command-line helper that prints a parsed name

docs/usage.rst

@@ -191,12 +191,13 @@ reading in that ambiguous context:
 Leading Period-Abbreviation Titles
 -----------------------------------
 
-An unrecognized, multi-letter word ending in a period, appearing before the
-first name, is treated as a title -- this covers military ranks and other
-abbreviations that aren't in the built-in titles list. Single-letter
-initials (``"J."``) and internal-period abbreviations (``"E.T."``) are not
-affected, and the same word appearing after the first name is left as a
-middle name.
+An unrecognized, multi-letter word ending in a period, found anywhere in the
+leading title run (i.e. before the first name is set), is treated as a title
+-- this covers military ranks and other abbreviations that aren't in the
+built-in titles list, including chained abbreviations like
+``"Foo. Xyz. John Smith"``. Single-letter initials (``"J."``) and
+internal-period abbreviations (``"E.T."``) are not affected, and the same
+word appearing after the first name is left as a middle name.
 
 .. doctest:: leading_period_titles
     :options: +NORMALIZE_WHITESPACE

nameparser/parser.py

@@ -543,11 +543,14 @@ def is_title(self, value: str) -> bool:
     def is_leading_title(self, piece: str) -> bool:
         """
         True if ``piece`` is a known title, or an unrecognized multi-letter
-        word ending in a single trailing period (e.g. ``"Major."``). Only
-        meaningful for pieces in the title position (before the first name is
-        set) — a period-abbreviation appearing later in the name is left as a
-        middle name. Does not mutate ``C.titles``, so the periodless form
-        (``"Major"``) is never affected in later parses.
+        word ending in a single trailing period (e.g. ``"Major."``). The
+        ``{2,}`` in the ``period_abbreviation`` regex, not a separate
+        ``is_an_initial()`` check, is what excludes single-letter initials
+        like ``"J."``. Only meaningful for pieces in the title position
+        (before the first name is set) — a period-abbreviation appearing
+        later in the name is left as a middle name. Does not mutate
+        ``C.titles``, so the periodless form (``"Major"``) is never affected
+        in later parses.
         """
         return self.is_title(piece) or bool(self.C.regexes.period_abbreviation.match(piece))
 

tests/test_titles.py

@@ -334,3 +334,27 @@ def test_middle_initial_with_period_unaffected(self) -> None:
         self.m(hn.first, "John", hn)
         self.m(hn.middle, "Q.", hn)
         self.m(hn.last, "Smith", hn)
+
+    def test_leading_period_abbreviation_excludes_digits(self) -> None:
+        hn = HumanName("No1. John Smith")
+        self.m(hn.title, "", hn)
+        self.m(hn.first, "No1.", hn)
+        self.m(hn.last, "Smith", hn)
+
+    def test_leading_period_abbreviation_excludes_apostrophe(self) -> None:
+        hn = HumanName("O'B. John Smith")
+        self.m(hn.title, "", hn)
+        self.m(hn.first, "O'B.", hn)
+        self.m(hn.last, "Smith", hn)
+
+    def test_leading_period_abbreviation_case_insensitive(self) -> None:
+        hn = HumanName("xyz. John Smith")
+        self.m(hn.title, "xyz.", hn)
+        self.m(hn.first, "John", hn)
+        self.m(hn.last, "Smith", hn)
+
+    def test_leading_period_abbreviation_with_nickname(self) -> None:
+        hn = HumanName("Xyz. (Bud) Smith")
+        self.m(hn.title, "Xyz.", hn)
+        self.m(hn.first, "Smith", hn)
+        self.m(hn.nickname, "Bud", hn)