From e67380d1e4444f8bba91311a9508fdc6b3cadf12 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Tue, 28 May 2024 22:34:32 +0300 Subject: [PATCH 1/9] gh-109218: Improve documentation for the complex() constructor --- Doc/library/functions.rst | 105 +++++++++++++++++++++---------- Objects/clinic/complexobject.c.h | 9 ++- Objects/complexobject.c | 9 ++- 3 files changed, 84 insertions(+), 39 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index cb9b650badcfbd..b39d7d434da044 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -141,10 +141,11 @@ are always available. They are listed here in alphabetical order. See also :func:`format` for more information. -.. class:: bool(x=False) +.. class:: bool(object=False, /) - Return a Boolean value, i.e. one of ``True`` or ``False``. *x* is converted - using the standard :ref:`truth testing procedure `. If *x* is false + Return a Boolean value, i.e. one of ``True`` or ``False``. The argument + is converted using the standard :ref:`truth testing procedure `. + If the argument is false or omitted, this returns ``False``; otherwise, it returns ``True``. The :class:`bool` class is a subclass of :class:`int` (see :ref:`typesnumeric`). It cannot be subclassed further. Its only instances are ``False`` and @@ -153,7 +154,7 @@ are always available. They are listed here in alphabetical order. .. index:: pair: Boolean; type .. versionchanged:: 3.7 - *x* is now a positional-only parameter. + The parameter is now positional-only. .. function:: breakpoint(*args, **kws) @@ -371,29 +372,64 @@ are always available. They are listed here in alphabetical order. support for top-level ``await``, ``async for``, and ``async with``. -.. class:: complex(real=0, imag=0) - complex(string) +.. class:: complex(number=0, /) + complex(string, /) + 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. 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 - defaults to zero and the constructor serves as a numeric conversion like - :class:`int` and :class:`float`. If both arguments are omitted, returns - ``0j``. + Convert a string or a number to a complex number or create a complex number + from the real and imaginary parts. + 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`. + + If the argument is a number, the constructor serves as a numeric + conversion like :class:`int` and :class:`float`. For a general Python object ``x``, ``complex(x)`` delegates to - ``x.__complex__()``. If :meth:`~object.__complex__` is not defined then it falls back - to :meth:`~object.__float__`. If :meth:`!__float__` is not defined then it falls back + ``x.__complex__()``. + If :meth:`~object.__complex__` is not defined then it falls back + to :meth:`~object.__float__`. + If :meth:`!__float__` is not defined then it falls back to :meth:`~object.__index__`. - .. note:: + If two arguments are provided or keyword arguments are used, each argument + may be any numeric type (including complex). + If both arguments are real numbers, return a complex number with the real + component *real* and the imaginary component *imag*. + 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``. + If one of arguments is a real number, only its real component is used in + the above expressions. + + If all arguments are omitted, returns ``0j``. - When converting from a string, the string must not contain whitespace - around the central ``+`` or ``-`` operator. For example, - ``complex('1+2j')`` is fine, but ``complex('1 + 2j')`` raises - :exc:`ValueError`. + Examples:: + + >>> 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`. @@ -682,13 +718,14 @@ are always available. They are listed here in alphabetical order. elements of *iterable* for which *function* is false. -.. class:: float(x=0.0) +.. class:: float(number=0.0, /) + float(string, /) .. index:: single: NaN single: Infinity - Return a floating point number constructed from a number or string *x*. + Return a floating point number constructed from a number or a string. If the argument is a string, it should contain a decimal number, optionally preceded by a sign, and optionally embedded in whitespace. The optional @@ -742,7 +779,7 @@ are always available. They are listed here in alphabetical order. Grouping digits with underscores as in code literals is allowed. .. versionchanged:: 3.7 - *x* is now a positional-only parameter. + The parameter is now positional-only. .. versionchanged:: 3.8 Falls back to :meth:`~object.__index__` if :meth:`~object.__float__` is not defined. @@ -926,17 +963,19 @@ are always available. They are listed here in alphabetical order. with the result after successfully reading input. -.. class:: int(x=0) - int(x, base=10) +.. class:: int(number=0, /) + int(string, /, base=10) + + Return an integer object constructed from a number or a string, or return + ``0`` if no arguments are given. - Return an integer object constructed from a number or string *x*, or return - ``0`` if no arguments are given. If *x* defines :meth:`~object.__int__`, - ``int(x)`` returns ``x.__int__()``. If *x* defines :meth:`~object.__index__`, - it returns ``x.__index__()``. If *x* defines :meth:`~object.__trunc__`, + 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__`, it returns ``x.__trunc__()``. For floating point numbers, this truncates towards zero. - If *x* is not a number or if *base* is given, then *x* must be a string, + If the argument is not a number or if *base* is given, then it must be a string, :class:`bytes`, or :class:`bytearray` instance representing an integer in radix *base*. Optionally, the string can be preceded by ``+`` or ``-`` (with no space in between), have leading zeros, be surrounded by whitespace, @@ -966,7 +1005,7 @@ are always available. They are listed here in alphabetical order. Grouping digits with underscores as in code literals is allowed. .. versionchanged:: 3.7 - *x* is now a positional-only parameter. + The first parameter is now positional-only. .. versionchanged:: 3.8 Falls back to :meth:`~object.__index__` if :meth:`~object.__int__` is not defined. @@ -977,7 +1016,7 @@ are always available. They are listed here in alphabetical order. .. versionchanged:: 3.11 :class:`int` string inputs and string representations can be limited to help avoid denial of service attacks. A :exc:`ValueError` is raised when - the limit is exceeded while converting a string *x* to an :class:`int` or + the limit is exceeded while converting a string to an :class:`int` or when converting an :class:`int` into a string would exceed the limit. See the :ref:`integer string conversion length limitation ` documentation. diff --git a/Objects/clinic/complexobject.c.h b/Objects/clinic/complexobject.c.h index 49b50304021f7b..46c3b352562445 100644 --- a/Objects/clinic/complexobject.c.h +++ b/Objects/clinic/complexobject.c.h @@ -94,9 +94,12 @@ PyDoc_STRVAR(complex_new__doc__, "complex(real=0, imag=0)\n" "--\n" "\n" -"Create a complex number from a real part and an optional imaginary part.\n" +"Create a complex number from a string or numbers.\n" "\n" -"This is equivalent to (real + imag*1j) where imag defaults to 0."); +"If a string is given, parse it as a complex number.\n" +"If a single number is given, convert it to a complex number.\n" +"If the \'real\' or \'imag\' arguments are given, create a complex number\n" +"with the specified real and imaginary components."); static PyObject * complex_new_impl(PyTypeObject *type, PyObject *r, PyObject *i); @@ -157,4 +160,4 @@ complex_new(PyTypeObject *type, PyObject *args, PyObject *kwargs) exit: return return_value; } -/*[clinic end generated code: output=04e6261649967b30 input=a9049054013a1b77]*/ +/*[clinic end generated code: output=295ecfd71389d7fe input=a9049054013a1b77]*/ diff --git a/Objects/complexobject.c b/Objects/complexobject.c index d8b0e84da5df4a..1aa3960a1c63f9 100644 --- a/Objects/complexobject.c +++ b/Objects/complexobject.c @@ -911,14 +911,17 @@ 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. +Create a complex number from a string or numbers. -This is equivalent to (real + imag*1j) where imag defaults to 0. +If a string is given, parse it as a complex number. +If a single number is given, convert it to a complex number. +If the 'real' or 'imag' arguments are given, create a complex number +with the specified real and imaginary components. [clinic start generated code]*/ static PyObject * complex_new_impl(PyTypeObject *type, PyObject *r, PyObject *i) -/*[clinic end generated code: output=b6c7dd577b537dc1 input=f4c667f2596d4fd1]*/ +/*[clinic end generated code: output=b6c7dd577b537dc1 input=ff4268dc540958a4]*/ { PyObject *tmp; PyNumberMethods *nbr, *nbi = NULL; From 94deb98e21e5cb73d728053665fc0a0341ecf03d Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Wed, 29 May 2024 11:22:13 +0300 Subject: [PATCH 2/9] Fix also cmath.rst. --- Doc/library/cmath.rst | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/Doc/library/cmath.rst b/Doc/library/cmath.rst index 65e98e09ad7ae3..381a8332f4b187 100644 --- a/Doc/library/cmath.rst +++ b/Doc/library/cmath.rst @@ -43,10 +43,7 @@ Conversions to and from polar coordinates 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*1j +part* ``z.real`` and its *imaginary part* ``z.imag``. *Polar coordinates* give an alternative way to represent a complex number. In polar coordinates, a complex number *z* is defined by the @@ -90,7 +87,7 @@ rectangular coordinates to polar coordinates and back. .. function:: rect(r, phi) Return the complex number *x* with polar coordinates *r* and *phi*. - Equivalent to ``r * (math.cos(phi) + math.sin(phi)*1j)``. + Equivalent to ``complex(r * math.cos(phi), r * math.sin(phi))``. Power and logarithmic functions From 718259756c25f8b9a00464cff98c7857cc41c8e5 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Wed, 29 May 2024 15:37:35 +0300 Subject: [PATCH 3/9] Apply suggestions from code review Co-authored-by: Alex Waygood --- Doc/library/functions.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index b39d7d434da044..68ad4705a98149 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -376,8 +376,8 @@ are always available. They are listed here in alphabetical order. complex(string, /) complex(real=0, imag=0) - Convert a string or a number to a complex number or create a complex number - from the real and imaginary parts. + Convert a single string or number to a complex number, or create a + complex number from real and imaginary parts. 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, @@ -412,7 +412,9 @@ are always available. They are listed here in alphabetical order. If all arguments are omitted, returns ``0j``. - Examples:: + Examples: + + .. doctest:: >>> complex('+1.23') (1.23+0j) From 63ebe03bcccc4f91a5cd282f92df629aa195a7ad Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Wed, 29 May 2024 20:32:30 +0300 Subject: [PATCH 4/9] Move examples for complex() and float(). Add examples for int(). --- Doc/library/functions.rst | 85 +++++++++++++++++++++++---------------- 1 file changed, 51 insertions(+), 34 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 68ad4705a98149..bfbe008e23c668 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -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: + + .. 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) + 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 @@ -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 @@ -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 @@ -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 @@ -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__`, From 944dc6c5f96a086658ba980844ff8a9c1a45cde4 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Wed, 29 May 2024 21:30:50 +0300 Subject: [PATCH 5/9] Add an example for truncation. --- Doc/library/functions.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index bfbe008e23c668..813ebfb687ea81 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -977,6 +977,8 @@ are always available. They are listed here in alphabetical order. .. doctest:: + >>> int(123.45) + 123 >>> int('123') 123 >>> int(' -12_345\n') From 97a9e00dbb79b724a922294954e8041d73456f62 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Thu, 30 May 2024 15:14:46 +0300 Subject: [PATCH 6/9] Rewrite the description of the complex format and use productionlist. --- Doc/library/functions.rst | 41 ++++++++++++++++++++++++--------------- 1 file changed, 25 insertions(+), 16 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 813ebfb687ea81..c405908bb5b6d9 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -400,17 +400,24 @@ are always available. They are listed here in alphabetical order. >>> complex(-1.23, 4.5) (-1.23+4.5j) - 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`. + If the argument is a string, it must contain either a real part (in the + same format as for :func:`float`) or an imaginary part (in the same + format but with a ``'j'`` or ``'J'`` suffix ), or both real and imaginary + parts (the sign of the imaginary part is mandatory in this case). 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`. + 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`. + More precisely, the input must conform to the :token:`~float:complexvalue` + production rule in the following grammar, after parenthesis and leading and + trailing whitespace characters are removed: + + .. productionlist:: float + complexvalue: `floatvalue` | + : `floatvalue` ("j" | "J") | + : `floatvalue` `sign` `absfloatvalue` ("j" | "J") If the argument is a number, the constructor serves as a numeric conversion like :class:`int` and :class:`float`. @@ -748,9 +755,10 @@ are always available. They are listed here in alphabetical order. preceded by a sign, and optionally embedded in whitespace. The optional sign may be ``'+'`` or ``'-'``; a ``'+'`` sign has no effect on the value produced. The argument may also be a string representing a NaN - (not-a-number), or positive or negative infinity. More precisely, the - input must conform to the ``floatvalue`` production rule in the following - grammar, after leading and trailing whitespace characters are removed: + (not-a-number), or positive or negative infinity. + More precisely, the input must conform to the :token:`~float:`floatvalue` + production rule in the following grammar, after leading and trailing + whitespace characters are removed: .. productionlist:: float sign: "+" | "-" @@ -759,9 +767,10 @@ are always available. They are listed here in alphabetical order. digit: digitpart: `digit` (["_"] `digit`)* number: [`digitpart`] "." `digitpart` | `digitpart` ["."] - exponent: ("e" | "E") ["+" | "-"] `digitpart` - floatnumber: number [`exponent`] - floatvalue: [`sign`] (`floatnumber` | `infinity` | `nan`) + exponent: ("e" | "E") [`sign`] `digitpart` + floatnumber: `number` [`exponent`] + absfloatvalue: `floatnumber` | `infinity` | `nan` + floatvalue: [`sign`] `absfloatvalue` Case is not significant, so, for example, "inf", "Inf", "INFINITY", and "iNfINity" are all acceptable spellings for positive infinity. From d77833c3a50183e9c3dd99cc3df0aa863d4a9e94 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Thu, 30 May 2024 22:13:57 +0300 Subject: [PATCH 7/9] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> --- Doc/library/functions.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index c405908bb5b6d9..27e889f7dd4e73 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -405,13 +405,13 @@ are always available. They are listed here in alphabetical order. format but with a ``'j'`` or ``'J'`` suffix ), or both real and imaginary parts (the sign of the imaginary part is mandatory in this case). The string can optionally be surrounded by whitespaces and the round - parenthesis ``'('`` and ``')'``, which are ignored. + parentheses ``'('`` 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`. More precisely, the input must conform to the :token:`~float:complexvalue` - production rule in the following grammar, after parenthesis and leading and + production rule in the following grammar, after parentheses and leading and trailing whitespace characters are removed: .. productionlist:: float From 9664b6a74ea3f85170a7cc9055d065fbb55f3772 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Thu, 30 May 2024 22:26:58 +0300 Subject: [PATCH 8/9] Update Doc/library/functions.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> --- Doc/library/functions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 27e889f7dd4e73..e1daa6bb3e2373 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -402,7 +402,7 @@ are always available. They are listed here in alphabetical order. If the argument is a string, it must contain either a real part (in the same format as for :func:`float`) or an imaginary part (in the same - format but with a ``'j'`` or ``'J'`` suffix ), or both real and imaginary + format but with a ``'j'`` or ``'J'`` suffix), or both real and imaginary parts (the sign of the imaginary part is mandatory in this case). The string can optionally be surrounded by whitespaces and the round parentheses ``'('`` and ``')'``, which are ignored. From c23c65909d12965fb08cfd1e435c7cfba8709c6f Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Thu, 30 May 2024 22:58:09 +0300 Subject: [PATCH 9/9] Update Doc/library/functions.rst --- Doc/library/functions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index e1daa6bb3e2373..c07b1043afe627 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -756,7 +756,7 @@ are always available. They are listed here in alphabetical order. sign may be ``'+'`` or ``'-'``; a ``'+'`` sign has no effect on the value produced. The argument may also be a string representing a NaN (not-a-number), or positive or negative infinity. - More precisely, the input must conform to the :token:`~float:`floatvalue` + More precisely, the input must conform to the :token:`~float:floatvalue` production rule in the following grammar, after leading and trailing whitespace characters are removed: