René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Invalid \"equivalents\" of the complex type constructor in docs","articleBody":"The sphinx docs says:\r\n```\r\nclass complex(real=0, imag=0)\r\n[...]\r\nReturn a complex number with the value real + imag*1j or convert a string or number to a complex number.\r\n[...]\r\n```\r\nThe docstring (btw it doesn't mention a string as an argument):\r\n```\r\n\u003e\u003e\u003e print(complex.__doc__)\r\nCreate a complex number from a real part and an optional imaginary part.\r\n\r\nThis is equivalent to (real + imag*1j) where imag defaults to 0.\r\n```\r\n\r\nThat wrong, e.g.:\r\n```pycon\r\n\u003e\u003e\u003e complex(0.0, -0.0)\r\n-0j\r\n\u003e\u003e\u003e 0.0 + (-0.0)*1j\r\n0j\r\n\u003e\u003e\u003e complex(-0.0, -0.0)\r\n(-0-0j)\r\n\u003e\u003e\u003e -0.0 + (-0.0)*1j\r\n(-0+0j)\r\n\u003e\u003e\u003e complex(-0.0, 0.0)\r\n(-0+0j)\r\n\u003e\u003e\u003e -0.0 + 0.0*1j\r\n0j\r\n```\r\n\r\n\u003cdetails\u003e\r\n\u003csummary\u003eHere is an attempt (patch) to solve, let me know if this is worth a PR:\u003c/summary\u003e\r\n\r\n```diff\r\ndiff --git a/Doc/library/functions.rst b/Doc/library/functions.rst\r\nindex d9974c6350..78b85658ef 100644\r\n--- a/Doc/library/functions.rst\r\n+++ b/Doc/library/functions.rst\r\n@@ -373,8 +373,8 @@ are always available.  They are listed here in alphabetical order.\r\n .. class:: complex(real=0, imag=0)\r\n            complex(string)\r\n\r\n-   Return a complex number with the value *real* + *imag*\\*1j or convert a string\r\n-   or number to a complex number.  If the first parameter is a string, it will\r\n+   Create a complex number from a real part and an optional imaginary part\r\n+   or convert a string to a complex number.  If the first parameter is a string, it will\r\n    be interpreted as a complex number and the function must be called without a\r\n    second parameter.  The second parameter can never be a string. Each argument\r\n    may be any numeric type (including complex).  If *imag* is omitted, it\r\ndiff --git a/Objects/complexobject.c b/Objects/complexobject.c\r\nindex 0e96f54584..336b703233 100644\r\n--- a/Objects/complexobject.c\r\n+++ b/Objects/complexobject.c\r\n@@ -886,9 +886,8 @@ complex.__new__ as complex_new\r\n     real as r: object(c_default=\"NULL\") = 0\r\n     imag as i: object(c_default=\"NULL\") = 0\r\n\r\n-Create a complex number from a real part and an optional imaginary part.\r\n-\r\n-This is equivalent to (real + imag*1j) where imag defaults to 0.\r\n+Create a complex number from a real part and an optional imaginary part\r\n+or convert a string to a complex number.\r\n [clinic start generated code]*/\r\n\r\n static PyObject *\r\n```\r\n\u003c/details\u003e\r\n\r\n**Edit**:\r\nAnother instance of this issue is in the [cmath docs](https://docs.python.org/3/library/cmath.html#conversions-to-and-from-polar-coordinates):\r\n```rst\r\nA Python complex number ``z`` is stored internally using *rectangular*\r\nor *Cartesian* coordinates.  It is completely determined by its *real\r\npart* ``z.real`` and its *imaginary part* ``z.imag``.  In other\r\nwords::\r\n\r\n   z == z.real + z.imag*1j\r\n```\r\nE.g.:\r\n```pycon\r\n\u003e\u003e\u003e from cmath import inf\r\n\u003e\u003e\u003e complex(0.0, inf)\r\ninfj\r\n\u003e\u003e\u003e 0.0 + inf*1j\r\n(nan+infj)\r\n```\n\n\u003c!-- gh-linked-prs --\u003e\n### Linked PRs\n* gh-119620\n* gh-119635\n* gh-119687\n* gh-119795\n* gh-119796\n* gh-119803\n* gh-119805\n\u003c!-- /gh-linked-prs --\u003e\n","author":{"url":"https://github.com/skirpichev","@type":"Person","name":"skirpichev"},"datePublished":"2023-09-10T08:47:17.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":11},"url":"https://github.com/109218/cpython/issues/109218"}