Normalize SetManager operator operands like add() does

The Set mixin operators build results from raw operand elements and
test them against the stored (normalized) ones, so even with the
bare-string guard, (titles | ['Esq.']) kept a raw 'Esq.' the parser's
lc() lookups could never match, and (titles & ['Dr.']) missed 'dr' —
the same silently-broken-config family as #238, one step from the
guarded case. Operands now pass through lc() in the existing operator
overrides, so operator results obey the same normalized-elements
invariant as add()-built sets. Idempotent for already-normalized
operands, so the internal suffixes_prefixes_titles union is unchanged.

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

Author: derek73

docs/release_log.rst

@@ -2,6 +2,7 @@ Release Log
 ===========
 * 1.3.0 - Unreleased
     - Fix a bare string passed to a set-backed ``Constants`` argument (e.g. ``Constants(titles='dr')``), to ``SetManager``, or as a ``SetManager`` set-operator operand (e.g. ``constants.titles |= 'esq'``) being silently split into single characters, replacing or polluting the set and producing wrong parses with no error; it now raises ``TypeError`` with the suggested fix — wrap strings in a list, decode ``bytes`` first (closes #238)
+    - Fix ``SetManager`` set operators skipping the lowercase/strip-periods normalization that ``add()`` applies: ``constants.titles |= ['Esq.']`` kept a raw ``'Esq.'`` the parser's lookups could never match, and ``titles & ['Dr.']`` missed ``'dr'``; operator operands are now normalized, so operator results behave like ``add()``-built sets
     - Fix the ``constants`` constructor argument silently discarding ``Constants`` *subclass* instances: the exact-type check replaced them with fresh defaults, throwing away the caller's configuration. Subclass instances are now used as given; anything that is neither ``None`` nor a ``Constants`` instance now raises ``TypeError`` instead of being silently swapped for defaults (closes #226)
     - Fix ``IndexError`` in ``initials()``/``initials_list()`` when a ``*_list`` attribute was assigned directly with an element containing unnormalized whitespace (e.g. ``name.middle_list = ['Q  R']``), bypassing the parser's whitespace normalization (closes #232)
     - Fix ``HumanName`` acting as its own iterator with a stored cursor: breaking out of a loop, iterating in nested loops, or calling ``len(name)`` mid-loop corrupted subsequent iteration; ``iter(name)`` now returns a fresh independent iterator each time. ``next(name)`` on the instance itself (undocumented) now raises ``TypeError`` — call ``next(iter(name))`` instead (closes #225)

nameparser/config/__init__.py

@@ -61,7 +61,9 @@ class SetManager(Set):
     and remove()d, and to allow passing multiple string arguments to the
     :py:func:`add()` and :py:func:`remove()` methods. The constructor and
     the set operators also reject a bare string with ``TypeError``, since
-    e.g. ``set('dr')`` would silently build a set of single characters.
+    e.g. ``set('dr')`` would silently build a set of single characters, and
+    the set operators normalize their operands the same way :py:func:`add()`
+    does, so operator results keep the normalized-elements invariant.
 
     '''
 
@@ -113,32 +115,37 @@ def __len__(self) -> int:
     # __init__ guard never sees a bare-string operand (c.titles |= 'esq'
     # would silently add 'e', 's', 'q'); __sub__/__xor__ raised only by
     # accident of constructing from the operand. Check all four uniformly.
+    # Operands are also normalized the way add() normalizes elements: the
+    # mixins build results from raw operand elements and test them against
+    # the stored (normalized) ones, so without this (titles | ['Esq.'])
+    # keeps a raw 'Esq.' the parser's lc() lookups can never match, and
+    # (titles & ['Dr.']) misses 'dr' — silently broken config either way.
+    @classmethod
+    def _normalized_operand(cls, other: Iterable[str]) -> set[str]:
+        cls._reject_bare_string(other)
+        return {lc(s) for s in other}
+
     # the runtime ABC accepts any Iterable operand, so annotate honestly and
     # ignore typeshed's narrower AbstractSet declarations
     def __or__(self, other: Iterable[str]) -> 'SetManager':  # type: ignore[override]
-        self._reject_bare_string(other)
-        return super().__or__(other)  # type: ignore[operator, return-value]
+        return super().__or__(self._normalized_operand(other))  # type: ignore[operator, return-value]
 
     __ror__ = __or__
 
     def __and__(self, other: Iterable[str]) -> 'SetManager':  # type: ignore[override]
-        self._reject_bare_string(other)
-        return super().__and__(other)  # type: ignore[operator, return-value]
+        return super().__and__(self._normalized_operand(other))  # type: ignore[operator, return-value]
 
     __rand__ = __and__
 
     def __sub__(self, other: Iterable[str]) -> 'SetManager':  # type: ignore[override]
-        self._reject_bare_string(other)
-        return super().__sub__(other)  # type: ignore[operator, return-value]
+        return super().__sub__(self._normalized_operand(other))  # type: ignore[operator, return-value]
 
     def __rsub__(self, other: Iterable[str]) -> 'SetManager':  # type: ignore[override]
-        self._reject_bare_string(other)
         # typeshed omits Set.__rsub__, but the runtime ABC defines it
-        return super().__rsub__(other)  # type: ignore[misc, operator, return-value]
+        return super().__rsub__(self._normalized_operand(other))  # type: ignore[misc, operator, return-value]
 
     def __xor__(self, other: Iterable[str]) -> 'SetManager':  # type: ignore[override]
-        self._reject_bare_string(other)
-        return super().__xor__(other)  # type: ignore[operator, return-value]
+        return super().__xor__(self._normalized_operand(other))  # type: ignore[operator, return-value]
 
     __rxor__ = __xor__
 

tests/test_constants.py

@@ -85,6 +85,28 @@ def test_set_manager_operators_accept_lists(self) -> None:
         hn = HumanName("Esq Jane Smith", constants=c)
         self.m(hn.title, "Esq", hn)
 
+    def test_set_manager_operators_normalize_like_add(self) -> None:
+        # add() lowercases and strips periods; without the same normalization
+        # of operator operands, (titles | ['Esq.']) contains raw 'Esq.', which
+        # the parser's lc()-based lookups can never match — silently broken
+        # config, same failure family as the bare-string shredding (#238)
+        sm = SetManager(['dr', 'mr'])
+        self.assertEqual((sm | ['Esq.']).elements, {'dr', 'mr', 'esq'})
+        self.assertEqual((['Esq.', 'Dr.'] | sm).elements, {'dr', 'mr', 'esq'})
+        self.assertEqual((sm & ['Dr.']).elements, {'dr'})
+        self.assertEqual((['Dr.'] & sm).elements, {'dr'})
+        self.assertEqual((sm - ['Dr.']).elements, {'mr'})
+        self.assertEqual((['Dr.', 'Esq.'] - sm).elements, {'esq'})
+        self.assertEqual((sm ^ ['Dr.', 'Esq.']).elements, {'mr', 'esq'})
+
+    def test_set_manager_operator_result_parses_when_wired_into_constants(self) -> None:
+        # end-to-end: an operator-built set must behave like an add()-built
+        # one once assigned back to Constants
+        c = Constants()
+        c.titles |= ['Esq.']
+        hn = HumanName("Esq Jane Smith", constants=c)
+        self.m(hn.title, "Esq", hn)
+
     def test_remove_title(self) -> None:
         hn = HumanName("Hon Solo", constants=None)
         start_len = len(hn.C.titles)