Fix bare string to SetManager silently shredding into characters

[derek73]

Summary

• Constants(titles='dr') silently replaced the entire default titles set with {'d', 'r'} because a bare str satisfies Iterable[str] — as an iterable of its characters — and SetManager.__init__ fed it straight to set(); names then parsed wrong with no error anywhere (closes Constants(titles='dr') silently shreds a bare string into characters #238)
• SetManager now validates and normalizes at every entry point — constructor, all set operators (and reflections), with add()/remove() already covered:
  • Bare str/bytes raise TypeError with an actionable hint (wrap it in a list: ['dr']; bytes get decode it first: [b'dr'.decode()] since a wrapped bytes element would just be a quieter version of the same dead-config bug)
  • The operator paths needed their own guard: the ABC mixins' __or__/__and__ hand _from_iterable a generator, so c.titles |= 'esq' bypassed the constructor guard and silently added 'e', 's', 'q' as titles
  • Operands and constructor elements get the same lc() normalization as add() (lowercase, strip leading/trailing periods) — titles | ['Esq.'] kept a raw 'Esq.' that parser lookups could never match, titles & ['Dr.'] missed the stored 'dr', and Constants(titles=[...]) stored raw elements that silently never matched (this operator bug existed in released v1.2.1, not just on this branch)
  • Non-str elements (bytes, None, numbers) raise a curated TypeError instead of crashing context-free inside lc() or being silently transmuted (None became '')
• This has to be a runtime check — the type system can't distinguish str from Iterable[str]

Performance

The naive implementation (mixin delegation + per-construction validation) made HumanName(constants=None) 6.8× slower than master. Final shape restores master parity (Constants() 8.2µs, HumanName(constants=None) 58µs): operators build results with plain set ops via a private _from_normalized constructor, _normalized_elements short-circuits already-normalized SetManager operands, and the nine default config sets are validated once at import and copied on identity-checked defaults.

Safety

• All internal SetManager(...) call sites pass module-level tuples/sets (verified by grep); the shipped defaults are already lc()-normalized, so constructor normalization is a no-op for them
• Pickle/deepcopy restore SetManager by state without re-running __init__, so round-trips are unaffected
• Entries with internal periods ('univ.prof', 'ph.d') survive normalization — lc() strips leading/trailing periods only

Test plan

• All behavior TDD'd with verified-failing tests: bare-string kwarg/constructor/operand rejection (all six operator spellings), bytes decode hint, non-str element rejection, constructor + operand normalization for all seven operator methods (__rxor__ pinned separately), and end-to-end parses proving operator-built and kwarg-built sets behave like add()-built ones
• Full suite 1380 passed / 22 xfailed, mypy clean, ruff clean, Sphinx doctest build clean

Follow-up issues filed from review findings

• Non-descriptor Constants set attributes accept bare-string assignment; substring 'in' silently corrupts parsing #241 (non-descriptor Constants set attributes accept bare-string assignment), TupleManager string inputs: cryptic ValueError for bare strings, silent key/value shredding for 2-char elements #242 (TupleManager string handling), SetManager.__contains__ is the lone non-normalizing membership check #244 (__contains__ is now the lone non-normalizing membership check)

🤖 Generated with Claude Code

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.40%. Comparing base (192d35e) to head (3c705d4).
⚠️ Report is 1 commits behind head on master.
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #240      +/-   ##
==========================================
+ Coverage   97.26%   97.40%   +0.14%     
==========================================
  Files          13       13              
  Lines         805      849      +44     
==========================================
+ Hits          783      827      +44     
  Misses         22       22              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.