Types for complex.__new__ should be any numeric type

[smlerman]

The types for the arguments to complex.__new__ should be any numeric type, not just float.

c1 = complex(1, 2)
c2 = complex(1, c1)

This code is valid, but the second line reports an error that complex is incompatible with float.

typeshed/stdlib/builtins.pyi

Line 368 in f550c24

def __new__(cls: type[Self], real: float = ..., imag: float = ...) -> Self: ...

[AlexWaygood]

The docs for complex state:

Each argument may be any numeric type (including complex).

So your analysis seems correct. PR welcome!

[smlerman]

I tried changing float to numbers.Number, but I got errors that int, float, and complex are all incompatible. Is that expected? If so, changing it to float | complex seems to work correctly.

[AlexWaygood]

I tried changing float to numbers.Number, but I got errors that int, float, and complex are all incompatible. Is that expected? If so, changing it to float | complex seems to work correctly.

Yeah, that's expected (see the resources I laid out here for why numbers.Number isn't much use when it comes to static typing).

For the first argument, the docs state:

For a general Python object x, complex(x) delegates to x.__complex__(). If __complex__() is not defined then it falls back to __float__(). If __float__() is not defined then it falls back to __index__().

That means that the first argument should be complex | SupportsComplex | SupportsFloat | SupportsIndex.

For the second argument, it seems complex or anything with a __float__ method will do, so the argument should be complex | SupportsFloat:

>>> class Foo:
...   def __index__(self):
...     return 5
...     
>>> complex(1, Foo())
Traceback (most recent call last):
  File "<string>", line 1, in <module>
TypeError: complex() second argument must be a number, not 'Foo'
>>> class Foo:
...   def __complex__(self):
...     return 5
...     
>>> complex(1, Foo())
Traceback (most recent call last):
  File "<string>", line 1, in <module>
TypeError: complex() second argument must be a number, not 'Foo'
>>> class Foo:
...   def __float__(self):
...     return 5
...     
>>> complex(1, Foo())
(1+5j)

[AlexWaygood]

SupportsComplex and SupportsFloat are both importable from typing; SupportsIndex is importable from typing_extensions (can't import it from typing as typeshed supports Python 3.7 and SupportsIndex was only added in 3.8).

[AlexWaygood]

For the first argument, the docs state:

For a general Python object x, complex(x) delegates to x.__complex__(). If __complex__() is not defined then it falls back to __float__(). If __float__() is not defined then it falls back to __index__().

That means that the first argument should be complex | SupportsComplex | SupportsFloat | SupportsIndex.

Actually, looks like that's only the case for when you only provide a single argument to complex(). If you provide two arguments, then the first argument should also be complex | SupportsFloat.

[AlexWaygood]

This is more complicated than I realised; I can prepare the PR if you like :)

[smlerman]

I was going to ask what Python version you were using, because I was getting different results with your code, then I saw your comment about using 3.7.

There's already a one-parameter overload declared, which has str | SupportsComplex | SupportsIndex | complex (should maybe add SupportsFloat; I can test it out), so I think I'd only have to fix the two-parameter overload.

[smlerman]

complex(1, FooSupportsIndex()) only works in 3.8+. Is it worth putting in a version check with different declarations for <3.8 and >=3.8?

[AlexWaygood]

complex(1, FooSupportsIndex()) only works in 3.8+. Is it worth putting in a version check with different declarations for <3.8 and >=3.8?

Yes, absolutely! And, good catch!

[smlerman]

python_typeshed_8440.py.txt
Attached a script for checking everything

[smlerman]

For some bizarre reason, Python gives TypeError: complex() second argument must be a number, not 'FooComplex' for a SupportsComplex object, even though a complex works fine. This is on all versions up to 3.10.

[AlexWaygood]

For some bizarre reason, Python gives TypeError: complex() second argument must be a number, not 'FooComplex' for a SupportsComplex object, even though a complex works fine. This is on all versions up to 3.10.

Some aspects of Python's data model are a little rough around the edges :)

[smlerman]

I assume the declaration here should match Python's actual behavior, and not what it probably should be?