cpython/Doc/library/functions.rst at d1a1bca1f0550a4715f1bf32b1586caa7bc4487b · python/cpython

Repository navigation

History

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

312

313

314

315

316

317

318

319

320

321

322

323

324

325

326

327

328

329

330

331

332

333

334

335

336

337

338

339

340

341

342

343

344

345

346

347

348

349

350

351

352

353

354

355

356

357

358

359

360

361

362

363

364

365

366

367

368

369

370

371

372

373

374

375

376

377

378

379

380

381

382

383

384

385

386

387

388

389

390

391

392

393

394

395

396

397

398

399

400

401

402

403

404

405

406

407

408

409

410

411

412

413

414

415

416

417

418

419

420

421

422

423

424

425

426

427

428

429

430

431

432

433

434

435

436

437

438

439

440

441

442

443

444

445

446

447

448

449

450

451

452

453

454

455

456

457

458

459

460

461

462

463

464

465

466

467

468

469

470

471

472

473

474

475

476

477

478

479

480

481

482

483

484

485

486

487

488

489

490

491

492

493

494

495

496

497

498

499

500

501

502

503

504

505

506

507

508

509

510

511

512

513

514

515

516

517

518

519

520

521

522

523

524

525

526

527

528

529

530

531

532

533

534

535

536

537

538

539

540

541

542

543

544

545

546

547

548

549

550

551

552

553

554

555

556

557

558

559

560

561

562

563

564

565

566

567

568

569

570

571

572

573

574

575

576

577

578

579

580

581

582

583

584

585

586

587

588

589

590

591

592

593

594

595

596

597

598

599

600

601

602

603

604

605

606

607

608

609

610

611

612

613

614

615

616

617

618

619

620

621

622

623

624

625

626

627

628

629

630

631

632

633

634

635

636

637

638

639

640

641

642

643

644

645

646

647

648

649

650

651

652

653

654

655

656

657

658

659

660

661

662

663

664

665

666

667

668

669

670

671

672

673

674

675

676

677

678

679

680

681

682

683

684

685

686

687

688

689

690

691

692

693

694

695

696

697

698

699

700

701

702

703

704

705

706

707

708

709

710

711

712

713

714

715

716

717

718

719

720

721

722

723

724

725

726

727

728

729

730

731

732

733

734

735

736

737

738

739

740

741

742

743

744

745

746

747

748

749

750

751

752

753

754

755

756

757

758

759

760

761

762

763

764

765

766

767

768

769

770

771

772

773

774

775

776

777

778

779

780

781

782

783

784

785

786

787

788

789

790

791

792

793

794

795

796

797

798

799

800

801

802

803

804

805

806

807

808

809

810

811

812

813

814

815

816

817

818

819

820

821

822

823

824

825

826

827

828

829

830

831

832

833

834

835

836

837

838

839

840

841

842

843

844

845

846

847

848

849

850

851

852

853

854

855

856

857

858

859

860

861

862

863

864

865

866

867

868

869

870

871

872

873

874

875

876

877

878

879

880

881

882

883

884

885

886

887

888

889

890

891

892

893

894

895

896

897

898

899

900

901

902

903

904

905

906

907

908

909

910

911

912

913

914

915

916

917

918

919

920

921

922

923

924

925

926

927

928

929

930

931

932

933

934

935

936

937

938

939

940

941

942

943

944

945

946

947

948

949

950

951

952

953

954

955

956

957

958

959

960

961

962

963

964

965

966

967

968

969

970

971

972

973

974

975

976

977

978

979

980

981

982

983

984

985

986

987

988

989

990

991

992

993

994

995

996

997

998

999

1000

.. XXX document all delegations to __special__ methods

.. _built-in-funcs:

Built-in Functions

==================

The Python interpreter has a number of functions and types built into it that

are always available. They are listed here in alphabetical order.

+---------------------------------------------------------------------------------------------------+

| Built-in Functions |

+=========================+=======================+=======================+=========================+

| | **A** | | **E** | | **L** | | **R** |

| | :func:`any` | | **F** | | **M** | | |

| | :func:`breakpoint` | | **G** | | **N** | | :func:`staticmethod` |

| | | | | | **O** | | :func:`super` |

| | **C** | | **H** | | :func:`object` | | |

| | :func:`complex` | | | | **P** | | **V** |

+-------------------------+-----------------------+-----------------------+-------------------------+

.. using :func:`dict` would create a link to another page, so local targets are

used, with replacement texts to make the output in the table consistent

.. |func-dict| replace:: ``dict()``

.. |func-frozenset| replace:: ``frozenset()``

.. |func-memoryview| replace:: ``memoryview()``

.. |func-set| replace:: ``set()``

.. |func-list| replace:: ``list()``

.. |func-str| replace:: ``str()``

.. |func-tuple| replace:: ``tuple()``

.. |func-range| replace:: ``range()``

.. |func-bytearray| replace:: ``bytearray()``

.. |func-bytes| replace:: ``bytes()``

.. function:: abs(x)

Return the absolute value of a number. The argument may be an

integer, a floating-point number, or an object implementing

:meth:`~object.__abs__`.

If the argument is a complex number, its magnitude is returned.

.. function:: aiter(async_iterable)

Return an :term:`asynchronous iterator` for an :term:`asynchronous iterable`.

Equivalent to calling ``x.__aiter__()``.

Note: Unlike :func:`iter`, :func:`aiter` has no 2-argument variant.

.. versionadded:: 3.10

.. function:: all(iterable)

Return ``True`` if all elements of the *iterable* are true (or if the iterable

is empty). Equivalent to::

def all(iterable):

for element in iterable:

if not element:

return False

return True

.. awaitablefunction:: anext(async_iterator)

anext(async_iterator, default)

When awaited, return the next item from the given :term:`asynchronous

iterator`, or *default* if given and the iterator is exhausted.

This is the async variant of the :func:`next` builtin, and behaves

similarly.

This calls the :meth:`~object.__anext__` method of *async_iterator*,

returning an :term:`awaitable`. Awaiting this returns the next value of the

iterator. If *default* is given, it is returned if the iterator is exhausted,

otherwise :exc:`StopAsyncIteration` is raised.

.. versionadded:: 3.10

.. function:: any(iterable)

Return ``True`` if any element of the *iterable* is true. If the iterable

is empty, return ``False``. Equivalent to::

def any(iterable):

for element in iterable:

if element:

return True

return False

.. function:: ascii(object)

As :func:`repr`, return a string containing a printable representation of an

object, but escape the non-ASCII characters in the string returned by

:func:`repr` using ``\x``, ``\u``, or ``\U`` escapes. This generates a string

similar to that returned by :func:`repr` in Python 2.

.. function:: bin(x)

Convert an integer number to a binary string prefixed with "0b". The result

is a valid Python expression. If *x* is not a Python :class:`int` object, it

has to define an :meth:`~object.__index__` method that returns an integer. Some

examples:

>>> bin(3)

'0b11'

>>> bin(-10)

'-0b1010'

If the prefix "0b" is desired or not, you can use either of the following ways.

>>> format(14, '#b'), format(14, 'b')

('0b1110', '1110')

>>> f'{14:#b}', f'{14:b}'

('0b1110', '1110')

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

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

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

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

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

``True`` (see :ref:`typebool`).

.. index:: pair: Boolean; type

.. versionchanged:: 3.7

The parameter is now positional-only.

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

This function drops you into the debugger at the call site. Specifically,

it calls :func:`sys.breakpointhook`, passing ``args`` and ``kws`` straight

through. By default, ``sys.breakpointhook()`` calls

:func:`pdb.set_trace()` expecting no arguments. In this case, it is

purely a convenience function so you don't have to explicitly import

:mod:`pdb` or type as much code to enter the debugger. However,

:func:`sys.breakpointhook` can be set to some other function and

:func:`breakpoint` will automatically call that, allowing you to drop into

the debugger of choice.

If :func:`sys.breakpointhook` is not accessible, this function will

raise :exc:`RuntimeError`.

By default, the behavior of :func:`breakpoint` can be changed with

the :envvar:`PYTHONBREAKPOINT` environment variable.

See :func:`sys.breakpointhook` for usage details.

Note that this is not guaranteed if :func:`sys.breakpointhook`

has been replaced.

.. audit-event:: builtins.breakpoint breakpointhook breakpoint

.. versionadded:: 3.7

.. _func-bytearray:

.. class:: bytearray(source=b'')

bytearray(source, encoding)

bytearray(source, encoding, errors)

:noindex:

Return a new array of bytes. The :class:`bytearray` class is a mutable

sequence of integers in the range 0 <= x < 256. It has most of the usual

methods of mutable sequences, described in :ref:`typesseq-mutable`, as well

as most methods that the :class:`bytes` type has, see :ref:`bytes-methods`.

The optional *source* parameter can be used to initialize the array in a few

different ways:

* If it is a *string*, you must also give the *encoding* (and optionally,

*errors*) parameters; :func:`bytearray` then converts the string to

bytes using :meth:`str.encode`.

* If it is an *integer*, the array will have that size and will be

initialized with null bytes.

* If it is an object conforming to the :ref:`buffer interface <bufferobjects>`,

a read-only buffer of the object will be used to initialize the bytes array.

* If it is an *iterable*, it must be an iterable of integers in the range

``0 <= x < 256``, which are used as the initial contents of the array.

Without an argument, an array of size 0 is created.

See also :ref:`binaryseq` and :ref:`typebytearray`.

.. _func-bytes:

.. class:: bytes(source=b'')

bytes(source, encoding)

bytes(source, encoding, errors)

:noindex:

Return a new "bytes" object which is an immutable sequence of integers in

the range ``0 <= x < 256``. :class:`bytes` is an immutable version of

:class:`bytearray` -- it has the same non-mutating methods and the same

indexing and slicing behavior.

Accordingly, constructor arguments are interpreted as for :func:`bytearray`.

Bytes objects can also be created with literals, see :ref:`strings`.

See also :ref:`binaryseq`, :ref:`typebytes`, and :ref:`bytes-methods`.

.. function:: callable(object)

Return :const:`True` if the *object* argument appears callable,

:const:`False` if not. If this returns ``True``, it is still possible that a

call fails, but if it is ``False``, calling *object* will never succeed.

Note that classes are callable (calling a class returns a new instance);

instances are callable if their class has a :meth:`~object.__call__` method.

.. versionadded:: 3.2

This function was first removed in Python 3.0 and then brought back

in Python 3.2.

.. function:: chr(i)

Return the string representing a character whose Unicode code point is the

integer *i*. For example, ``chr(97)`` returns the string ``'a'``, while

``chr(8364)`` returns the string ``'€'``. This is the inverse of :func:`ord`.

The valid range for the argument is from 0 through 1,114,111 (0x10FFFF in

base 16). :exc:`ValueError` will be raised if *i* is outside that range.

.. decorator:: classmethod

Transform a method into a class method.

A class method receives the class as an implicit first argument, just like an

instance method receives the instance. To declare a class method, use this

idiom::

class C:

@classmethod

def f(cls, arg1, arg2): ...

The ``@classmethod`` form is a function :term:`decorator` -- see

:ref:`function` for details.

A class method can be called either on the class (such as ``C.f()``) or on an instance (such

as ``C().f()``). The instance is ignored except for its class. If a class

method is called for a derived class, the derived class object is passed as the

implied first argument.

Class methods are different than C++ or Java static methods. If you want those,

see :func:`staticmethod` in this section.

For more information on class methods, see :ref:`types`.

.. versionchanged:: 3.9

Class methods can now wrap other :term:`descriptors <descriptor>` such as

:func:`property`.

.. versionchanged:: 3.10

Class methods now inherit the method attributes (``__module__``,

``__name__``, ``__qualname__``, ``__doc__`` and ``__annotations__``) and

have a new ``__wrapped__`` attribute.

.. deprecated-removed:: 3.11 3.13

Class methods can no longer wrap other :term:`descriptors <descriptor>` such as

:func:`property`.

.. function:: compile(source, filename, mode, flags=0, dont_inherit=False, optimize=-1)

Compile the *source* into a code or AST object. Code objects can be executed

by :func:`exec` or :func:`eval`. *source* can either be a normal string, a

byte string, or an AST object. Refer to the :mod:`ast` module documentation

for information on how to work with AST objects.

The *filename* argument should give the file from which the code was read;

pass some recognizable value if it wasn't read from a file (``'<string>'`` is

commonly used).

The *mode* argument specifies what kind of code must be compiled; it can be

``'exec'`` if *source* consists of a sequence of statements, ``'eval'`` if it

consists of a single expression, or ``'single'`` if it consists of a single

interactive statement (in the latter case, expression statements that

evaluate to something other than ``None`` will be printed).

The optional arguments *flags* and *dont_inherit* control which

:ref:`compiler options <ast-compiler-flags>` should be activated

and which :ref:`future features <future>` should be allowed. If neither

is present (or both are zero) the code is compiled with the same flags that

affect the code that is calling :func:`compile`. If the *flags*

argument is given and *dont_inherit* is not (or is zero) then the compiler

options and the future statements specified by the *flags* argument are used

in addition to those that would be used anyway. If *dont_inherit* is a

non-zero integer then the *flags* argument is it -- the flags (future

features and compiler options) in the surrounding code are ignored.

Compiler options and future statements are specified by bits which can be

bitwise ORed together to specify multiple options. The bitfield required to

specify a given future feature can be found as the

:attr:`~__future__._Feature.compiler_flag` attribute on the

:class:`~__future__._Feature` instance in the :mod:`__future__` module.

:ref:`Compiler flags <ast-compiler-flags>` can be found in :mod:`ast`

module, with ``PyCF_`` prefix.

The argument *optimize* specifies the optimization level of the compiler; the

default value of ``-1`` selects the optimization level of the interpreter as

given by :option:`-O` options. Explicit levels are ``0`` (no optimization;

``__debug__`` is true), ``1`` (asserts are removed, ``__debug__`` is false)

or ``2`` (docstrings are removed too).

This function raises :exc:`SyntaxError` if the compiled source is invalid,

and :exc:`ValueError` if the source contains null bytes.

If you want to parse Python code into its AST representation, see

:func:`ast.parse`.

.. audit-event:: compile source,filename compile

Raises an :ref:`auditing event <auditing>` ``compile`` with arguments

``source`` and ``filename``. This event may also be raised by implicit

compilation.

.. note::

When compiling a string with multi-line code in ``'single'`` or

``'eval'`` mode, input must be terminated by at least one newline

character. This is to facilitate detection of incomplete and complete

statements in the :mod:`code` module.

.. warning::

It is possible to crash the Python interpreter with a

sufficiently large/complex string when compiling to an AST

object due to stack depth limitations in Python's AST compiler.

.. versionchanged:: 3.2

Allowed use of Windows and Mac newlines. Also, input in ``'exec'`` mode

does not have to end in a newline anymore. Added the *optimize* parameter.

.. versionchanged:: 3.5

Previously, :exc:`TypeError` was raised when null bytes were encountered

in *source*.

.. versionadded:: 3.8

``ast.PyCF_ALLOW_TOP_LEVEL_AWAIT`` can now be passed in flags to enable

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

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

complex(string, /)

complex(real=0, imag=0)

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

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

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

to :meth:`~object.__index__`.

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.

See also :meth:`complex.from_number` which only accepts a single numeric argument.

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

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

.. versionchanged:: 3.6

Grouping digits with underscores as in code literals is allowed.

.. versionchanged:: 3.8

Falls back to :meth:`~object.__index__` if :meth:`~object.__complex__` and

:meth:`~object.__float__` are not defined.

.. deprecated:: 3.14

Passing a complex number as the *real* or *imag* argument is now

deprecated; it should only be passed as a single positional argument.

.. function:: delattr(object, name)

This is a relative of :func:`setattr`. The arguments are an object and a

string. The string must be the name of one of the object's attributes. The

function deletes the named attribute, provided the object allows it. For

example, ``delattr(x, 'foobar')`` is equivalent to ``del x.foobar``.

*name* need not be a Python identifier (see :func:`setattr`).

.. _func-dict:

.. class:: dict(**kwarg)

dict(mapping, **kwarg)

dict(iterable, **kwarg)

:noindex:

Create a new dictionary. The :class:`dict` object is the dictionary class.

See :class:`dict` and :ref:`typesmapping` for documentation about this class.

For other containers see the built-in :class:`list`, :class:`set`, and

:class:`tuple` classes, as well as the :mod:`collections` module.

.. function:: dir()

dir(object)

Without arguments, return the list of names in the current local scope. With an

argument, attempt to return a list of valid attributes for that object.

If the object has a method named :meth:`~object.__dir__`,

this method will be called and

must return the list of attributes. This allows objects that implement a custom

:func:`~object.__getattr__` or :func:`~object.__getattribute__` function

to customize the way

:func:`dir` reports their attributes.

If the object does not provide :meth:`~object.__dir__`,

the function tries its best to gather information from the object's

:attr:`~object.__dict__` attribute, if defined, and

from its type object. The resulting list is not necessarily complete and may

be inaccurate when the object has a custom :func:`~object.__getattr__`.

The default :func:`dir` mechanism behaves differently with different types of

objects, as it attempts to produce the most relevant, rather than complete,

information:

* If the object is a module object, the list contains the names of the module's

attributes.

* If the object is a type or class object, the list contains the names of its

attributes, and recursively of the attributes of its bases.

* Otherwise, the list contains the object's attributes' names, the names of its

class's attributes, and recursively of the attributes of its class's base

classes.

The resulting list is sorted alphabetically. For example:

>>> import struct

>>> dir() # show the names in the module namespace # doctest: +SKIP

['__builtins__', '__name__', 'struct']

>>> dir(struct) # show the names in the struct module # doctest: +SKIP

['Struct', '__all__', '__builtins__', '__cached__', '__doc__', '__file__',

'__initializing__', '__loader__', '__name__', '__package__',

'_clearcache', 'calcsize', 'error', 'pack', 'pack_into',

'unpack', 'unpack_from']

>>> class Shape:

... def __dir__(self):

... return ['area', 'perimeter', 'location']

...

>>> s = Shape()

>>> dir(s)

['area', 'location', 'perimeter']

.. note::

Because :func:`dir` is supplied primarily as a convenience for use at an

interactive prompt, it tries to supply an interesting set of names more

than it tries to supply a rigorously or consistently defined set of names,

and its detailed behavior may change across releases. For example,

metaclass attributes are not in the result list when the argument is a

class.

.. function:: divmod(a, b)

Take two (non-complex) numbers as arguments and return a pair of numbers

consisting of their quotient and remainder when using integer division. With

mixed operand types, the rules for binary arithmetic operators apply. For

integers, the result is the same as ``(a // b, a % b)``. For floating-point

numbers the result is ``(q, a % b)``, where *q* is usually ``math.floor(a /

b)`` but may be 1 less than that. In any case ``q * b + a % b`` is very

close to *a*, if ``a % b`` is non-zero it has the same sign as *b*, and ``0

<= abs(a % b) < abs(b)``.

.. function:: enumerate(iterable, start=0)

Return an enumerate object. *iterable* must be a sequence, an

:term:`iterator`, or some other object which supports iteration.

The :meth:`~iterator.__next__` method of the iterator returned by

:func:`enumerate` returns a tuple containing a count (from *start* which

defaults to 0) and the values obtained from iterating over *iterable*.

>>> seasons = ['Spring', 'Summer', 'Fall', 'Winter']

>>> list(enumerate(seasons))

[(0, 'Spring'), (1, 'Summer'), (2, 'Fall'), (3, 'Winter')]

>>> list(enumerate(seasons, start=1))

[(1, 'Spring'), (2, 'Summer'), (3, 'Fall'), (4, 'Winter')]

Equivalent to::

def enumerate(iterable, start=0):

n = start

for elem in iterable:

yield n, elem

n += 1

.. _func-eval:

.. function:: eval(source, /, globals=None, locals=None)

:param source:

A Python expression.

:type source: :class:`str` | :ref:`code object <code-objects>`

:param globals:

The global namespace (default: ``None``).

:type globals: :class:`dict` | ``None``

:param locals:

The local namespace (default: ``None``).

:type locals: :term:`mapping` | ``None``

:returns: The result of the evaluated expression.

:raises: Syntax errors are reported as exceptions.

The *expression* argument is parsed and evaluated as a Python expression

(technically speaking, a condition list) using the *globals* and *locals*

mappings as global and local namespace. If the *globals* dictionary is

present and does not contain a value for the key ``__builtins__``, a

reference to the dictionary of the built-in module :mod:`builtins` is

inserted under that key before *expression* is parsed. That way you can

control what builtins are available to the executed code by inserting your

own ``__builtins__`` dictionary into *globals* before passing it to

:func:`eval`. If the *locals* mapping is omitted it defaults to the

*globals* dictionary. If both mappings are omitted, the expression is

executed with the *globals* and *locals* in the environment where

:func:`eval` is called. Note, *eval()* will only have access to the

:term:`nested scopes <nested scope>` (non-locals) in the enclosing

environment if they are already referenced in the scope that is calling

:func:`eval` (e.g. via a :keyword:`nonlocal` statement).

Example:

>>> x = 1

>>> eval('x+1')

This function can also be used to execute arbitrary code objects (such as

those created by :func:`compile`). In this case, pass a code object instead

of a string. If the code object has been compiled with ``'exec'`` as the

*mode* argument, :func:`eval`\'s return value will be ``None``.

Hints: dynamic execution of statements is supported by the :func:`exec`

function. The :func:`globals` and :func:`locals` functions

return the current global and local dictionary, respectively, which may be

useful to pass around for use by :func:`eval` or :func:`exec`.

If the given source is a string, then leading and trailing spaces and tabs

are stripped.

See :func:`ast.literal_eval` for a function that can safely evaluate strings

with expressions containing only literals.

.. audit-event:: exec code_object eval

Raises an :ref:`auditing event <auditing>` ``exec`` with the code object

as the argument. Code compilation events may also be raised.

.. versionchanged:: 3.13

The *globals* and *locals* arguments can now be passed as keywords.

.. versionchanged:: 3.13

The semantics of the default *locals* namespace have been adjusted as

described for the :func:`locals` builtin.

.. index:: pair: built-in function; exec

.. function:: exec(source, /, globals=None, locals=None, *, closure=None)

This function supports dynamic execution of Python code. *source* must be

either a string or a code object. If it is a string, the string is parsed as

a suite of Python statements which is then executed (unless a syntax error

occurs). [#]_ If it is a code object, it is simply executed. In all cases,

the code that's executed is expected to be valid as file input (see the

section :ref:`file-input` in the Reference Manual). Be aware that the

:keyword:`nonlocal`, :keyword:`yield`, and :keyword:`return`

statements may not be used outside of

function definitions even within the context of code passed to the

:func:`exec` function. The return value is ``None``.

In all cases, if the optional parts are omitted, the code is executed in the

current scope. If only *globals* is provided, it must be a dictionary

(and not a subclass of dictionary), which

will be used for both the global and the local variables. If *globals* and

*locals* are given, they are used for the global and local variables,

respectively. If provided, *locals* can be any mapping object. Remember

that at the module level, globals and locals are the same dictionary.

.. note::

When ``exec`` gets two separate objects as *globals* and *locals*, the

code will be executed as if it were embedded in a class definition. This

means functions and classes defined in the executed code will not be able

to access variables assigned at the top level (as the "top level"

variables are treated as class variables in a class definition).

If the *globals* dictionary does not contain a value for the key

``__builtins__``, a reference to the dictionary of the built-in module

:mod:`builtins` is inserted under that key. That way you can control what

builtins are available to the executed code by inserting your own

``__builtins__`` dictionary into *globals* before passing it to :func:`exec`.

The *closure* argument specifies a closure--a tuple of cellvars.

It's only valid when the *object* is a code object containing free variables.

The length of the tuple must exactly match the number of free variables

referenced by the code object.

.. audit-event:: exec code_object exec

Raises an :ref:`auditing event <auditing>` ``exec`` with the code object

as the argument. Code compilation events may also be raised.

.. note::

The built-in functions :func:`globals` and :func:`locals` return the current

global and local namespace, respectively, which may be useful to pass around

for use as the second and third argument to :func:`exec`.

.. note::

The default *locals* act as described for function :func:`locals` below.

Pass an explicit *locals* dictionary if you need to see effects of the

code on *locals* after function :func:`exec` returns.

.. versionchanged:: 3.11

Added the *closure* parameter.

.. versionchanged:: 3.13

The *globals* and *locals* arguments can now be passed as keywords.

.. versionchanged:: 3.13

The semantics of the default *locals* namespace have been adjusted as

described for the :func:`locals` builtin.

.. function:: filter(function, iterable)

Construct an iterator from those elements of *iterable* for which *function*

is true. *iterable* may be either a sequence, a container which

supports iteration, or an iterator. If *function* is ``None``, the identity

function is assumed, that is, all elements of *iterable* that are false are

removed.

Note that ``filter(function, iterable)`` is equivalent to the generator

expression ``(item for item in iterable if function(item))`` if function is

not ``None`` and ``(item for item in iterable if item)`` if function is

``None``.

See :func:`itertools.filterfalse` for the complementary function that returns

elements of *iterable* for which *function* is false.

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

float(string, /)

.. index::

single: NaN

single: Infinity

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

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`

production rule in the following grammar, after leading and trailing

whitespace characters are removed:

.. productionlist:: float

sign: "+" | "-"

infinity: "Infinity" | "inf"

nan: "nan"

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

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

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

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.

Otherwise, if the argument is an integer or a floating-point number, a

floating-point number with the same value (within Python's floating-point

precision) is returned. If the argument is outside the range of a Python

float, an :exc:`OverflowError` will be raised.

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

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

to :meth:`~object.__index__`.

See also :meth:`float.from_number` which only accepts a numeric argument.

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

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

.. versionchanged:: 3.6

Grouping digits with underscores as in code literals is allowed.

.. versionchanged:: 3.7

The parameter is now positional-only.

.. versionchanged:: 3.8

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

.. index::

single: __format__

single: string; format() (built-in function)

.. function:: format(value, format_spec="")

Convert a *value* to a "formatted" representation, as controlled by

*format_spec*. The interpretation of *format_spec* will depend on the type

of the *value* argument; however, there is a standard formatting syntax that

is used by most built-in types: :ref:`formatspec`.

The default *format_spec* is an empty string which usually gives the same

effect as calling :func:`str(value) <str>`.

A call to ``format(value, format_spec)`` is translated to

``type(value).__format__(value, format_spec)`` which bypasses the instance

dictionary when searching for the value's :meth:`~object.__format__` method.

A :exc:`TypeError` exception is raised if the method search reaches

:mod:`object` and the *format_spec* is non-empty, or if either the

*format_spec* or the return value are not strings.

.. versionchanged:: 3.4

``object().__format__(format_spec)`` raises :exc:`TypeError`

if *format_spec* is not an empty string.

.. _func-frozenset:

.. class:: frozenset(iterable=set())

:noindex:

Return a new :class:`frozenset` object, optionally with elements taken from

*iterable*. ``frozenset`` is a built-in class. See :class:`frozenset` and

:ref:`types-set` for documentation about this class.

For other containers see the built-in :class:`set`, :class:`list`,

:class:`tuple`, and :class:`dict` classes, as well as the :mod:`collections`

module.

.. function:: getattr(object, name)

getattr(object, name, default)

Return the value of the named attribute of *object*. *name* must be a string.

If the string is the name of one of the object's attributes, the result is the

value of that attribute. For example, ``getattr(x, 'foobar')`` is equivalent to

``x.foobar``. If the named attribute does not exist, *default* is returned if

provided, otherwise :exc:`AttributeError` is raised.

*name* need not be a Python identifier (see :func:`setattr`).

.. note::

Since :ref:`private name mangling <private-name-mangling>` happens at

compilation time, one must manually mangle a private attribute's

(attributes with two leading underscores) name in order to retrieve it with

:func:`getattr`.

.. function:: globals()

Return the dictionary implementing the current module namespace. For code within

functions, this is set when the function is defined and remains the same

regardless of where the function is called.

.. function:: hasattr(object, name)

The arguments are an object and a string. The result is ``True`` if the

string is the name of one of the object's attributes, ``False`` if not. (This

is implemented by calling ``getattr(object, name)`` and seeing whether it

raises an :exc:`AttributeError` or not.)

.. function:: hash(object)

Return the hash value of the object (if it has one). Hash values are

integers. They are used to quickly compare dictionary keys during a

dictionary lookup. Numeric values that compare equal have the same hash

value (even if they are of different types, as is the case for 1 and 1.0).

.. note::

For objects with custom :meth:`~object.__hash__` methods,

note that :func:`hash`

truncates the return value based on the bit width of the host machine.

.. function:: help()

help(request)

Invoke the built-in help system. (This function is intended for interactive

use.) If no argument is given, the interactive help system starts on the

interpreter console. If the argument is a string, then the string is looked up

as the name of a module, function, class, method, keyword, or documentation

topic, and a help page is printed on the console. If the argument is any other

kind of object, a help page on the object is generated.

Note that if a slash(/) appears in the parameter list of a function when

invoking :func:`help`, it means that the parameters prior to the slash are

positional-only. For more info, see

:ref:`the FAQ entry on positional-only parameters <faq-positional-only-arguments>`.

This function is added to the built-in namespace by the :mod:`site` module.

.. versionchanged:: 3.4

Changes to :mod:`pydoc` and :mod:`inspect` mean that the reported

signatures for callables are now more comprehensive and consistent.

.. function:: hex(x)

Convert an integer number to a lowercase hexadecimal string prefixed with

"0x". If *x* is not a Python :class:`int` object, it has to define an

:meth:`~object.__index__` method that returns an integer. Some examples:

>>> hex(255)

'0xff'

>>> hex(-42)

'-0x2a'

If you want to convert an integer number to an uppercase or lower hexadecimal

string with prefix or not, you can use either of the following ways:

>>> '%#x' % 255, '%x' % 255, '%X' % 255

('0xff', 'ff', 'FF')

>>> format(255, '#x'), format(255, 'x'), format(255, 'X')

('0xff', 'ff', 'FF')

>>> f'{255:#x}', f'{255:x}', f'{255:X}'

('0xff', 'ff', 'FF')

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

See also :func:`int` for converting a hexadecimal string to an

integer using a base of 16.

.. note::

To obtain a hexadecimal string representation for a float, use the

:meth:`float.hex` method.

.. function:: id(object)

Return the "identity" of an object. This is an integer which

is guaranteed to be unique and constant for this object during its lifetime.

Two objects with non-overlapping lifetimes may have the same :func:`id`

value.

.. impl-detail:: This is the address of the object in memory.

.. audit-event:: builtins.id id id

.. function:: input()

input(prompt)

If the *prompt* argument is present, it is written to standard output without

a trailing newline. The function then reads a line from input, converts it

to a string (stripping a trailing newline), and returns that. When EOF is

read, :exc:`EOFError` is raised. Example::

>>> s = input('--> ') # doctest: +SKIP

--> Monty Python's Flying Circus

>>> s # doctest: +SKIP

"Monty Python's Flying Circus"

If the :mod:`readline` module was loaded, then :func:`input` will use it

to provide elaborate line editing and history features.

.. audit-event:: builtins.input prompt input

Raises an :ref:`auditing event <auditing>` ``builtins.input`` with

argument ``prompt`` before reading input

.. audit-event:: builtins.input/result result input

Raises an :ref:`auditing event <auditing>` ``builtins.input/result``

with the result after successfully reading input.

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

Examples:

.. doctest::

>>> int(123.45)

123

>>> int('123')

123

View remainder of file in raw view

FilesExpand file tree

functions.rst

Latest commit

History

functions.rst

File metadata and controls