merge: integrate master into pr/166, resolve test_constants conflict

Author: derek73

AGENTS.md

@@ -2,28 +2,58 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+## Workflow
+
+For non-trivial changes, use a feature branch and open a PR.
+Branch naming: `fix/issue-NNN-short-description` or `feat/short-description`.
+
 ## Commands
 
 ```bash
-# Install dev dependencies (requires pip >= 24.1)
-pip install --group dev
+# Preferred: use uv run (works without activating the venv)
+# Alternative: .venv/bin/<tool> if the venv is already active
 
-# Run all tests
-pytest
+# Run all tests (includes --doctest-modules, so doctests in nameparser/ are also run;
+# the dual-parametrize fixture doubles the count, so ~370 methods → ~740 results)
+uv run pytest  # --doctest-modules is set in pyproject.toml, so doctests run automatically
 
 # Run a single test file / class / method
-pytest tests/test_python_api.py
-pytest tests/test_python_api.py::HumanNamePythonTests::test_utf8
+uv run pytest tests/test_python_api.py
+uv run pytest tests/test_python_api.py::HumanNamePythonTests::test_utf8
+
+# Type check
+uv run mypy nameparser/
+
+# Lint
+uv run ruff check nameparser/
 
 # Debug how a specific name string is parsed (prints HumanName repr)
-python -m nameparser "Dr. Juan Q. Xavier de la Vega III"
+uv run python -m nameparser "Dr. Juan Q. Xavier de la Vega III"
 
 # Build docs
-sphinx-build -b html docs dist/docs
-
-# Build package for release
-python setup.py sdist bdist_wheel
-twine upload dist/*
+uv run sphinx-build -b html docs dist/docs
+
+# Maintain docs/release_log.rst as changes land:
+# - Keep an "Unreleased" entry at the top: `* X.Y.Z - Unreleased`
+# - Add one bullet per notable change; prefix with Add/Fix/Remove/Change
+# - Reference the issue or PR in parentheses: (#123) or (#123, #124)
+#   Use "closes #N" when the change directly resolves the issue
+# - Version is decided at release time (patch/minor/major per semver)
+# - Format matches existing entries — see 1.3.0 block for a current example
+
+# Release checklist (PyPI publish is triggered automatically by GitHub Actions on release creation)
+# 0. Review docs/ for anything stale — especially usage.rst (examples, API surface)
+#    and any .rst files that reference config constants or HumanName kwargs
+#    Also review AGENTS.md for stale commands, architecture notes, or gotchas
+# 1. Bump VERSION in nameparser/_version.py
+# 2. Stamp "Unreleased" → "X.Y.Z - Month DD, YYYY" in docs/release_log.rst
+# 3. git commit + git tag -a vX.Y.Z -m "Release X.Y.Z"
+# 4. git push origin master && git push origin vX.Y.Z  ← tag must be pushed separately before gh release create
+# 5. gh release create vX.Y.Z --title "vX.Y.Z" --notes "..."
+# 6. Close the vX.Y.Z milestone and create a new "Next Release" one:
+#    MILESTONE=$(gh api repos/derek73/python-nameparser/milestones --jq '.[] | select(.title=="vX.Y.Z") | .number')
+#    gh api -X PATCH repos/derek73/python-nameparser/milestones/$MILESTONE -f state=closed
+#    gh api -X POST repos/derek73/python-nameparser/milestones -f title="Next Release"
 ```
 
 Enable debug logging to see the parser's internal decisions:
@@ -52,6 +82,8 @@ Each module defines a plain Python set of known name pieces:
 
 **Two-tier config pattern**: `CONSTANTS` is global; passing `None` as the second arg to `HumanName` creates a fresh per-instance `Constants()`. After modifying per-instance config you must call `hn.parse_full_name()` again. `SetManager.add()`/`remove()` normalizes inputs to lowercase with no periods, so callers don't need to worry about case.
 
+**`_CachedUnionMember` descriptor**: The four PST-contributing attrs (`prefixes`, `suffix_acronyms`, `suffix_not_acronyms`, `titles`) are managed by this descriptor, which stores their values under the *private* name (`_prefixes`, `_titles`, etc.) in the instance `__dict__` so that the descriptor's `__set__` owns every assignment and can wire the cache-invalidation callback. Any code that inspects `__dict__` directly (e.g. `__getstate__`) must map `_xxx` → `xxx` for descriptor-managed attrs rather than filtering on `not k.startswith('_')`.
+
 ### Parser (`nameparser/parser.py`)
 
 `HumanName` is the single public class. Assigning to `full_name` (or instantiating with a string) triggers `parse_full_name()`.
@@ -66,6 +98,28 @@ Parse flow:
 
 Each named attribute (`title`, `first`, etc.) is a `@property` that joins its corresponding `_list`. Setters call `_set_list()` which runs the value through `parse_pieces()`, so assigning `hn.last = "de la Vega"` correctly re-parses prefix tokens.
 
+## Extension Patterns
+
+**Adding a scalar `Constants` attribute + `HumanName` kwarg** (e.g. `initials_separator`, `suffix_delimiter`):
+1. Add class attr to `Constants` in `config/__init__.py` with docstring
+2. Add `x: str | None = None` to `HumanName.__init__` signature after related kwargs
+3. Add `self.x = x if x is not None else self.C.x` in body — use `is not None`, not `or`, to allow falsy values like `""`
+4. conftest auto-restores scalar CONSTANTS between tests, but tests that *set* CONSTANTS mid-run still need their own try/finally
+
+## Gotchas
+
+**`suffix_not_acronyms` vs `is_an_initial` tension** — single-letter roman numeral suffixes (`i`, `v`) are in `suffix_not_acronyms` but also match the `is_an_initial` regex (single uppercase letter), so `is_suffix()` rejects them. Two separate code paths need context-aware workarounds: (1) suffix-comma detection uses `are_suffixes_after_comma()` which bypasses `is_suffix()` for `suffix_not_acronyms` members; (2) lastname-comma post-comma parsing uses `is_suffix_at_lastname_comma_end()` which only fires when `nxt is None` and `len(parts)==2` (no `parts[2]` suffix segment). See issues #136, #144.
+
+**Expected-failure tests use `@pytest.mark.xfail`** — the conftest parametrized fixture breaks `@unittest.expectedFailure`; always use `@pytest.mark.xfail` instead.
+
+**`lc()` strips only trailing periods** — `'M.D.'` → `'m.d'`, not `'md'`. Exception keys in `capitalization_exceptions` are dot-free, so lookups must also try `.replace('.', '')`.
+
+**`docs/usage.rst` contains live doctests** — edits can break `uv run pytest` (run via `--doctest-modules`). Verify new examples with `python3 -c "..."` before committing.
+
+**`initials_separator` is intra-group only** — it controls the joiner between consecutive initials *within* a name group (e.g. two middle names in `middle_list`). Spaces *between* groups come from `initials_format`. To fully concatenate initials you need both `initials_separator=""` and `initials_format="{first}{middle}{last}"`.
+
+**`pr/NNN` local branches** track upstream PRs — don't commit to them by accident. Check `git branch --show-current` before starting work.
+
 ### Tests (`tests/`)
 
-Tests run under **pytest** and are split one file per concern (`tests/test_titles.py`, `tests/test_suffixes.py`, etc.). `tests/base.py` holds `HumanNameTestBase` — a plain (non-`unittest`) base whose `m()` helper is a custom assert that prints the original name string on failure (plus thin `assert*` shims so the moved test bodies are unchanged). `tests/conftest.py` defines an autouse fixture that runs **every test twice** — once with `empty_attribute_default = ''` and once with `None` — so reported counts are doubled (e.g. 11 methods → 22 results); it also snapshots/restores the scalar `CONSTANTS` config around each test to keep tests order-independent. `TEST_NAMES` (in `tests/test_variations.py`) is a list of name strings permuted into comma-separated variants as a regression check. Tests that should fail use `@pytest.mark.xfail`. When adding a parsing case, add it to the relevant `tests/test_*.py` file and consider adding the base form to `TEST_NAMES`.
+Tests run under **pytest** (via `uv run pytest`) and are split one file per concern (`tests/test_titles.py`, `tests/test_suffixes.py`, etc.). `tests/base.py` holds `HumanNameTestBase` — a plain (non-`unittest`) base whose `m()` helper is a custom assert that prints the original name string on failure (plus thin `assert*` shims so the moved test bodies are unchanged). `tests/conftest.py` defines an autouse fixture that runs **every test twice** — once with `empty_attribute_default = ''` and once with `None` — so reported counts are doubled (e.g. 11 methods → 22 results); it also snapshots/restores the scalar `CONSTANTS` config around each test to keep tests order-independent. `TEST_NAMES` (in `tests/test_variations.py`) is a list of name strings permuted into comma-separated variants as a regression check. Tests that should fail use `@pytest.mark.xfail`. When adding a parsing case, add it to the relevant `tests/test_*.py` file and consider adding the base form to `TEST_NAMES`.

docs/customize.rst

@@ -59,6 +59,8 @@ 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).
+* :py:obj:`~nameparser.config.Constants.initials_separator` - string placed between consecutive initials within the same name group (after the delimiter). Defaults to ``" "``, so ``"A. K."``; set to ``""`` for compact ``"A.K."``.
 
 
 

docs/release_log.rst

@@ -1,5 +1,16 @@
 Release Log
 ===========
+* 1.3.0 - Unreleased
+    - Add ``suffix_delimiter`` to ``Constants`` and ``HumanName`` for parsing suffixes separated by arbitrary delimiters, e.g. ``"RN - CRNA"`` (#156)
+    - Add ``initials_separator`` to ``Constants`` and ``HumanName`` to control spacing between consecutive initials within a name group (#171)
+    - Fix ``Constants`` customizations, singleton identity, and ``TupleManager`` subclass being lost across ``pickle``/``deepcopy`` round-trips (#167, #168, #169)
+    - Fix capitalization of suffix acronyms written with dots, e.g. ``"M.D."`` (closes #141)
+    - Fix recognition of single-letter roman numeral suffixes (e.g. ``"I"``, ``"V"``) in suffix-comma format (closes #136)
+    - Fix recognition of trailing ``suffix_not_acronyms`` (e.g. ``"Jr."``) in lastname-comma format (closes #144)
+    - Fix single-character symbol conjunctions (e.g. ``"&"``, ``"/"``) being ignored in short names (#173)
+    - Fix spurious leading space in surnames and empty token in suffix list after ``capitalize()`` with an empty middle or suffix (#164)
+    - Fix extra whitespace before punctuation in ``str()`` output when a ``string_format`` field is empty (closes #139)
+    - Fix ``'apn aprn'`` split into separate ``suffix_acronyms`` entries so each is recognized independently (closes #155)
 * 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

@@ -203,8 +203,26 @@ Furthermore, the delimiter for the string output can be set through:
 
   >>> HumanName("Doe, John A. Kenneth, Jr.", initials_delimiter=";").initials()
   'J; A; K; D;'
-  >>> HumanName("Doe, John A. Kenneth, Jr.", initials_format="{first}{middle}{last}", initials_delimiter=".").initials()
-  'J.A. K.D.'
+
+The separator between consecutive initials *within* a name group (e.g. two middle
+names) is controlled by :py:attr:`~nameparser.config.Constants.initials_separator`,
+which defaults to ``" "``. Setting it to ``""`` removes that space within a group;
+spacing *between* groups is still governed by ``initials_format``.
+
+``initials_delimiter``, ``initials_separator``, and ``initials_format`` work together:
+
+- ``initials_delimiter`` — appended *after* each individual initial (default ``"."``)
+- ``initials_separator`` — placed *after* the delimiter between consecutive initials in the same group (default ``" "``), so with ``delimiter="."`` and ``separator=" "`` you get ``A. K.``
+- ``initials_format`` — controls how the first, middle, and last groups are arranged
+
+For example, to produce compact period-separated initials with no spaces:
+
+.. doctest:: initials separator
+
+  >>> HumanName("Doe, John A. Kenneth, Jr.", initials_separator="", initials_format="{first}{middle}{last}").initials()
+  'J.A.K.D.'
+  >>> HumanName("Doe, John A. Kenneth, Jr.", initials_delimiter="", initials_separator="", initials_format="{first}{middle}{last}").initials()
+  'JAKD'
 
 To get a list representation of the initials, use :py:meth:`~nameparser.HumanName.initials_list`.
 This function is unaffected by :py:attr:`~nameparser.config.Constants.initials_format`

nameparser/config/__init__.py

@@ -9,8 +9,7 @@
 ::
 
     >>> from nameparser.config import CONSTANTS
-    >>> CONSTANTS.titles.remove('hon').add('chemistry','dean') # doctest: +ELLIPSIS
-    SetManager({'msgt', ..., 'adjutant'})
+    >>> CONSTANTS.titles.remove('hon').add('chemistry','dean') # doctest: +SKIP
 
 You can also adjust the configuration of individual instances by passing
 ``None`` as the second argument upon instantiation.
@@ -19,8 +18,7 @@
 
     >>> from nameparser import HumanName
     >>> hn = HumanName("Dean Robert Johns", None)
-    >>> hn.C.titles.add('dean') # doctest: +ELLIPSIS
-    SetManager({'msgt', ..., 'adjutant'})
+    >>> hn.C.titles.add('dean') # doctest: +SKIP
     >>> hn.parse_full_name() # need to run this again after config changes
 
 **Potential Gotcha**: If you do not pass ``None`` as the second argument,
@@ -265,6 +263,38 @@ class Constants:
     Will be used to add a delimiter between each initial.
     """
 
+    initials_separator = " "
+    """
+    The default separator placed between consecutive initials within a name
+    group (first, middle, or last). Distinct from ``initials_delimiter``,
+    which is the trailing character after each individual initial.
+
+    With defaults ``initials_delimiter="."`` and ``initials_separator=" "``,
+    ``initials()`` produces ``"J. A. D."``. Setting ``initials_separator=""``
+    with ``initials_delimiter="."`` and ``initials_format="{first}{middle}{last}"``
+    produces ``"J.A.D."``. With the default ``initials_format``, group-level
+    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/config/regexes.py

@@ -22,6 +22,7 @@
     ("period_not_at_end",re.compile(r'.*\..+$', re.I | re.U)),
     ("emoji",re_emoji),
     ("phd", re.compile(r'\s(ph\.?\s+d\.?)', re.I | re.U)),
+    ("space_before_comma", re.compile(r'\s+,', re.U)),
 ])
 """
 All regular expressions used by the parser are precompiled and stored in the config.

nameparser/config/suffixes.py

@@ -55,7 +55,8 @@
     'amieee',
     'ams',
     'aphr',
-    'apn aprn',
+    'apn',
+    'aprn',
     'apr',
     'apss',
     'aqp',