[lohitredddy]

clamp() documents callable formatters and a None input, but its annotations reject both uses. For example, mypy rejects clamp(1, format=intword, floor=1e6) and clamp(None) even though both already work at runtime.

Changes proposed in this pull request:

• Accept string and callable formatters in the type annotations.
• Add overloads so numeric calls retain a precise str return type and None calls return None; clarify the existing behavior in the docstring.
• Add typing.assert_type regression coverage alongside runtime assertions for those calls.

The function body is unchanged. The new assertions produce three mypy errors against the original annotations and pass with this change.

Validation on Python 3.12:

• Number tests: 242 passed.
• Full test suite: 747 passed, 110 skipped (compiled locale catalogs are unavailable in this checkout).
• mypy: no issues in 14 source files, run with --num-workers 0.
• Ruff and Black checks on both changed files, plus git diff --check: passed.

Other Python versions and the full pre-commit hook collection were not run.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.70%. Comparing base (785e5dc) to head (476caec).
⚠️ Report is 27 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #458   +/-   ##
=======================================
  Coverage   99.69%   99.70%           
=======================================
  Files          12       12           
  Lines         995     1000    +5     
=======================================
+ Hits          992      997    +5     
  Misses          3        3           

Flag	Coverage Δ
macos-latest	97.60% <100.00%> (+0.01%)	⬆️
ubuntu-latest	97.60% <100.00%> (+0.01%)	⬆️
windows-latest	93.30% <100.00%> (+0.03%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

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

[hugovk]

Superseded by #516:

• Drop eager typing import, we don't need @overload
• No need to test typing things

I would have pushed here, but you've disabled "Allow edits by maintainers". Please keep that ticked next time.