Thanks to visit codestin.com
Credit goes to github.com

Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 10 commits into from
May 30, 2024
Merged

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

Changes from 1 commit
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
e67380d
gh-109218: Improve documentation for the complex() constructor
serhiy-storchaka May 28, 2024
94deb98
Fix also cmath.rst.
serhiy-storchaka May 29, 2024
7182597
Apply suggestions from code review
serhiy-storchaka May 29, 2024
63ebe03
Move examples for complex() and float(). Add examples for int().
serhiy-storchaka May 29, 2024
28bae65
Merge branch 'main' into complex-constructor-docs
serhiy-storchaka May 29, 2024
944dc6c
Add an example for truncation.
serhiy-storchaka May 29, 2024
97a9e00
Rewrite the description of the complex format and use productionlist.
serhiy-storchaka May 30, 2024
d77833c
Apply suggestions from code review
serhiy-storchaka May 30, 2024
9664b6a
Update Doc/library/functions.rst
serhiy-storchaka May 30, 2024
c23c659
Update Doc/library/functions.rst
serhiy-storchaka May 30, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Move examples for complex() and float(). Add examples for int().
  • Loading branch information
@serhiy-storchaka
serhiy-storchaka committed May 29, 2024
commit 63ebe03bcccc4f91a5cd282f92df629aa195a7ad
85 changes: 51 additions & 34 deletions Doc/library/functions.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -379,6 +379,27 @@ are always available. They are listed here in alphabetical order.
Convert a single string or number to a complex number, or create a
complex number from real and imaginary parts.

Examples:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Examples:
.. rubric:: Examples

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

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


.. doctest::

>>> 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)
Comment on lines +386 to +401
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


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
Expand Down Expand Up @@ -412,27 +433,6 @@ are always available. They are listed here in alphabetical order.

If all arguments are omitted, returns ``0j``.

Examples:

.. doctest::

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

The complex type is described in :ref:`typesnumeric`.

.. versionchanged:: 3.6
Expand Down Expand Up @@ -729,6 +729,21 @@ are always available. They are listed here in alphabetical order.

Return a floating point number constructed from a number or a string.

Examples:

.. doctest::

>>> float('+1.23')
1.23
>>> float(' -12345\n')
-12345.0
>>> float('1e-003')
0.001
>>> float('+1E6')
1000000.0
>>> float('-Infinity')
-inf

If the argument is a string, it should contain a decimal number, optionally
preceded by a sign, and optionally embedded in whitespace. The optional
sign may be ``'+'`` or ``'-'``; a ``'+'`` sign has no effect on the value
Expand Down Expand Up @@ -762,19 +777,6 @@ are always available. They are listed here in alphabetical order.

If no argument is given, ``0.0`` is returned.

Examples::

>>> float('+1.23')
1.23
>>> float(' -12345\n')
-12345.0
>>> float('1e-003')
0.001
>>> float('+1E6')
1000000.0
>>> float('-Infinity')
-inf

The float type is described in :ref:`typesnumeric`.

.. versionchanged:: 3.6
Expand Down Expand Up @@ -971,6 +973,21 @@ are always available. They are listed here in alphabetical order.
Return an integer object constructed from a number or a string, or return
``0`` if no arguments are given.

Examples:

.. doctest::

>>> int('123')
123
>>> int(' -12_345\n')
-12345
>>> int('FACE', 16)
64206
>>> int('0xface', 0)
64206
>>> int('01110011', base=2)
115

If the argument defines :meth:`~object.__int__`,
``int(x)`` returns ``x.__int__()``. If the argument defines :meth:`~object.__index__`,
it returns ``x.__index__()``. If the argument defines :meth:`~object.__trunc__`,
Expand Down