GeezerVison

This is a lot of detail for the second paragraph. Users might find it easier to understand how to create complex numbers if the REPL examples came before this full specification

I followed the example of float() which has even more detailed description of the input format in the second paragraph. I merged it with a note about whitespaces, so all information related to parsing string to complex is now in one place.

I would be happy to make the description shorter, even if less detailed. Do you have any suggestions?

Fair enough, though I would honestly also be inclined to move the float() examples higher up as well. I think it's probably correct to provide a full specification here; I just worry that it could overwhelmingly technical for Python beginners, who will probably learn best by looking at the examples.

In any event, I don't have a strong opinion; I'm happy to defer to you and Mark

I think @AlexWaygood has a good point here: for readability, it would be nice to see just three examples (one for each of the three signatures) following the initial "Convert a single string or number to a complex number, or ..." line, before we get into the heavy detail of exactly which strings are permitted.

I have moved examples for complex() and float() and added examples for int().

I think @AlexWaygood has a good point here: for readability, it would be nice to see just three examples (one for each of the three signatures) following the initial "Convert a single string or number to a complex number, or ..." line, before we get into the heavy detail of exactly which strings are permitted.

Presumably this will mention the deprecation if/when #119620 is merged? Or is the plan to remove the mention of allowing complex altogether?

I'd be tempted to not even document this (mis)feature, on the basis that people who already know about it already know about it, and people who don't know about it shouldn't start using it.

The plan was to leave this until the end of the deprecation period.

I would be happy to remove this, but then we will receive another reports about wrong documentation or behavior. The old real + imag*1j was more correct for input with finite components (and ignoring corner cases with negative zero).

"Each argument may be any numeric type (including complex)." is already in the current documentation, so it is late to hide this without also changing the behavior.

Fair enough.

Best we can do is to put the deprecation note as close to this sentence, as possible:)

I suggest we reorder some of these so that the stranger ones come below the more common ones:

But this mixes examples for three fundamentally different roles: string parsing, numerical conversion and construction from components.

It wasn't immediately obvious to me that that was the reason behind your ordering, and I doubt it would be obvious to beginners either, which is why I suggested a different order of "most useful to least useful". But again, I don't have a strong opinion; your PR is certainly fine as-is :-)

I would also expect the most useful to the least useful examples even though it mixes the parsers.

It may look a bit nicer, but I don't know whether you want a smaller heading here.

Looking how it is used in Doc/library/asyncio-api-index.rst, I do not think that it is appropriate here.

I would also expect the most useful to the least useful examples even though it mixes the parsers.

Nit: this "j" vs "J" happens in several places. You could just mention (as in the float constructor) that parsing is case-insensitive:

>>> complex('(InFiNITY+1j)')
(inf+1j)

But "e" and "E" are mentioned separately in the float grammar. We can say also that all whitespaces except the leading and trailing are not acceptable, but I think it will be clearer to be a little more verbose here.

Looking how it is used in Doc/library/asyncio-api-index.rst, I do not think that it is appropriate here.

But "e" and "E" are mentioned separately in the float grammar. We can say also that all whitespaces except the leading and trailing are not acceptable, but I think it will be clearer to be a little more verbose here.