Closed
Description
The sphinx docs says:
class complex(real=0, imag=0)
[...]
Return a complex number with the value real + imag*1j or convert a string or number to a complex number.
[...]
The docstring (btw it doesn't mention a string as an argument):
>>> print(complex.__doc__)
Create a complex number from a real part and an optional imaginary part.
This is equivalent to (real + imag*1j) where imag defaults to 0.
That wrong, e.g.:
>>> complex(0.0, -0.0)
-0j
>>> 0.0 + (-0.0)*1j
0j
>>> complex(-0.0, -0.0)
(-0-0j)
>>> -0.0 + (-0.0)*1j
(-0+0j)
>>> complex(-0.0, 0.0)
(-0+0j)
>>> -0.0 + 0.0*1j
0jHere is an attempt (patch) to solve, let me know if this is worth a PR:
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index d9974c6350..78b85658ef 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -373,8 +373,8 @@ are always available. They are listed here in alphabetical order.
.. class:: complex(real=0, imag=0)
complex(string)
- Return a complex number with the value *real* + *imag*\*1j or convert a string
- or number to a complex number. If the first parameter is a string, it will
+ Create a complex number from a real part and an optional imaginary part
+ or convert a string to a complex number. If the first parameter is a string, it will
be interpreted as a complex number and the function must be called without a
second parameter. The second parameter can never be a string. Each argument
may be any numeric type (including complex). If *imag* is omitted, it
diff --git a/Objects/complexobject.c b/Objects/complexobject.c
index 0e96f54584..336b703233 100644
--- a/Objects/complexobject.c
+++ b/Objects/complexobject.c
@@ -886,9 +886,8 @@ complex.__new__ as complex_new
real as r: object(c_default="NULL") = 0
imag as i: object(c_default="NULL") = 0
-Create a complex number from a real part and an optional imaginary part.
-
-This is equivalent to (real + imag*1j) where imag defaults to 0.
+Create a complex number from a real part and an optional imaginary part
+or convert a string to a complex number.
[clinic start generated code]*/
static PyObject *Edit:
Another instance of this issue is in the cmath docs:
A Python complex number ``z`` is stored internally using *rectangular*
or *Cartesian* coordinates. It is completely determined by its *real
part* ``z.real`` and its *imaginary part* ``z.imag``. In other
words::
z == z.real + z.imag*1jE.g.:
>>> from cmath import inf
>>> complex(0.0, inf)
infj
>>> 0.0 + inf*1j
(nan+infj)Linked PRs
- gh-109218: Deprecate weird cases in the complex() constructor #119620
- gh-109218: Refactor tests for the complex() constructor #119635
- gh-109218: Improve documentation for the complex() constructor #119687
- [3.13] gh-109218: Refactor tests for the complex() constructor (GH-119635) #119795
- [3.12] gh-109218: Refactor tests for the complex() constructor (GH-119635) #119796
- [3.13] gh-109218: Improve documentation for the complex() constructor (GH-119687) #119803
- [3.12] gh-109218: Improve documentation for the complex() constructor (GH-119687) #119805