Add clean_name utility and fallback_func support to lookup

[jcarbaugh]

Summary

Adds two related improvements to us.states for handling messy, free-form state input.

clean_name

A new utility that normalizes free-form text down to a bare state name. It lowercases the input, strips punctuation, removes the filler words the, state, commonwealth, and of, and collapses whitespace before recombining tokens into a single space-separated string.

>>> us.states.clean_name(' The state OF idaho ')
'idaho'
>>> us.states.lookup(us.states.clean_name('Commonwealth of Virginia'))
<State:Virginia>

clean_name is a standalone normalizer — it is not auto-wired into lookup, so existing callers are unaffected. Callers combine the two explicitly.

fallback_func argument on lookup

lookup now accepts an optional fallback_func. When the built-in FIPS / abbreviation / metaphone matching finds nothing, the fallback is called with the original, untransformed lookup value and its return value is used as the result. This lets callers plug in their own match logic. Fallback results are not cached.

A startswith_fallback helper is included as a ready-made fallback_func: it returns the first state or territory whose name starts with the given value (case-insensitive). An empty string matches nothing.

>>> us.states.lookup('verm', fallback_func=us.states.startswith_fallback)
<State:Vermont>

Testing

• 12 new tests in us/tests/test_us.py covering clean_name, the fallback_func behavior, and startswith_fallback.
• Full suite: 38 passed, 1 skipped. ruff check clean.

Notes

• README and CHANGELOG updated.

Linear issue: https://linear.app/apricotdotcool/issue/APR-30/add-clean-name-utility-and-fallback-func-support-to-lookup

[jcarbaugh]

Opened against the wrong repository by mistake; reopening on the correct fork.