Background

crates/common/src/float_ops.rs had three independent implementations:

• mod_(v1, v2) — Python % operator
• floordiv(v1, v2) — Python // operator
• divmod(v1, v2) — Python divmod() builtin

Each independently converted Rust's dividend-sign % to CPython's divisor-sign convention. Two of them (mod_ and divmod) had the same gap — the sign-correction branch fired on zero remainders, producing values that violate Python's spec invariants.

Bugs

1. Zero-remainder + opposite-sign divisor (divmod and %)

divmod(0.0, -1.0)
# CPython:    (-0.0, -0.0)
# Pre-fix:    (-1.0, -1.0)   ← q and r both off by one
6.0 % -3.0
# CPython:    -0.0
# Pre-fix:    -3.0           ← |r| == |b|, violates 0 <= |r| < |b|
divmod(6.0, -3.0)
# CPython:    (-2.0, -0.0)
# Pre-fix:    (-3.0, -3.0)

The dividend-is-non-zero-exact-multiple cases fell into the default sign-correction branch, which adds the divisor to a zero remainder and decrements the quotient — yielding values that violate the magnitude invariant 0 <= |r| < |b|.

2. Signed-zero quotient leak (divmod)

divmod(-1.0, -2.0)
# CPython:    (+0.0, -1.0)
# Pre-fix:    (-0.0, -1.0)   ← quotient sign leaked from (v1 - m) / v2

When the true quotient is exactly zero, the (v1 - m) / v2 intermediate produces a signed zero whose sign reflects the intermediate division, not the true quotient v1 / v2. CPython's _float_div_mod snaps zero quotients via copysign(0.0, vx / wx).

3. Internal consistency violation (Python language spec)

Python guarantees divmod(a, b) == (a // b, a % b). RustPython didn't:

a, b = 6.0, -3.0
divmod(a, b)               # (-3.0, -3.0)   ← divmod's own bug
(a // b, a % b)            # (-2.0, -3.0)   ← floordiv correct, mod_ buggy

Three values, three different paths, three results that all disagreed.

Fix

Mirror CPython's _float_div_mod (Objects/floatobject.c) by making divmod the canonical implementation. mod_ and floordiv become thin wrappers that delegate and project, so divmod(a, b) == (a // b, a % b) holds by construction — no separate paths to keep in sync.

pub fn mod_(v1: f64, v2: f64) -> Option<f64> {
    divmod(v1, v2).map(|(_, m)| m)
}

pub fn floordiv(v1: f64, v2: f64) -> Option<f64> {
    divmod(v1, v2).map(|(d, _)| d)
}

pub fn divmod(v1: f64, v2: f64) -> Option<(f64, f64)> {
    if v2 == 0.0 {
        return None;
    }
    let mut m = v1 % v2;
    let mut d = (v1 - m) / v2;
    if m != 0.0 {
        if v2.is_sign_negative() != m.is_sign_negative() {
            m += v2;
            d -= 1.0;
        }
    } else {
        m = (0.0_f64).copysign(v2);     // zero remainder: sign of divisor
    }
    let d = if d != 0.0 {
        let f = d.floor();
        if d - f > 0.5 { f + 1.0 } else { f }   // CPython's half-up snap
    } else {
        (0.0_f64).copysign(v1 / v2)     // zero quotient: sign of true quotient
    };
    Some((d, m))
}

The half-up snap on non-zero quotient (if d - f > 0.5 { f + 1.0 } else { f }) mirrors CPython's safety net for cases where (v1 - m) / v2 undershoots the true integer quotient by more than half an ULP.

Verification

CPython 3.14.4 byte-identical for 44 cases spanning sign permutations, zero edges, exact divisions, IEEE 754 signed zero, and subnormals:

• divmod: 29 cases (all pass; pre-fix 8 failed)
• % operator (mod_): 8 cases (all pass; pre-fix 5 failed)
• // operator (floordiv): 7 cases (all pass on both)
• Internal consistency divmod == (//, %): 6 cases (all pass; pre-fix all 6 failed)

Regression sweep: test_float, test_int, test_complex, test_math, test_time, test_datetime, test_fractions, test_decimal — 1,471 tests, 0 regressions.

A regression test was added to extra_tests/snippets/builtin_divmod.py covering the bug class plus the divmod identity and magnitude/sign invariants.

Notes

divmod carries the canonical implementation (rather than introducing a private _float_div_mod helper) because all three public functions in this module already share the same Option<f64>-based API; a thin-wrapper pattern is the smallest delta that achieves single-source-of-truth without changing the public surface.

The half-up snap was added to match CPython exactly even though no probed case currently exercises it. It is correctness-relevant for extreme magnitudes where the intermediate (v1 - m) / v2 can lose precision.

Closes #7722

Summary by CodeRabbit

• Bug Fixes

  • Improved floating-point division operations to match Python's standard library behavior more closely, with better handling of edge cases involving signed zeros and operands with opposite signs.

• Tests

  • Added comprehensive test coverage for floating-point division edge cases and invariants.