gh-109218: Improve documentation for the complex() constructor #119687

serhiy-storchaka · 2024-05-28T20:14:54Z

Issue: Invalid "equivalents" of the complex type constructor in docs #109218

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

skirpichev

LGTM

Few remarks:
0) This touch also bool, float and int constructors; changes looks fine, but at least the commit message could be more verbose and mention that.

Should be merged before gh-109218: Deprecate weird cases in the complex() constructor #119620
cmath has yet another instance of z == z.real + z.imag*1j invariant, mentioned in the issue thread. I think this should be fixed too, probably just by removing that line.

Doc/library/functions.rst

AlexWaygood · 2024-05-29T12:23:22Z

Doc/library/functions.rst

+   If the argument is a string, it should contain a decimal number, optionally
+   preceded by a sign, and optionally followed by the ``j`` or ``J`` suffix,
+   or a pair of decimal numbers, optionally preceded by a sign, separated by
+   the ``+`` or ``-`` operator, and followed by the ``j`` or ``J`` suffix.
+   A string representing a NaN (not-a-number), or infinity is acceptable
+   in place of a decimal number, like in :func:`float`.
+   The string can optionally be surrounded by whitespaces and the round
+   parenthesis ``(`` and ``)``, which are ignored.
+   The string must not contain whitespace between ``+``, ``-``, the ``j`` or
+   ``J`` suffix, and the decimal number.  For example, ``complex('1+2j')`` is fine, but
+   ``complex('1 + 2j')`` raises :exc:`ValueError`.


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().

Doc/library/functions.rst

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

mdickinson

LGTM.

This is very much a judgement call and personal opinion, and I don't know how well it fits with the general direction of our documentation, but I do think it would be nice to have a small number of examples immediately following the initial "Convert a single string ..." doc line.

Doc/library/functions.rst

mdickinson · 2024-05-29T16:06:28Z

Doc/library/functions.rst

+   If the argument is a string, it should contain a decimal number, optionally
+   preceded by a sign, and optionally followed by the ``j`` or ``J`` suffix,
+   or a pair of decimal numbers, optionally preceded by a sign, separated by
+   the ``+`` or ``-`` operator, and followed by the ``j`` or ``J`` suffix.
+   A string representing a NaN (not-a-number), or infinity is acceptable
+   in place of a decimal number, like in :func:`float`.
+   The string can optionally be surrounded by whitespaces and the round
+   parenthesis ``(`` and ``)``, which are ignored.
+   The string must not contain whitespace between ``+``, ``-``, the ``j`` or
+   ``J`` suffix, and the decimal number.  For example, ``complex('1+2j')`` is fine, but
+   ``complex('1 + 2j')`` raises :exc:`ValueError`.


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.

mdickinson · 2024-05-29T16:11:09Z

Doc/library/functions.rst

+   If both arguments are complex numbers, return a complex number with the real
+   component ``real.real-imag.imag`` and the imaginary component
+   ``real.imag+imag.real``.


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:)

Doc/library/functions.rst

AlexWaygood · 2024-05-29T17:38:22Z

Doc/library/functions.rst

+      >>> complex('+1.23')
+      (1.23+0j)
+      >>> complex('-4.5j')
+      -4.5j
+      >>> complex('-1.23+4.5j')
+      (-1.23+4.5j)
+      >>> complex('\t( -1.23+4.5J )\n')
+      (-1.23+4.5j)
+      >>> complex('-Infinity+NaNj')
+      (-inf+nanj)
+      >>> complex(1.23)
+      (1.23+0j)
+      >>> complex(imag=-4.5)
+      -4.5j
+      >>> complex(-1.23, 4.5)
+      (-1.23+4.5j)


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

Suggested change

>>> complex('+1.23')

(1.23+0j)

>>> complex('-4.5j')

-4.5j

>>> complex('-1.23+4.5j')

(-1.23+4.5j)

>>> complex('\t( -1.23+4.5J )\n')

(-1.23+4.5j)

>>> complex('-Infinity+NaNj')

(-inf+nanj)

>>> complex(1.23)

(1.23+0j)

>>> complex(imag=-4.5)

-4.5j

>>> complex(-1.23, 4.5)

(-1.23+4.5j)

>>> complex('+1.23')

(1.23+0j)

>>> complex('-4.5j')

-4.5j

>>> complex('-1.23+4.5j')

(-1.23+4.5j)

>>> complex(-1.23, 4.5)

(-1.23+4.5j)

>>> complex(1.23)

(1.23+0j)

>>> complex(imag=-4.5)

-4.5j

>>> complex('\t( -1.23+4.5J )\n')

(-1.23+4.5j)

>>> complex('-Infinity+NaNj')

(-inf+nanj)

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.

picnixz · 2024-05-30T14:15:42Z

Doc/library/functions.rst

+   Convert a single string or number to a complex number, or create a
+   complex number from real and imaginary parts.
+
+   Examples:


Suggested change

Examples:

.. rubric:: Examples

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.

picnixz · 2024-05-30T14:16:59Z

Doc/library/functions.rst

+      >>> complex('+1.23')
+      (1.23+0j)
+      >>> complex('-4.5j')
+      -4.5j
+      >>> complex('-1.23+4.5j')
+      (-1.23+4.5j)
+      >>> complex('\t( -1.23+4.5J )\n')
+      (-1.23+4.5j)
+      >>> complex('-Infinity+NaNj')
+      (-inf+nanj)
+      >>> complex(1.23)
+      (1.23+0j)
+      >>> complex(imag=-4.5)
+      -4.5j
+      >>> complex(-1.23, 4.5)
+      (-1.23+4.5j)


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

Doc/library/functions.rst

skirpichev · 2024-05-30T14:36:10Z

Doc/library/functions.rst

+   The string can optionally be surrounded by whitespaces and the round
+   parenthesis ``'('`` and ``')'``, which are ignored.
+   The string must not contain whitespace between ``'+'``, ``'-'``, the
+   ``'j'`` or ``'J'`` suffix, and the decimal number.


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.

serhiy-storchaka · 2024-05-30T19:00:57Z

Doc/library/functions.rst

+   Convert a single string or number to a complex number, or create a
+   complex number from real and imaginary parts.
+
+   Examples:


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

serhiy-storchaka · 2024-05-30T19:11:39Z

Doc/library/functions.rst

+   The string can optionally be surrounded by whitespaces and the round
+   parenthesis ``'('`` and ``')'``, which are ignored.
+   The string must not contain whitespace between ``'+'``, ``'-'``, the
+   ``'j'`` or ``'J'`` suffix, and the decimal number.


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.

Doc/library/functions.rst

Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>

Doc/library/functions.rst

miss-islington-app · 2024-05-30T20:20:11Z

Thanks @serhiy-storchaka for the PR 🌮🎉.. I'm working now to backport this PR to: 3.12, 3.13.
🐍🍒⛏🤖

…ythonGH-119687) * Remove the equivalence with real+imag*1j which can be incorrect in corner cases (non-finite numbers, the sign of zeroes). * Separately document the three roles of the constructor: parsing a string, converting a number, and constructing a complex from components. * Document positional-only parameters of complex(), float(), int() and bool() as positional-only. * Add examples for complex() and int(). * Specify the grammar of the string for complex(). * Improve the grammar of the string for float(). * Describe more explicitly the behavior when real and/or imag arguments are complex numbers. (This will be deprecated in future.) (cherry picked from commit ec1ba26) Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>

miss-islington-app · 2024-05-30T20:20:19Z

Sorry, @serhiy-storchaka, I could not cleanly backport this to 3.12 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker ec1ba264607b2b7b98d2602f5536a1d02981efc6 3.12

bedevere-app · 2024-05-30T20:20:23Z

GH-119803 is a backport of this pull request to the 3.13 branch.

…ructor (pythonGH-119687) * Remove the equivalence with real+imag*1j which can be incorrect in corner cases (non-finite numbers, the sign of zeroes). * Separately document the three roles of the constructor: parsing a string, converting a number, and constructing a complex from components. * Document positional-only parameters of complex(), float(), int() and bool() as positional-only. * Add examples for complex() and int(). * Specify the grammar of the string for complex(). * Improve the grammar of the string for float(). * Describe more explicitly the behavior when real and/or imag arguments are complex numbers. (This will be deprecated in future.) (cherry picked from commit ec1ba26) Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>

bedevere-app · 2024-05-30T20:27:44Z

GH-119805 is a backport of this pull request to the 3.12 branch.

…GH-119687) (GH-119803) * Remove the equivalence with real+imag*1j which can be incorrect in corner cases (non-finite numbers, the sign of zeroes). * Separately document the three roles of the constructor: parsing a string, converting a number, and constructing a complex from components. * Document positional-only parameters of complex(), float(), int() and bool() as positional-only. * Add examples for complex() and int(). * Specify the grammar of the string for complex(). * Improve the grammar of the string for float(). * Describe more explicitly the behavior when real and/or imag arguments are complex numbers. (This will be deprecated in future.) (cherry picked from commit ec1ba26) Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>

…GH-119687) (ПР-119805) * Remove the equivalence with real+imag*1j which can be incorrect in corner cases (non-finite numbers, the sign of zeroes). * Separately document the three roles of the constructor: parsing a string, converting a number, and constructing a complex from components. * Document positional-only parameters of complex(), float(), int() and bool() as positional-only. * Add examples for complex() and int(). * Specify the grammar of the string for complex(). * Improve the grammar of the string for float(). * Describe more explicitly the behavior when real and/or imag arguments are complex numbers. (This will be deprecated in future.) (cherry picked from commit ec1ba26)

…ythonGH-119687) * Remove the equivalence with real+imag*1j which can be incorrect in corner cases (non-finite numbers, the sign of zeroes). * Separately document the three roles of the constructor: parsing a string, converting a number, and constructing a complex from components. * Document positional-only parameters of complex(), float(), int() and bool() as positional-only. * Add examples for complex() and int(). * Specify the grammar of the string for complex(). * Improve the grammar of the string for float(). * Describe more explicitly the behavior when real and/or imag arguments are complex numbers. (This will be deprecated in future.)

pythongh-109218: Improve documentation for the complex() constructor

e67380d

serhiy-storchaka added docs Documentation in the Doc dir skip news needs backport to 3.12 only security fixes needs backport to 3.13 bugs and security fixes labels May 28, 2024

serhiy-storchaka requested a review from mdickinson May 28, 2024 20:14

bedevere-app bot added the awaiting core review label May 28, 2024

bedevere-app bot mentioned this pull request May 28, 2024

Invalid "equivalents" of the complex type constructor in docs #109218

Closed

skirpichev approved these changes May 29, 2024

View reviewed changes

Fix also cmath.rst.

94deb98

AlexWaygood reviewed May 29, 2024

View reviewed changes

Apply suggestions from code review

7182597

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

mdickinson approved these changes May 29, 2024

View reviewed changes

bedevere-app bot added awaiting merge and removed awaiting core review labels May 29, 2024

Move examples for complex() and float(). Add examples for int().

63ebe03

AlexWaygood approved these changes May 29, 2024

View reviewed changes

serhiy-storchaka added 2 commits May 29, 2024 21:29

Merge branch 'main' into complex-constructor-docs

28bae65

Add an example for truncation.

944dc6c

serhiy-storchaka mentioned this pull request May 30, 2024

gh-119740: Remove deprecated trunc delegation #119743

Merged

Rewrite the description of the complex format and use productionlist.

97a9e00

picnixz reviewed May 30, 2024

View reviewed changes

skirpichev reviewed May 30, 2024

View reviewed changes

serhiy-storchaka commented May 30, 2024

View reviewed changes

Apply suggestions from code review

d77833c

Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>

serhiy-storchaka enabled auto-merge (squash) May 30, 2024 19:26

Update Doc/library/functions.rst

9664b6a

Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>

serhiy-storchaka commented May 30, 2024

View reviewed changes

Doc/library/functions.rst Outdated Show resolved Hide resolved

Update Doc/library/functions.rst

c23c659

serhiy-storchaka merged commit ec1ba26 into python:main May 30, 2024
36 checks passed

bedevere-app bot removed the awaiting merge label May 30, 2024

miss-islington-app bot assigned serhiy-storchaka May 30, 2024

bedevere-app bot removed the needs backport to 3.13 bugs and security fixes label May 30, 2024

serhiy-storchaka deleted the complex-constructor-docs branch May 30, 2024 20:25

bedevere-app bot removed the needs backport to 3.12 only security fixes label May 30, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

gh-109218: Improve documentation for the complex() constructor #119687

gh-109218: Improve documentation for the complex() constructor #119687

serhiy-storchaka commented May 28, 2024 •

edited by github-actions bot

Loading

skirpichev left a comment •

edited

Loading

AlexWaygood May 29, 2024

serhiy-storchaka May 29, 2024

AlexWaygood May 29, 2024

mdickinson May 29, 2024

serhiy-storchaka May 29, 2024

mdickinson left a comment

mdickinson May 29, 2024

mdickinson May 29, 2024

serhiy-storchaka May 29, 2024

mdickinson May 29, 2024

skirpichev May 30, 2024

AlexWaygood May 29, 2024

serhiy-storchaka May 29, 2024

AlexWaygood May 30, 2024

picnixz May 30, 2024

picnixz May 30, 2024

serhiy-storchaka May 30, 2024

picnixz May 30, 2024

skirpichev May 30, 2024

serhiy-storchaka May 30, 2024

serhiy-storchaka May 30, 2024

serhiy-storchaka May 30, 2024

miss-islington-app bot commented May 30, 2024

miss-islington-app bot commented May 30, 2024

bedevere-app bot commented May 30, 2024

bedevere-app bot commented May 30, 2024

gh-109218: Improve documentation for the complex() constructor #119687

gh-109218: Improve documentation for the complex() constructor #119687

Conversation

serhiy-storchaka commented May 28, 2024 • edited by github-actions bot Loading

skirpichev left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mdickinson left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

miss-islington-app bot commented May 30, 2024

miss-islington-app bot commented May 30, 2024

bedevere-app bot commented May 30, 2024

bedevere-app bot commented May 30, 2024

serhiy-storchaka commented May 28, 2024 •

edited by github-actions bot

Loading

skirpichev left a comment •

edited

Loading