Imaginary type and IEC 60559-compatible complex arithmetic

[skirpichev]

"Generally, mixed-mode arithmetic combining real and complex variables should be performed directly, not by first coercing the real to complex, lest the sign of zero be rendered uninformative; the same goes for combinations of pure imaginary quantities with complex variables." (c) Kahan, W: Branch cuts for complex elementary functions.

That's why C standards since C99 introduce imaginary types. This patch proposes similar extension to the Python language:

• Added a new subtype (imaginary) of the complex type. New type has few overloaded methods (conjugate() and __getnewargs__()).
• Complex and imaginary types implement IEC 60559-compatible complex arithmetic (as specified by C11 Annex G).
• Imaginary literals now produce instances of imaginary type.
• cmath.infj/nanj were changed to be of imaginary type.
• Modules ast, code, copy, marshal got support for imaginary type.
• Few tests (test_fractions.py, test_socket.py and test_str.py) adapted to use complex, instead of imaginary literals.
• Print dot for signed zeros in the real part of repr(complex).
• repr(complex) also now prints real part even if it's zero.

Lets consider (actually interrelated) problems, shown for unpatched code, which will be solved on this way.

1. First, new code allows to use complex arithmetic for implementation of mathematical functions without special "corner cases". Take the inverse tangent as an example:

>>> z = complex(-0.0, 2)
>>> cmath.atan(z)
(-1.5707963267948966+0.5493061443340549j)
>>> 1j*(cmath.log(1 - 1j*z) - cmath.log(1 + 1j*z))/2  # real part was wrong
(1.5707963267948966+0.5493061443340549j)

2. Previously, we have only unsigned imaginary literals with the following semantics:

±a±bj = complex(±float(a), 0.0) ± complex(0.0, float(b))

While this behaviour was well documented, most users would expect instead here:

±a±bj = complex(±float(a), ±float(b))

i.e. that it follows to the rectangular notation for complex numbers.

For example:

>>> -0.0+1j  # now (-0.0+1j)
1j
>>> float('inf')*1j  # now infj
(nan+infj)

3. The eval(repr(x)) == x invariant was broken for the complex type. Below are simple examples with signed zero:

>>> complex(-0.0, 1.0)  # also note funny signed integer zero below
(-0+1j)
>>> -0+1j
1j
>>> complex(0.0, -cmath.inf)
-infj
>>> -cmath.infj
(-0-infj)

See also ISO/IEC 9899:2011, Annex G and Rationale for C99 and Augmenting a Programming Language with Complex Arithmetic.

---

📚 Documentation preview 📚: https://cpython-previews--1.org.readthedocs.build/