Add typing.SupportsIndex to int/float/complex type hints

[rwgk]

Description

Production code changes isolated from #5879

Quoting from there:

This corrects a mistake where these types were supported but the type hint was not updated to reflect that SupportsIndex objects are accepted.

Isolated out mainly to have the corresponding sprawling changes to the unit tests separately, to minimize the chances that we're overlooking something important in the more critical PR #5879.

Note: In contrast to #5879, the noconvert conversion behavior is unchanged. Only the complex-caster convert behavior is changed (bug fix), and the type hints.

Note: Most of the legwork here was done by Cursor.

@gentlegiantJGC @InvincibleRMC for visibility

Suggested changelog entry:

• Correct a mistake where support for __index__ was added, but the type hints were not updated to reflect that SupportsIndex objects are accepted. Also fix a long-standing bug: the complex-caster was not accepting __index__ in convert mode.

[henryiii]

Only int SupportsIndex. float and complex do not? SupportsIndex means a type can be losslessly converted to an integer for indexing, that is something[x] is supported for x. They should not have an __index__. Only int and types like int should.

[InvincibleRMC]

You're missing the tests I believe which show this is already happening at run time.

[rwgk]

Only int SupportsIndex. float and complex do not? SupportsIndex means a type can be losslessly converted to an integer for indexing, that is something[x] is supported for x. They should not have an __index__. Only int and types like int should.

I'm not completely clear about that (yet) myself.

The goal of this PR

• is not to reach a final desired state,
• but to correct a particular mistake in isolation, to make other changes to the tests easier to review.

Currently I'm thinking PR #5879 is good as-is, but

• I don't want to make such a big leap,
• and I think we should release pybind11 v3.0.2 without the (other) production code changes in PR 5879,
• but right after the release merge the rest of PR 5879.

[InvincibleRMC]

Only int SupportsIndex. float and complex do not? SupportsIndex means a type can be losslessly converted to an integer for indexing, that is something[x] is supported for x. They should not have an __index__. Only int and types like int should.

If you look at the bottom of float and complex they fallback on index. https://docs.python.org/3.13/library/functions.html#float

[henryiii]

Ahh, this is for input only?

[rwgk]

Ahh, this is for input only?

I want to actually merge this PR, then merge master into PR 5879. Hopefully that'll clear up a lot of the unit test diffs there.

[rwgk]

oops, I clicked ready for review button too fast, I'm seeing the request for change only now

[rwgk]

@InvincibleRMC wrote:

You're missing the tests I believe which show this is already happening at run time.

Could you please help me with concrete pointers?

I did not try to transfer any additional tests from PR 5879, but if you point at specific ones that you think should be included here, I could do that. I could also give you write permission to this branch, so that you can make changes directly. Please let me know.

[InvincibleRMC]

The tests that pass in custom classes with __index__ into float and complex args. I think it's float convert and complex convert.

[rwgk]

The tests that pass in custom classes with index into float and complex args. I think it's float convert and complex convert.

@InvincibleRMC do these commits look right?

• 77c7fca — Cursor-generated commit: Added the Index() tests from PR 5879.
• 9c333f1 — Reflect behavior changes going back from PR 5879 to master. This diff will have to be reapplied under PR 5879.

[rwgk]

The three pypy-3.10 jobs (ubuntu, macos-13, windows-latest) are failing with the error below.

Fixing that will be a behavior change, but I think we should do that in this PR, because it's in convert mode, i.e. "related but different" from the goal of PR 5879. It's more a bug fix actually IMO than a behavior change.

I.e. we'd need to extract out the corresponding changes from PR 5879 as well.

@InvincibleRMC could you please let me know if you agree or disagree?

I'll play with Cursor some more to see if it is capable of doing that for us.

=================================== FAILURES ===================================
______________________________ test_complex_cast _______________________________

doc = <conftest.SanitizedString object at 0x0000000011743210>

    def test_complex_cast(doc):
        """std::complex casts"""
    
        class Complex:
            def __complex__(self) -> complex:
                return complex(5, 4)
    
        class Float:
            def __float__(self) -> float:
                return 5.0
    
        class Int:
            def __int__(self) -> int:
                return 3
    
        class Index:
            def __index__(self) -> int:
                return 1
    
        assert m.complex_cast(1) == "1.0"
        assert m.complex_cast(1.0) == "1.0"
        assert m.complex_cast(Complex()) == "(5.0, 4.0)"
        assert m.complex_cast(2j) == "(0.0, 2.0)"
    
        convert, noconvert = m.complex_convert, m.complex_noconvert
    
        def requires_conversion(v):
            pytest.raises(TypeError, noconvert, v)
    
        def cant_convert(v):
            pytest.raises(TypeError, convert, v)
    
        assert (
            doc(convert)
            == "complex_convert(arg0: typing.SupportsComplex | typing.SupportsFloat | typing.SupportsIndex) -> complex"
        )
        assert doc(noconvert) == "complex_noconvert(arg0: complex) -> complex"
    
        assert convert(1) == 1.0
        assert convert(2.0) == 2.0
        assert convert(1 + 5j) == 1.0 + 5.0j
        assert convert(Complex()) == 5.0 + 4j
        assert convert(Float()) == 5.0
        assert isinstance(convert(Float()), complex)
        cant_convert(Int())
>       assert convert(Index()) == 1
E       TypeError: complex_convert(): incompatible function arguments. The following argument types are supported:
E           1. (arg0: typing.SupportsComplex | typing.SupportsFloat | typing.SupportsIndex) -> complex
E       
E       Invoked with: <test_builtin_casters.test_complex_cast.<locals>.Index object at 0x000000001170bec0>

Complex    = <class 'test_builtin_casters.test_complex_cast.<locals>.Complex'>
Float      = <class 'test_builtin_casters.test_complex_cast.<locals>.Float'>
Index      = <class 'test_builtin_casters.test_complex_cast.<locals>.Index'>
Int        = <class 'test_builtin_casters.test_complex_cast.<locals>.Int'>
cant_convert = <function test_complex_cast.<locals>.cant_convert at 0x00007f349fb85ce0>
convert    = <builtin_function_or_method object at 0x000000000d88aa60>
doc        = <conftest.SanitizedString object at 0x0000000011743210>
noconvert  = <builtin_function_or_method object at 0x000000000d88aaa0>
requires_conversion = <function test_complex_cast.<locals>.requires_conversion at 0x00007f349fb85c40>

../../tests/test_builtin_casters.py:529: TypeError

[InvincibleRMC]

Ah yeah that makes sense. Copying the back porting of __index__ to old versions of pypy.

[rwgk]

OK, I'll get Cursor going on this.

(Peeling the PR apart like this is a great way for me to get my head around it. I wasn't able to follow the individual commits on 5879; I'm operating on a tiny time budget.)

[rwgk]

After commit 6267614 all tests passed. Merging. Thanks @InvincibleRMC!

I'll try to use Cursor to update 5879, hoping it'll be able to deal with any merge conflicts.