fix: suffixes_prefixes_titles always reflects current set state

[gaoflow]

Problem

Constants.suffixes_prefixes_titles cached its result in _pst after the
first access and never invalidated that cache. Any subsequent add() or
remove() call on titles, prefixes, suffix_acronyms, or
suffix_not_acronyms was silently ignored by the stale cache.

This creates an observable inconsistency: is_title() / is_prefix() /
is_suffix() query the live sets and return the correct answer, but
is_rootname() — which delegates to suffixes_prefixes_titles — keeps
returning the stale cached answer, causing it to contradict the other helpers.

Minimal reproduction:

from nameparser import HumanName
from nameparser.config import Constants

C = Constants()
# Access the property to prime the cache.
_ = C.suffixes_prefixes_titles

C.prefixes.add('xpfx')
hn = HumanName("", C)

# These two should agree — before this fix they don't:
print(hn.is_prefix('xpfx'))   # True  (correct — queries live set)
print(hn.is_rootname('xpfx')) # True  (wrong  — reads stale cache, should be False)

The same inconsistency affects titles and suffixes added or removed after the
property is first read. join_on_conjunctions relies on is_rootname to
count rootname_pieces and choose whether to join single-letter conjunctions,
so a stale _pst can silently skew that decision.

Fix

Keep _pst as a cache but wire invalidation callbacks so it is cleared
whenever any of the four contributing SetManager attributes changes.

A new _CachedUnionMember descriptor manages each of prefixes,
suffix_acronyms, suffix_not_acronyms, and titles. On assignment it
detaches the old manager's callback, wires the new manager's _on_change to
_invalidate_pst, and clears the cache. SetManager.add_with_encoding and
remove fire _on_change after each mutation, so in-place changes
invalidate the cache too.

This preserves the performance benefit of caching while fixing the staleness.

Tests

Thirteen new tests in tests/test_constants.py verify that:

• suffixes_prefixes_titles reflects add/remove on all four contributing sets,
  both on a cold cache and after priming.
• is_rootname stays consistent with is_title/is_prefix after mutations.
• Replacing a whole SetManager invalidates the cache and wires the new
  manager's callbacks.
• A detached (replaced) manager no longer invalidates the cache.
• add_with_encoding invalidates the cache.
• A pickle round-trip re-wires the invalidation callbacks correctly.

All 734 tests pass (20 xfailed).

---

This pull request was prepared with the assistance of AI, under my direction and review.

[derek73]

Two follow-up commits added based on review feedback:

f69ecee — perf: restore _pst cache with proper invalidation

The original fix dropped the cache entirely, which is ~1000x slower per call (~69 µs vs ~70 ns). This commit restores it with correct invalidation:

• SetManager now accepts an optional on_change callback, fired after add / remove — so user mutations immediately clear _pst
• Constants.__setattr__ clears _pst and re-wires the callback whenever one of the four contributing attrs is replaced — this covers the test fixture teardown path where setattr(CONSTANTS, 'prefixes', SetManager(...)) swaps in a fresh instance
• The manual CONSTANTS._pst = None reset in conftest.py is removed; __setattr__ handles it automatically

5fc4b6b — test: expand coverage and add assertNotIn helper

• Added a prime-then-mutate test (_ = c.suffixes_prefixes_titles; c.titles.add(...); assertIn(...)) — the exact scenario from the bug report, which none of the original five tests exercised
• Added add-tests for suffix_acronyms and suffix_not_acronyms (both were untested)
• Added a remove-test for prefixes (mirroring the existing titles remove test)
• Replaced assertFalse(x in ...) with assertNotIn (added shim to HumanNameTestBase)

690 tests pass (682 pre-existing + 8 new × dual-run fixture).

[derek73]

388c65b — refactor: replace the __setattr__ cache-invalidation with a descriptor

A follow-up on the cache-invalidation machinery added in f69ecee. That commit kept the _pst cache correct after add()/remove() by wiring a SetManager.on_change callback and using a custom Constants.__setattr__ (plus a _PST_ATTRS frozenset) to clear _pst and re-wire the callback whenever one of the four contributing attributes was replaced. It worked, but a closer review surfaced three issues worth tidying before merge:

1. The __setattr__ was global for a four-attribute concern. It ran on every attribute assignment to Constants (string_format, capitalize_name, …), paying an in-check each time, and the "which attributes are cached" knowledge was duplicated across three places that had to be kept in sync by hand: the _PST_ATTRS frozenset, the attribute annotations, and the union expression in suffixes_prefixes_titles.

2. A stale-callback leak. Reassigning a manager (c.prefixes = SetManager(...)) wired the new one but never detached the old one. The orphaned manager still held self._invalidate_pst, so mutating that dangling reference would invalidate a cache it was no longer part of — benign (it only nulls the cache, never corrupts it), but a latent foot-gun and an unnecessary recompute.

3. A dead constructor parameter. SetManager.__init__(on_change=...) was never actually passed — wiring always happened afterward via the external value._on_change = ... poke (including the config-teardown setattr path). The advertised constructor contract didn't match how the callback was really wired.

The fix moves the behavior onto a small _CachedUnionMember descriptor placed on exactly the four cached attributes:

• Invalidation/re-wiring now lives beside the attributes it governs and fires only for those four, so the global __setattr__ and the _PST_ATTRS frozenset are both gone.
• On reassignment it detaches the replaced manager (previous._on_change = None), closing the stale-callback leak.
• The unused on_change constructor parameter is dropped; _on_change is initialized to None and wired by the owning Constants, which is the only path that was ever exercised.

The in-place add()/remove() → _on_change callback mechanism on SetManager is unchanged — that's still what catches mutations to an existing manager; only the whole-attribute-replacement path moved from __setattr__ to the descriptor.

Behavior, mypy, and ruff are all unchanged (the descriptor uses @overload for the instance-vs-class __get__ return types so the SetManager type still flows through). Parse throughput is identical to the cached baseline — ~18 µs/name, vs ~263 µs/name with no cache — so the performance reason for keeping _pst still holds.

New tests cover the paths the previous version left unguarded: the replaced-manager re-wiring path, the "orphaned manager no longer invalidates the live cache" guarantee (asserted by cache identity, since the leak's only symptom is an unnecessary recompute), add_with_encoding invalidation, and removal from the two suffix sets after the cache is primed. 700 passed, 20 xfailed.

[derek73]

Update

Since opening this PR, a few things have happened:

• Merged PR Fix pickle/copy round-trip bugs in Constants and config managers #168 into main, then rebased this branch on top of those changes.
• Ran a code review on the branch which surfaced a few hardening opportunities, now addressed in the latest commit:
  • SetManager.remove() no longer fires _on_change on no-op calls (nothing actually removed)
  • _CachedUnionMember.__set__ now raises TypeError if assigned a non-SetManager value, rather than silently skipping hook wiring and leaving the cache broken
  • Constants.__setstate__ now verifies all descriptor-backed attrs were restored from the pickle state, and raises a clear ValueError (with the public attr name) if any are missing — previously a truncated blob would surface as a confusing AttributeError exposing the private _prefixes name
  • Replaced a duplicate test with a pickle round-trip test that verifies _on_change is re-wired after unpickling
  • Minor: UnicodeDecodeError fallback in the test base now preserves actual/expected in the assertion message

From my end I'm happy with the state of this. I'll wait a few days to see if the original contributor has any feedback before merging.