gh-109218: Improve documentation for the complex() constructor (GH-11… · miss-islington/cpython@ec1ba26 (original) (raw)

`@@ -141,10 +141,11 @@ are always available. They are listed here in alphabetical order.

141

`` See also :func:format for more information.

142

143

144

.. class:: bool(x=False)

144

.. class:: bool(object=False, /)

145

146


 Return a Boolean value, i.e. one of ``True`` or ``False``. *x* is converted

147

`` -

using the standard :ref:truth testing procedure <truth>. If x is false

146


 Return a Boolean value, i.e. one of ``True`` or ``False``. The argument

147

`` +

is converted using the standard :ref:truth testing procedure <truth>.

148

If the argument is false

148

149

``` or omitted, this returns False; otherwise, it returns True. The


`149`

`150`

`` :class:`bool` class is a subclass of :class:`int` (see :ref:`typesnumeric`).

``

`150`

`151`

```  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.

153

154

` .. index:: pair: Boolean; type

154

155

156

` .. versionchanged:: 3.7

156

x is now a positional-only parameter.

157

The parameter is now positional-only.

157

158

159

`.. function:: breakpoint(*args, **kws)

159

160

`@@ -371,29 +372,73 @@ are always available. They are listed here in alphabetical order.

371

372

``` support for top-level await, async for, and async with.


`372`

`373`

``

`373`

`374`

``

`374`

``

`-

.. class:: complex(real=0, imag=0)

`

`375`

``

`-

complex(string)

`

``

`375`

`+

.. class:: complex(number=0, /)

`

``

`376`

`+

complex(string, /)

`

``

`377`

`+

complex(real=0, imag=0)

`

``

`378`

`+`

``

`379`

`+

Convert a single string or number to a complex number, or create a

`

``

`380`

`+

complex number from real and imaginary parts.

`

``

`381`

`+`

``

`382`

`+

Examples:

`

``

`383`

`+`

``

`384`

`+

.. doctest::

`

``

`385`

`+`

``

`386`

`+

>>> complex('+1.23')

`

``

`387`

`+

(1.23+0j)

`

``

`388`

`+

>>> complex('-4.5j')

`

``

`389`

`+

-4.5j

`

``

`390`

`+

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

`

``

`391`

`+

(-1.23+4.5j)

`

``

`392`

`+

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

`

``

`393`

`+

(-1.23+4.5j)

`

``

`394`

`+

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

`

``

`395`

`+

(-inf+nanj)

`

``

`396`

`+

>>> complex(1.23)

`

``

`397`

`+

(1.23+0j)

`

``

`398`

`+

>>> complex(imag=-4.5)

`

``

`399`

`+

-4.5j

`

``

`400`

`+

>>> complex(-1.23, 4.5)

`

``

`401`

`+

(-1.23+4.5j)

`

``

`402`

`+`

``

`403`

`+

If the argument is a string, it must contain either a real part (in the

`

``

`404`

`` +

same format as for :func:`float`) or an imaginary part (in the same

``

``

`405`

``` +

format but with a ``'j'`` or ``'J'`` suffix), or both real and imaginary

406

parts (the sign of the imaginary part is mandatory in this case).

407

The string can optionally be surrounded by whitespaces and the round

408


 parentheses ``'('`` and ``')'``, which are ignored.

409


 The string must not contain whitespace between ``'+'``, ``'-'``, the

410


 ``'j'`` or ``'J'`` suffix, and the decimal number.

411


 For example, ``complex('1+2j')`` is fine, but ``complex('1 + 2j')`` raises

412

`` +

:exc:ValueError.

413

`` +

More precisely, the input must conform to the :token:~float:complexvalue

414

production rule in the following grammar, after parentheses and leading and

415

trailing whitespace characters are removed:

376

416

377

Return a complex number with the value real + imag*1j or convert a string

378

or number to a complex number. If the first parameter is a string, it will

379

be interpreted as a complex number and the function must be called without a

380

second parameter. The second parameter can never be a string. Each argument

381

may be any numeric type (including complex). If imag is omitted, it

382

defaults to zero and the constructor serves as a numeric conversion like

383

`` -

:class:int and :class:float. If both arguments are omitted, returns

384


 ``0j``.

417

.. productionlist:: float

418

`` +

complexvalue: floatvalue |

419

`` +

: floatvalue ("j" | "J") |

420

`` +

: floatvalue sign absfloatvalue ("j" | "J")

385

421

422

If the argument is a number, the constructor serves as a numeric

423

`` +

conversion like :class:int and :class:float.

386

424

``` For a general Python object x, complex(x) delegates to


`387`

``

``` -

``x.__complex__()``. If :meth:`~object.__complex__` is not defined then it falls back

388

`` -

to :meth:~object.__float__. If :meth:!__float__ is not defined then it falls back

425


 ``x.__complex__()``.

426

`` +

If :meth:~object.__complex__ is not defined then it falls back

427

`` +

to :meth:~object.__float__.

428

`` +

If :meth:!__float__ is not defined then it falls back

389

429

`` to :meth:~object.__index__.

390

430

391

.. note::

431

If two arguments are provided or keyword arguments are used, each argument

432

may be any numeric type (including complex).

433

If both arguments are real numbers, return a complex number with the real

434

component real and the imaginary component imag.

435

If both arguments are complex numbers, return a complex number with the real

436


 component ``real.real-imag.imag`` and the imaginary component

437


 ``real.imag+imag.real``.

438

If one of arguments is a real number, only its real component is used in

439

the above expressions.

392

440

393

When converting from a string, the string must not contain whitespace

394


 around the central ``+`` or ``-`` operator. For example,

395


 ``complex('1+2j')`` is fine, but ``complex('1 + 2j')`` raises

396

`` -

:exc:ValueError.

441


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

397

442

398

443

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

399

444

`@@ -682,21 +727,38 @@ are always available. They are listed here in alphabetical order.

682

727

` elements of iterable for which function is false.

683

728

684

729

685

.. class:: float(x=0.0)

730

.. class:: float(number=0.0, /)

731

float(string, /)

686

732

687

733

` .. index::

688

734

` single: NaN

689

735

` single: Infinity

690

736

691

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

737

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

738

+

739

Examples:

740

+

741

.. doctest::

742

+

743

float('+1.23')

744

1.23

745

float(' -12345\n')

746

-12345.0

747

float('1e-003')

748

0.001

749

float('+1E6')

750

1000000.0

751

float('-Infinity')

752

-inf

692

753

693

754

` If the argument is a string, it should contain a decimal number, optionally

694

755

` preceded by a sign, and optionally embedded in whitespace. The optional

695

756

``` sign may be '+' or '-'; a '+' sign has no effect on the value


`696`

`757`

` produced. The argument may also be a string representing a NaN

`

`697`

``

`-

(not-a-number), or positive or negative infinity. More precisely, the

`

`698`

``

``` -

input must conform to the ``floatvalue`` production rule in the following

699

grammar, after leading and trailing whitespace characters are removed:

758

(not-a-number), or positive or negative infinity.

759

`` +

More precisely, the input must conform to the :token:~float:floatvalue

760

production rule in the following grammar, after leading and trailing

761

whitespace characters are removed:

700

762

701

763

` .. productionlist:: float

702

764

` sign: "+" | "-"

`@@ -705,9 +767,10 @@ are always available. They are listed here in alphabetical order.

705

767

` digit: <a Unicode decimal digit, i.e. characters in Unicode general category Nd>

706

768

`` digitpart: digit (["_"] digit)*

707

769

`` number: [digitpart] "." digitpart | digitpart ["."]

708

`` -

exponent: ("e" | "E") ["+" | "-"] digitpart

709

`` -

floatnumber: number [exponent]

710

`` -

floatvalue: [sign] (floatnumber | infinity | nan)

770

`` +

exponent: ("e" | "E") [sign] digitpart

771

`` +

floatnumber: number [exponent]

772

`` +

absfloatvalue: floatnumber | infinity | nan

773

`` +

floatvalue: [sign] absfloatvalue

711

774

712

775

` Case is not significant, so, for example, "inf", "Inf", "INFINITY", and

713

776

` "iNfINity" are all acceptable spellings for positive infinity.

`@@ -723,26 +786,13 @@ are always available. They are listed here in alphabetical order.

723

786

724

787

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


`725`

`788`

``

`726`

``

`-

Examples::

`

`727`

``

`-`

`728`

``

`-

>>> float('+1.23')

`

`729`

``

`-

1.23

`

`730`

``

`-

>>> float(' -12345\n')

`

`731`

``

`-

-12345.0

`

`732`

``

`-

>>> float('1e-003')

`

`733`

``

`-

0.001

`

`734`

``

`-

>>> float('+1E6')

`

`735`

``

`-

1000000.0

`

`736`

``

`-

>>> float('-Infinity')

`

`737`

``

`-

-inf

`

`738`

``

`-`

`739`

`789`

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

``

`740`

`790`

``

`741`

`791`

` .. versionchanged:: 3.6

`

`742`

`792`

` Grouping digits with underscores as in code literals is allowed.

`

`743`

`793`

``

`744`

`794`

` .. versionchanged:: 3.7

`

`745`

``

`-

*x* is now a positional-only parameter.

`

``

`795`

`+

The parameter is now positional-only.

`

`746`

`796`

``

`747`

`797`

` .. versionchanged:: 3.8

`

`748`

`798`

``  Falls back to :meth:`~object.__index__` if :meth:`~object.__float__` is not defined.

``

`@@ -926,17 +976,36 @@ are always available. They are listed here in alphabetical order.

`

`926`

`976`

` with the result after successfully reading input.

`

`927`

`977`

``

`928`

`978`

``

`929`

``

`-

.. class:: int(x=0)

`

`930`

``

`-

int(x, base=10)

`

``

`979`

`+

.. class:: int(number=0, /)

`

``

`980`

`+

int(string, /, base=10)

`

``

`981`

`+`

``

`982`

`+

Return an integer object constructed from a number or a string, or return

`

``

`983`

``` +

``0`` if no arguments are given.

984

+

985

Examples:

986

+

987

.. doctest::

988

+

989

int(123.45)

990

123

991

int('123')

992

123

993

int(' -12_345\n')

994

-12345

995

int('FACE', 16)

996

64206

997

int('0xface', 0)

998

64206

999

int('01110011', base=2)

1000

115

931

1001

932

Return an integer object constructed from a number or string x, or return

933


 ``0`` if no arguments are given. If *x* defines :meth:`~object.__int__`,

934


 ``int(x)`` returns ``x.__int__()``. If *x* defines :meth:`~object.__index__`,

935


 it returns ``x.__index__()``. If *x* defines :meth:`~object.__trunc__`,

1002

`` +

If the argument defines :meth:~object.__int__,

1003


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

1004


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

936

1005

``` it returns x.__trunc__().


`937`

`1006`

` For floating point numbers, this truncates towards zero.

`

`938`

`1007`

``

`939`

``

`-

If *x* is not a number or if *base* is given, then *x* must be a string,

`

``

`1008`

`+

If the argument is not a number or if *base* is given, then it must be a string,

`

`940`

`1009`

`` :class:`bytes`, or :class:`bytearray` instance representing an integer

``

`941`

`1010`

```  in radix *base*. Optionally, the string can be preceded by ``+`` or ``-``

942

1011

` (with no space in between), have leading zeros, be surrounded by whitespace,

`@@ -966,7 +1035,7 @@ are always available. They are listed here in alphabetical order.

966

1035

` Grouping digits with underscores as in code literals is allowed.

967

1036

968

1037

` .. versionchanged:: 3.7

969

x is now a positional-only parameter.

1038

The first parameter is now positional-only.

970

1039

971

1040

` .. versionchanged:: 3.8

972

1041

`` Falls back to :meth:~object.__index__ if :meth:~object.__int__ is not defined.

`@@ -977,7 +1046,7 @@ are always available. They are listed here in alphabetical order.

977

1046

` .. versionchanged:: 3.11

978

1047

`` :class:int string inputs and string representations can be limited to

979

1048

`` help avoid denial of service attacks. A :exc:ValueError is raised when

980

`` -

the limit is exceeded while converting a string x to an :class:int or

1049

`` +

the limit is exceeded while converting a string to an :class:int or

981

1050

`` when converting an :class:int into a string would exceed the limit.

982

1051

`` See the :ref:`integer string conversion length limitation

983

1052

`` ` documentation.