Carry metric() to the next SI prefix when rounding reaches 1000

[gaoflow]

Summary

metric() can emit a four-digit mantissa with a too-small SI prefix:

>>>humanize.metric(999.9, "V")
'1000 V'# expected '1.00 kV'>>>humanize.metric(999.99, "V")
'1000 V'# expected '1.00 kV'>>>humanize.metric(999999, "V")
'1000 kV'# expected '1.00 MV'>>>humanize.metric(0.0009999, "V")
'1000 μV'# expected '1.00 mV'

This contradicts the function's own docstring, which states the prefix is

always chosen so that non-significant zero digits are required ... 1,230,000 will become 1.23M instead of 1230K

1000 V / 1000 kV are precisely the 1230K-style outputs it promises to avoid, so the documented contract is the oracle here.

Root cause

metric() selects the SI prefix bucket from exponent = floor(log10(abs(value))) on the raw value, then rounds the mantissa to the requested precision. When the value sits just below a power-of-1000 boundary, the rounded mantissa becomes 1000, but the prefix was already locked in from the pre-rounding exponent, and the code never re-checks whether rounding crossed into the next bucket.

Fix

After computing the mantissa and its display precision, if round(abs(mantissa), digits) >= 1000 and a higher prefix is available (exponent < 30), advance to the next prefix bucket and re-divide. The top of the SI range (quetta, Q, 10^30) has no higher prefix, so the exponent < 30 guard leaves it unchanged rather than indexing past the prefix table.

Tests

Added four cases to the test_metric parametrization (the carry cases above). They fail on main ('1000 V' != '1.00 kV', etc.) and pass with this change. The full tests/test_number.py suite passes (223 passed), so existing metric() output, including the high-range QF/qA cases and the exact power-of-1000 inputs, is unchanged.

Disclosure: I developed this fix with AI assistance, under my direction. I reviewed and verified the boundary behaviour (positive carry, the negative-exponent mV path, and the top-of-range quetta guard) and the regression run myself, and I am happy to adjust the approach.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.55%. Comparing base (976484a) to head (4b69e61).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@ Coverage Diff @@## main #328 +/- ##
=======================================
Coverage 99.55% 99.55% =======================================
Files 12 12 Lines 900 907 +7 =======================================
+ Hits 896 903 +7 
Misses 4 4 

Flag	Coverage Δ
macos-latest	97.57% <100.00%> (+0.01%)	⬆️
ubuntu-latest	97.57% <100.00%> (+0.01%)	⬆️
windows-latest	95.70% <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.

[codspeed-hq]

Merging this PR will degrade performance by 14.55%

⚠️Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

❌ 1 regressed benchmark
✅ 14 untouched benchmarks

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
❌	test_metric	44.1 µs	51.6 µs	-14.55%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing gaoflow:fix/metric-si-prefix-carry (4b69e61) with main (c2c410c)}

[hugovk]

Thanks!