Simplify and speed up SetManager normalization paths

The operand-normalization work left a compounding perf regression:
operators delegated to the ABC mixins, whose _from_iterable re-entered
__init__ and re-validated the entire result element by element, and
Constants() re-checked ~1,400 already-normalized default constants on
every construction. Measured on the headline per-instance-config path,
HumanName(constants=None) was 6.8x slower than master (101 -> 690us)
and Constants() 21.6x slower (7.5 -> 162us).

Build operator results with plain set ops on already-normalized
elements via a private _from_normalized constructor (also dropping the
super()-delegation type ignores), short-circuit SetManager operands in
_normalized_elements (a SetManager is normalized by construction), and
validate the nine default config sets once at import, copied on
identity-checked defaults. Back to master parity: Constants() 8.2us,
HumanName(constants=None) 58us.

Also fold the single-caller _reject_bare_string into
_normalized_elements, note the deliberate bytes-policy divergence from
add_with_encoding(), merge two tests that pinned the same |= parse
end-to-end, trim the triple-stated operator rationale, and update the
stale AGENTS.md SetManager normalization note.

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

Author: derek73

AGENTS.md

@@ -85,7 +85,7 @@ Most modules define a plain Python set of known name pieces; `capitalization.py`
 
 `config/__init__.py` wraps everything into `SetManager` and `TupleManager` instances inside a `Constants` class. A module-level singleton `CONSTANTS` is shared across all `HumanName` instances by default.
 
-**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.
+**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` normalizes elements (lowercase, leading/trailing periods stripped) at every entry point — constructor, `add()`/`remove()`, and set operators — and raises `TypeError` for bare strings/bytes and non-str elements, 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('_')`.
 

nameparser/config/__init__.py

@@ -70,29 +70,33 @@ class SetManager(Set):
 
     _on_change: Callable[[], None] | None
 
-    @staticmethod
-    def _reject_bare_string(value: object) -> None:
+    @classmethod
+    def _normalized_elements(cls, elements: Iterable[str]) -> set[str]:
+        # a SetManager's elements were validated and normalized when it was
+        # built, so copy them instead of re-validating — this is what keeps
+        # chained unions (suffixes_prefixes_titles) and default Constants()
+        # construction from re-checking ~1,400 entries per step
+        if isinstance(elements, SetManager):
+            return set(elements.elements)
         # a bare string is an iterable of its characters, so set(value)
         # would silently build a set of single characters — and bytes
         # iterates to ints, which can never match parsed tokens (#238)
-        if isinstance(value, bytes):
+        if isinstance(elements, bytes):
             raise TypeError(
                 "expected an iterable of strings, got a single bytes; "
-                f"decode it first: [{value!r}.decode()]"
+                f"decode it first: [{elements!r}.decode()]"
             )
-        if isinstance(value, str):
+        if isinstance(elements, str):
             raise TypeError(
                 "expected an iterable of strings, got a single str; "
-                f"wrap it in a list: [{value!r}]"
+                f"wrap it in a list: [{elements!r}]"
             )
-
-    @classmethod
-    def _normalized_elements(cls, elements: Iterable[str]) -> set[str]:
         # apply the same lc() normalization (lowercase, strip leading/
         # trailing periods) that add() applies, and reject junk elements:
         # lc() on bytes or int crashes without naming the culprit, and
-        # lc(None) silently transmutes to ''
-        cls._reject_bare_string(elements)
+        # lc(None) silently transmutes to ''. Divergence from add() is
+        # deliberate: add_with_encoding() decodes bytes for back-compat,
+        # bulk boundaries stay strict.
         normalized = set()
         for s in elements:
             if isinstance(s, bytes):
@@ -106,6 +110,16 @@ def _normalized_elements(cls, elements: Iterable[str]) -> set[str]:
             normalized.add(lc(s))
         return normalized
 
+    @classmethod
+    def _from_normalized(cls, elements: set[str]) -> 'SetManager':
+        # private fast constructor for sets this class already normalized
+        # (operator results, prebuilt default copies); bypasses __init__
+        # so results aren't re-validated element by element
+        obj = cls.__new__(cls)
+        obj.elements = elements
+        obj._on_change = None
+        return obj
+
     def __init__(self, elements: Iterable[str]) -> None:
         self.elements = self._normalized_elements(elements)
         # Optional invalidation hook, wired by an owning Constants so that
@@ -131,36 +145,33 @@ def __contains__(self, value: object) -> bool:
     def __len__(self) -> int:
         return len(self.elements)
 
-    # Set's mixin operators compare operand and stored elements without
-    # normalizing (and __or__/__and__ hand _from_iterable a generator, so
-    # the __init__ guard alone never sees a bare-string operand: c.titles
-    # |= 'esq' would silently add 'e', 's', 'q'). Normalize every operand
-    # through _normalized_elements so operator results behave like
-    # add()-built sets: without it (titles | ['Esq.']) keeps a raw 'Esq.'
-    # the parser's lc() lookups can never match, and (titles & ['Dr.'])
-    # misses the stored 'dr'.
+    # The ABC mixins compare raw operand elements against stored (normalized)
+    # ones, and their __or__/__and__ accept a bare str as Iterable, so every
+    # operand is validated and normalized here. Results are built with plain
+    # set ops on already-normalized elements instead of delegating to the
+    # mixins, whose _from_iterable would re-validate the whole result
+    # through __init__.
     #
     # 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]
-        return super().__or__(self._normalized_elements(other))  # type: ignore[operator, return-value]
+        return self._from_normalized(self.elements | self._normalized_elements(other))
 
     __ror__ = __or__
 
     def __and__(self, other: Iterable[str]) -> 'SetManager':  # type: ignore[override]
-        return super().__and__(self._normalized_elements(other))  # type: ignore[operator, return-value]
+        return self._from_normalized(self.elements & self._normalized_elements(other))
 
     __rand__ = __and__
 
     def __sub__(self, other: Iterable[str]) -> 'SetManager':  # type: ignore[override]
-        return super().__sub__(self._normalized_elements(other))  # type: ignore[operator, return-value]
+        return self._from_normalized(self.elements - self._normalized_elements(other))
 
-    def __rsub__(self, other: Iterable[str]) -> 'SetManager':  # type: ignore[override]
-        # typeshed omits Set.__rsub__, but the runtime ABC defines it
-        return super().__rsub__(self._normalized_elements(other))  # type: ignore[misc, operator, return-value]
+    def __rsub__(self, other: Iterable[str]) -> 'SetManager':
+        return self._from_normalized(self._normalized_elements(other) - self.elements)
 
     def __xor__(self, other: Iterable[str]) -> 'SetManager':  # type: ignore[override]
-        return super().__xor__(self._normalized_elements(other))  # type: ignore[operator, return-value]
+        return self._from_normalized(self.elements ^ self._normalized_elements(other))
 
     __rxor__ = __xor__
 
@@ -227,6 +238,22 @@ def _is_dunder(attr: str) -> bool:
     return attr.startswith("__") and attr.endswith("__")
 
 
+# The default config sets are module constants that never change, so
+# validate and normalize each one exactly once at import. Constants()
+# copies these via _normalized_elements' SetManager fast path instead of
+# re-checking ~1,400 elements per construction — a real cost on the
+# per-instance-config path, HumanName(constants=None).
+_DEFAULT_PREFIXES = SetManager(PREFIXES)
+_DEFAULT_SUFFIX_ACRONYMS = SetManager(SUFFIX_ACRONYMS)
+_DEFAULT_SUFFIX_NOT_ACRONYMS = SetManager(SUFFIX_NOT_ACRONYMS)
+_DEFAULT_SUFFIX_ACRONYMS_AMBIGUOUS = SetManager(SUFFIX_ACRONYMS_AMBIGUOUS)
+_DEFAULT_TITLES = SetManager(TITLES)
+_DEFAULT_FIRST_NAME_TITLES = SetManager(FIRST_NAME_TITLES)
+_DEFAULT_CONJUNCTIONS = SetManager(CONJUNCTIONS)
+_DEFAULT_BOUND_FIRST_NAMES = SetManager(BOUND_FIRST_NAMES)
+_DEFAULT_NON_FIRST_NAME_PREFIXES = SetManager(NON_FIRST_NAME_PREFIXES)
+
+
 class TupleManager(dict[str, T]):
     '''
     A dictionary with dot.notation access. Subclass of ``dict``. Wraps the
@@ -561,15 +588,18 @@ def __init__(self,
         # These four descriptor assignments call _CachedUnionMember.__set__, which
         # calls _invalidate_pst() and establishes self._pst. They must come before
         # any read of suffixes_prefixes_titles.
-        self.prefixes = SetManager(prefixes)
-        self.suffix_acronyms = SetManager(suffix_acronyms)
-        self.suffix_not_acronyms = SetManager(suffix_not_acronyms)
-        self.titles = SetManager(titles)
-        self.first_name_titles = SetManager(first_name_titles)
-        self.conjunctions = SetManager(conjunctions)
-        self.bound_first_names = SetManager(bound_first_names)
-        self.non_first_name_prefixes = SetManager(non_first_name_prefixes)
-        self.suffix_acronyms_ambiguous = SetManager(suffix_acronyms_ambiguous)
+        # untouched defaults (identity check) copy the prebuilt module-level
+        # managers instead of re-validating the raw constants element by
+        # element; user-supplied iterables still get the full check
+        self.prefixes = SetManager(_DEFAULT_PREFIXES if prefixes is PREFIXES else prefixes)
+        self.suffix_acronyms = SetManager(_DEFAULT_SUFFIX_ACRONYMS if suffix_acronyms is SUFFIX_ACRONYMS else suffix_acronyms)
+        self.suffix_not_acronyms = SetManager(_DEFAULT_SUFFIX_NOT_ACRONYMS if suffix_not_acronyms is SUFFIX_NOT_ACRONYMS else suffix_not_acronyms)
+        self.titles = SetManager(_DEFAULT_TITLES if titles is TITLES else titles)
+        self.first_name_titles = SetManager(_DEFAULT_FIRST_NAME_TITLES if first_name_titles is FIRST_NAME_TITLES else first_name_titles)
+        self.conjunctions = SetManager(_DEFAULT_CONJUNCTIONS if conjunctions is CONJUNCTIONS else conjunctions)
+        self.bound_first_names = SetManager(_DEFAULT_BOUND_FIRST_NAMES if bound_first_names is BOUND_FIRST_NAMES else bound_first_names)
+        self.non_first_name_prefixes = SetManager(_DEFAULT_NON_FIRST_NAME_PREFIXES if non_first_name_prefixes is NON_FIRST_NAME_PREFIXES else non_first_name_prefixes)
+        self.suffix_acronyms_ambiguous = SetManager(_DEFAULT_SUFFIX_ACRONYMS_AMBIGUOUS if suffix_acronyms_ambiguous is SUFFIX_ACRONYMS_AMBIGUOUS else suffix_acronyms_ambiguous)
         self.capitalization_exceptions = TupleManager(capitalization_exceptions)
         self.regexes = RegexTupleManager(regexes)
         # Per-bucket delimiter collections that parse_nicknames() consults to

tests/test_constants.py

@@ -77,10 +77,12 @@ def test_set_manager_bare_string_operand_raises_typeerror(self) -> None:
                 op()
 
     def test_set_manager_operators_accept_lists(self) -> None:
+        # end-to-end: an operator-built set wired back into Constants must
+        # behave like an add()-built one, normalization included
         c = Constants()
         with pytest.raises(TypeError, match=r"wrap it in a list"):
             c.titles |= 'esq'
-        c.titles |= ['esq']
+        c.titles |= ['Esq.']
         self.assertIn('esq', c.titles)
         hn = HumanName("Esq Jane Smith", constants=c)
         self.m(hn.title, "Esq", hn)
@@ -128,14 +130,6 @@ def test_set_manager_non_str_elements_raise_typeerror(self) -> None:
         with pytest.raises(TypeError, match=r"expected str elements"):
             SetManager(['dr']) | [1]  # type: ignore[list-item]
 
-    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)