Show the Policy spellings that type-check

[derek73]

Summary

nameparser ships py.typed, and every Policy configuration example in the docs needed a # type: ignore[arg-type]. This changes the docs to teach the spellings that check clean.

Five spellings failed, not the two originally noticed:

documented	why it failed
Policy(script_orders={})	dict → tuple
Policy(segment_scripts=())	tuple → frozenset
Policy(nickname_delimiters={("[", "]")})	set → frozenset
Policy(maiden_delimiters={("(", ")")})	set → frozenset
Policy(script_orders=dict(DEFAULT_SCRIPT_ORDERS) | {...})	dict → tuple

The bare set literal for a delimiter field is the one most likely to bite in practice — it is the spelling anyone reaches for first, and it appeared in concepts.rst as the introductory example.

What is not changed, and why

The annotations. A dataclass field annotation types both the __init__ parameter and the attribute, and Policy normalizes in __post_init__ (its validators take object), so those two types genuinely differ. Python cannot express that with one annotation.

The annotation stays the storage type, because reading the attribute is the commoner operation and a union there would cascade to every reader — the same reasoning that already kept empty_attribute_default narrow. This is a real expressiveness gap, not sloppiness, and it applies to every normalizing field.

Union spellings were already fine and are untouched: frozenset | set is frozenset, so DEFAULT_NICKNAME_DELIMITERS | {("{", "}")} always checked clean.

The one spelling that needed a contract first

The script_orders override becomes:

Policy(script_orders=(*DEFAULT_SCRIPT_ORDERS, (Script.HAN, GIVEN_FIRST)))

which depends on a later entry replacing an earlier one. That behavior was emergent — _validated_script_orders builds a dict before sorting, and the comment there justifies it for hashability, not for override semantics. Prose telling readers to append is prose that depends on it, so tests/v2/test_policy.py now pins the override, the survival of the other entries, one-entry-per-script, and equality with the mapping spelling it replaces.

Verification

• Every spelling the docs now show, extracted verbatim into one file: mypy clean.
• uv run sphinx-build -b doctest docs — exit 0.
• uv run pytest -q — 3060 passed (was 3059; one new test).
• uv run mypy, uv run ruff check — clean.

Note for review

The .. note:: in customize.rst previously told readers the readable spellings need a # type: ignore. It now explains the storage-vs-constructor split instead, and says the wider spellings still parse identically for anyone not running a type checker.

I did not add a release-log entry: no behavior changed. Arguably the newly-contracted last-wins rule is a promise the library now makes and could warrant a line — happy to add one if you read it that way.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.48%. Comparing base (57f3b5d) to head (afde560).

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #334   +/-   ##
=======================================
  Coverage   98.48%   98.48%           
=======================================
  Files          41       41           
  Lines        2832     2832           
=======================================
  Hits         2789     2789           
  Misses         43       43           

☔ 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.