feat: add suffix_delimiter for parsing suffixes separated by arbitrary delimiters (#156) (#172)

* docs: add design spec for suffix_delimiter feature (issue #156)
* docs: add implementation plan for suffix_delimiter feature
* feat: add suffix_delimiter to Constants (default None)

Add the suffix_delimiter class attribute to the Constants class with a default
value of None. This attribute will be used by HumanName to split suffix groups
after comma-splitting. The attribute follows the existing pattern of scalar
class attributes (string_format, initials_delimiter, initials_separator).

* feat: wire suffix_delimiter kwarg into HumanName.__init__
* feat: expand parts on suffix_delimiter after comma split in parse()

When parsing names with suffixes separated by a custom delimiter (e.g.
"Steven Hardman, RN - CRNA" with suffix_delimiter=" - "), the parser
now re-splits post-comma parts on the suffix_delimiter and flattens them
before processing. This transforms ["Steven Hardman", "RN - CRNA"] into
["Steven Hardman", "RN", "CRNA"], making downstream suffix detection work
correctly instead of treating the delimiter as an invalid suffix.

* test: add CONSTANTS-level and known-limitation tests for suffix_delimiter
* docs: note inverted-format limitation in suffix_delimiter docstring; clarify known-limitation test
* chore: remove planning docs for suffix_delimiter feature
* docs: add suffix_delimiter to customize.rst and release_log.rst
* fix: address PR review feedback on suffix_delimiter

- Filter empty tokens from trailing/leading delimiters to prevent
  silent parse corruption (e.g. "MD-PhD-" with suffix_delimiter="-")
- Clarify no-op note in Constants docstring: both the comma split and
  subsequent strip() make ", " a no-op, not just the comma split
- Correct param docstring: expansion applies to all post-comma parts,
  not just identified suffix groups
- Tighten known-limitation test with concrete field assertions instead
  of a fragile assertNotEqual
- Add tests: trailing delimiter, comma-space no-op, inverted-format
  limitation

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: derek73

docs/customize.rst

@@ -59,6 +59,7 @@ Other editable attributes
 * :py:obj:`~nameparser.config.Constants.empty_attribute_default` - value returned by empty attributes, defaults to empty string
 * :py:obj:`~nameparser.config.Constants.capitalize_name` - If set, applies :py:meth:`~nameparser.parser.HumanName.capitalize` to :py:class:`~nameparser.parser.HumanName` instance.
 * :py:obj:`~nameparser.config.Constants.force_mixed_case_capitalization` - If set, forces the capitalization of mixed case strings when :py:meth:`~nameparser.parser.HumanName.capitalize` is called.
+* :py:obj:`~nameparser.config.Constants.suffix_delimiter` - additional delimiter used to split suffix groups after comma-splitting, e.g. ``" - "`` for names like ``"Jane Smith, RN - CRNA"``. Defaults to ``None`` (disabled).
 
 
 

docs/release_log.rst

@@ -1,5 +1,7 @@
 Release Log
 ===========
+* 1.2.2 - June 28, 2026
+    - Add ``suffix_delimiter`` to ``Constants`` and ``HumanName`` for parsing suffixes separated by arbitrary delimiters, e.g. ``"RN - CRNA"`` (#156)
 * 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

nameparser/config/__init__.py

@@ -228,6 +228,25 @@ class Constants:
     spacing from the template is still applied.
     """
 
+    suffix_delimiter = None
+    """
+    If set, an additional delimiter used to split suffix groups after
+    comma-splitting. For example, setting ``suffix_delimiter=" - "`` allows
+    ``"RN - CRNA"`` to be parsed as two separate suffixes. Default is
+    ``None`` (no additional splitting beyond the standard comma split).
+
+    Note: setting this to ``","`` or ``", "`` has no additional effect —
+    the full name is already split on bare commas first, and each resulting
+    part is stripped of surrounding whitespace before this step runs.
+
+    Known limitation: the expansion is applied to all post-comma parts, not
+    just suffix groups. In inverted format (``"Last, First, suffix"``), the
+    first-name part is also split on the delimiter. In practice this is
+    harmless since first names rarely contain the delimiter string, but a
+    name like ``"Doe, Mary - Kate, RN"`` with ``suffix_delimiter=" - "``
+    would misparse.
+    """
+
     empty_attribute_default = ''
     """
     Default return value for empty attributes.

nameparser/parser.py

@@ -53,6 +53,9 @@ class HumanName:
     :param str string_format: python string formatting
     :param str initials_format: python initials string formatting
     :param str initials_delimter: string delimiter for initials
+    :param str initials_separator: string separator between consecutive initials
+    :param str suffix_delimiter: additional delimiter to split post-comma parts
+        before suffix detection, e.g. ``" - "`` for ``"RN - CRNA"``
     :param str first: first name
     :param str middle: middle name
     :param str last: last name
@@ -95,6 +98,7 @@ def __init__(
         initials_format: str | None = None,
         initials_delimiter: str | None = None,
         initials_separator: str | None = None,
+        suffix_delimiter: str | None = None,
         first: str | list[str] | None = None,
         middle: str | list[str] | None = None,
         last: str | list[str] | None = None,
@@ -111,6 +115,7 @@ def __init__(
         self.initials_format    = initials_format    if initials_format    is not None else self.C.initials_format
         self.initials_delimiter = initials_delimiter if initials_delimiter is not None else self.C.initials_delimiter
         self.initials_separator = initials_separator if initials_separator is not None else self.C.initials_separator
+        self.suffix_delimiter   = suffix_delimiter   if suffix_delimiter   is not None else self.C.suffix_delimiter
         if (first or middle or last or title or suffix or nickname):
             self.first = first
             self.middle = middle
@@ -623,6 +628,12 @@ def parse_full_name(self) -> None:
         # break up full_name by commas
         parts = [x.strip() for x in self._full_name.split(",")]
 
+        if self.suffix_delimiter and len(parts) > 1:
+            expanded = [parts[0]]
+            for part in parts[1:]:
+                expanded.extend([p for p in (p.strip() for p in part.split(self.suffix_delimiter)) if p])
+            parts = expanded
+
         log.debug("full_name: %s", self._full_name)
         log.debug("parts: %s", parts)
 

tests/test_suffixes.py

@@ -136,3 +136,70 @@ def test_suffix_with_periods_with_lastname_comma(self) -> None:
         self.m(hn.first, "John", hn)
         self.m(hn.last, "Doe", hn)
         self.m(hn.suffix, "Msc.Ed.", hn)
+
+    def test_suffix_delimiter_default_on_constants(self) -> None:
+        from nameparser.config import CONSTANTS
+        self.assertIs(CONSTANTS.suffix_delimiter, None)
+
+    def test_suffix_delimiter_kwarg_accepted(self) -> None:
+        hn = HumanName("Steven Hardman, RN - CRNA", suffix_delimiter=" - ")
+        self.assertEqual(hn.suffix_delimiter, " - ")
+
+    def test_suffix_delimiter_basic(self) -> None:
+        hn = HumanName("Steven Hardman, RN - CRNA", suffix_delimiter=" - ")
+        self.m(hn.first, "Steven", hn)
+        self.m(hn.last, "Hardman", hn)
+        self.m(hn.suffix, "RN, CRNA", hn)
+
+    def test_suffix_delimiter_multiple(self) -> None:
+        hn = HumanName("John Doe, MD - PhD - FACS", suffix_delimiter=" - ")
+        self.m(hn.first, "John", hn)
+        self.m(hn.last, "Doe", hn)
+        self.m(hn.suffix, "MD, PhD, FACS", hn)
+
+    def test_suffix_delimiter_no_effect_without_comma(self) -> None:
+        # suffix_delimiter only applies after the comma split; space-separated
+        # suffixes already work via the no-comma parse path
+        hn = HumanName("John Doe MD PhD", suffix_delimiter=" - ")
+        self.m(hn.first, "John", hn)
+        self.m(hn.last, "Doe", hn)
+        self.m(hn.suffix, "MD, PhD", hn)
+
+    def test_suffix_delimiter_constants_level(self) -> None:
+        from nameparser.config import CONSTANTS
+        _orig = CONSTANTS.suffix_delimiter
+        try:
+            CONSTANTS.suffix_delimiter = " - "
+            hn = HumanName("Steven Hardman, RN - CRNA")
+            self.m(hn.first, "Steven", hn)
+            self.m(hn.last, "Hardman", hn)
+            self.m(hn.suffix, "RN, CRNA", hn)
+        finally:
+            CONSTANTS.suffix_delimiter = _orig
+
+    def test_suffix_delimiter_none_by_default_known_limitation(self) -> None:
+        # Without suffix_delimiter set, " - " between suffixes breaks parsing.
+        # This test documents the known limitation — do not "fix" it.
+        hn = HumanName("Steven Hardman, RN - CRNA")
+        self.m(hn.first, "RN", hn)
+        self.m(hn.last, "Steven Hardman", hn)
+        self.m(hn.suffix, "CRNA", hn)
+
+    def test_suffix_delimiter_trailing_delimiter_ignored(self) -> None:
+        # Trailing delimiter produces an empty token that must be filtered out.
+        # Using a non-whitespace-terminated delimiter so stripping doesn't consume it.
+        hn = HumanName("John Doe, MD-PhD-", suffix_delimiter="-")
+        self.m(hn.first, "John", hn)
+        self.m(hn.last, "Doe", hn)
+        self.m(hn.suffix, "MD, PhD", hn)
+
+    def test_suffix_delimiter_comma_space_is_noop(self) -> None:
+        hn = HumanName("John Doe, MD, PhD", suffix_delimiter=", ")
+        self.m(hn.suffix, "MD, PhD", hn)
+
+    def test_suffix_delimiter_inverted_format_known_limitation(self) -> None:
+        # In inverted format, the first-name part is also split on the delimiter.
+        # "Mary - Kate" becomes two separate parts, causing a wrong parse.
+        # This is a documented limitation — do not "fix" it without a broader solution.
+        hn = HumanName("Doe, Mary - Kate, RN", suffix_delimiter=" - ")
+        self.assertNotEqual(hn.first, "Mary - Kate")