1.. XXX document all delegations to __special__ methods 2.. _built-in-funcs: 3 4Built-in Functions 5================== 6 7The Python interpreter has a number of functions and types built into it that 8are always available. They are listed here in alphabetical order. 9 10+---------------------------------------------------------------------------------------------------+ 11| Built-in Functions | 12+=========================+=======================+=======================+=========================+ 13| | **A** | | **E** | | **L** | | **R** | 14| | :func:`abs` | | :func:`enumerate` | | :func:`len` | | |func-range|_ | 15| | :func:`aiter` | | :func:`eval` | | |func-list|_ | | :func:`repr` | 16| | :func:`all` | | :func:`exec` | | :func:`locals` | | :func:`reversed` | 17| | :func:`anext` | | | | | | :func:`round` | 18| | :func:`any` | | **F** | | **M** | | | 19| | :func:`ascii` | | :func:`filter` | | :func:`map` | | **S** | 20| | | | :func:`float` | | :func:`max` | | |func-set|_ | 21| | **B** | | :func:`format` | | |func-memoryview|_ | | :func:`setattr` | 22| | :func:`bin` | | |func-frozenset|_ | | :func:`min` | | :func:`slice` | 23| | :func:`bool` | | | | | | :func:`sorted` | 24| | :func:`breakpoint` | | **G** | | **N** | | :func:`staticmethod` | 25| | |func-bytearray|_ | | :func:`getattr` | | :func:`next` | | |func-str|_ | 26| | |func-bytes|_ | | :func:`globals` | | | | :func:`sum` | 27| | | | | | **O** | | :func:`super` | 28| | **C** | | **H** | | :func:`object` | | | 29| | :func:`callable` | | :func:`hasattr` | | :func:`oct` | | **T** | 30| | :func:`chr` | | :func:`hash` | | :func:`open` | | |func-tuple|_ | 31| | :func:`classmethod` | | :func:`help` | | :func:`ord` | | :func:`type` | 32| | :func:`compile` | | :func:`hex` | | | | | 33| | :func:`complex` | | | | **P** | | **V** | 34| | | | **I** | | :func:`pow` | | :func:`vars` | 35| | **D** | | :func:`id` | | :func:`print` | | | 36| | :func:`delattr` | | :func:`input` | | :func:`property` | | **Z** | 37| | |func-dict|_ | | :func:`int` | | | | :func:`zip` | 38| | :func:`dir` | | :func:`isinstance` | | | | | 39| | :func:`divmod` | | :func:`issubclass` | | | | **_** | 40| | | | :func:`iter` | | | | :func:`__import__` | 41+-------------------------+-----------------------+-----------------------+-------------------------+ 42 43.. using :func:`dict` would create a link to another page, so local targets are 44 used, with replacement texts to make the output in the table consistent 45 46.. |func-dict| replace:: ``dict()`` 47.. |func-frozenset| replace:: ``frozenset()`` 48.. |func-memoryview| replace:: ``memoryview()`` 49.. |func-set| replace:: ``set()`` 50.. |func-list| replace:: ``list()`` 51.. |func-str| replace:: ``str()`` 52.. |func-tuple| replace:: ``tuple()`` 53.. |func-range| replace:: ``range()`` 54.. |func-bytearray| replace:: ``bytearray()`` 55.. |func-bytes| replace:: ``bytes()`` 56 57.. function:: abs(x) 58 59 Return the absolute value of a number. The argument may be an 60 integer, a floating-point number, or an object implementing 61 :meth:`~object.__abs__`. 62 If the argument is a complex number, its magnitude is returned. 63 64 65.. function:: aiter(async_iterable) 66 67 Return an :term:`asynchronous iterator` for an :term:`asynchronous iterable`. 68 Equivalent to calling ``x.__aiter__()``. 69 70 Note: Unlike :func:`iter`, :func:`aiter` has no 2-argument variant. 71 72 .. versionadded:: 3.10 73 74.. function:: all(iterable) 75 76 Return ``True`` if all elements of the *iterable* are true (or if the iterable 77 is empty). Equivalent to:: 78 79 def all(iterable): 80 for element in iterable: 81 if not element: 82 return False 83 return True 84 85 86.. awaitablefunction:: anext(async_iterator) 87 anext(async_iterator, default) 88 89 When awaited, return the next item from the given :term:`asynchronous 90 iterator`, or *default* if given and the iterator is exhausted. 91 92 This is the async variant of the :func:`next` builtin, and behaves 93 similarly. 94 95 This calls the :meth:`~object.__anext__` method of *async_iterator*, 96 returning an :term:`awaitable`. Awaiting this returns the next value of the 97 iterator. If *default* is given, it is returned if the iterator is exhausted, 98 otherwise :exc:`StopAsyncIteration` is raised. 99 100 .. versionadded:: 3.10 101 102.. function:: any(iterable) 103 104 Return ``True`` if any element of the *iterable* is true. If the iterable 105 is empty, return ``False``. Equivalent to:: 106 107 def any(iterable): 108 for element in iterable: 109 if element: 110 return True 111 return False 112 113 114.. function:: ascii(object) 115 116 As :func:`repr`, return a string containing a printable representation of an 117 object, but escape the non-ASCII characters in the string returned by 118 :func:`repr` using ``\x``, ``\u``, or ``\U`` escapes. This generates a string 119 similar to that returned by :func:`repr` in Python 2. 120 121 122.. function:: bin(x) 123 124 Convert an integer number to a binary string prefixed with "0b". The result 125 is a valid Python expression. If *x* is not a Python :class:`int` object, it 126 has to define an :meth:`~object.__index__` method that returns an integer. Some 127 examples: 128 129 >>> bin(3) 130 '0b11' 131 >>> bin(-10) 132 '-0b1010' 133 134 If the prefix "0b" is desired or not, you can use either of the following ways. 135 136 >>> format(14, '#b'), format(14, 'b') 137 ('0b1110', '1110') 138 >>> f'{14:#b}', f'{14:b}' 139 ('0b1110', '1110') 140 141 See also :func:`format` for more information. 142 143 144.. class:: bool(object=False, /) 145 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 149 or omitted, this returns ``False``; otherwise, it returns ``True``. The 150 :class:`bool` class is a subclass of :class:`int` (see :ref:`typesnumeric`). 151 It cannot be subclassed further. Its only instances are ``False`` and 152 ``True`` (see :ref:`typebool`). 153 154 .. index:: pair: Boolean; type 155 156 .. versionchanged:: 3.7 157 The parameter is now positional-only. 158 159.. function:: breakpoint(*args, **kws) 160 161 This function drops you into the debugger at the call site. Specifically, 162 it calls :func:`sys.breakpointhook`, passing ``args`` and ``kws`` straight 163 through. By default, ``sys.breakpointhook()`` calls 164 :func:`pdb.set_trace` expecting no arguments. In this case, it is 165 purely a convenience function so you don't have to explicitly import 166 :mod:`pdb` or type as much code to enter the debugger. However, 167 :func:`sys.breakpointhook` can be set to some other function and 168 :func:`breakpoint` will automatically call that, allowing you to drop into 169 the debugger of choice. 170 If :func:`sys.breakpointhook` is not accessible, this function will 171 raise :exc:`RuntimeError`. 172 173 By default, the behavior of :func:`breakpoint` can be changed with 174 the :envvar:`PYTHONBREAKPOINT` environment variable. 175 See :func:`sys.breakpointhook` for usage details. 176 177 Note that this is not guaranteed if :func:`sys.breakpointhook` 178 has been replaced. 179 180 .. audit-event:: builtins.breakpoint breakpointhook breakpoint 181 182 .. versionadded:: 3.7 183 184.. _func-bytearray: 185.. class:: bytearray(source=b'') 186 bytearray(source, encoding) 187 bytearray(source, encoding, errors) 188 :noindex: 189 190 Return a new array of bytes. The :class:`bytearray` class is a mutable 191 sequence of integers in the range 0 <= x < 256. It has most of the usual 192 methods of mutable sequences, described in :ref:`typesseq-mutable`, as well 193 as most methods that the :class:`bytes` type has, see :ref:`bytes-methods`. 194 195 The optional *source* parameter can be used to initialize the array in a few 196 different ways: 197 198 * If it is a *string*, you must also give the *encoding* (and optionally, 199 *errors*) parameters; :func:`bytearray` then converts the string to 200 bytes using :meth:`str.encode`. 201 202 * If it is an *integer*, the array will have that size and will be 203 initialized with null bytes. 204 205 * If it is an object conforming to the :ref:`buffer interface <bufferobjects>`, 206 a read-only buffer of the object will be used to initialize the bytes array. 207 208 * If it is an *iterable*, it must be an iterable of integers in the range 209 ``0 <= x < 256``, which are used as the initial contents of the array. 210 211 Without an argument, an array of size 0 is created. 212 213 See also :ref:`binaryseq` and :ref:`typebytearray`. 214 215 216.. _func-bytes: 217.. class:: bytes(source=b'') 218 bytes(source, encoding) 219 bytes(source, encoding, errors) 220 :noindex: 221 222 Return a new "bytes" object which is an immutable sequence of integers in 223 the range ``0 <= x < 256``. :class:`bytes` is an immutable version of 224 :class:`bytearray` -- it has the same non-mutating methods and the same 225 indexing and slicing behavior. 226 227 Accordingly, constructor arguments are interpreted as for :func:`bytearray`. 228 229 Bytes objects can also be created with literals, see :ref:`strings`. 230 231 See also :ref:`binaryseq`, :ref:`typebytes`, and :ref:`bytes-methods`. 232 233 234.. function:: callable(object) 235 236 Return :const:`True` if the *object* argument appears callable, 237 :const:`False` if not. If this returns ``True``, it is still possible that a 238 call fails, but if it is ``False``, calling *object* will never succeed. 239 Note that classes are callable (calling a class returns a new instance); 240 instances are callable if their class has a :meth:`~object.__call__` method. 241 242 .. versionadded:: 3.2 243 This function was first removed in Python 3.0 and then brought back 244 in Python 3.2. 245 246 247.. function:: chr(i) 248 249 Return the string representing a character whose Unicode code point is the 250 integer *i*. For example, ``chr(97)`` returns the string ``'a'``, while 251 ``chr(8364)`` returns the string ``'€'``. This is the inverse of :func:`ord`. 252 253 The valid range for the argument is from 0 through 1,114,111 (0x10FFFF in 254 base 16). :exc:`ValueError` will be raised if *i* is outside that range. 255 256 257.. decorator:: classmethod 258 259 Transform a method into a class method. 260 261 A class method receives the class as an implicit first argument, just like an 262 instance method receives the instance. To declare a class method, use this 263 idiom:: 264 265 class C: 266 @classmethod 267 def f(cls, arg1, arg2): ... 268 269 The ``@classmethod`` form is a function :term:`decorator` -- see 270 :ref:`function` for details. 271 272 A class method can be called either on the class (such as ``C.f()``) or on an instance (such 273 as ``C().f()``). The instance is ignored except for its class. If a class 274 method is called for a derived class, the derived class object is passed as the 275 implied first argument. 276 277 Class methods are different than C++ or Java static methods. If you want those, 278 see :func:`staticmethod` in this section. 279 For more information on class methods, see :ref:`types`. 280 281 .. versionchanged:: 3.9 282 Class methods can now wrap other :term:`descriptors <descriptor>` such as 283 :func:`property`. 284 285 .. versionchanged:: 3.10 286 Class methods now inherit the method attributes 287 (:attr:`~function.__module__`, :attr:`~function.__name__`, 288 :attr:`~function.__qualname__`, :attr:`~function.__doc__` and 289 :attr:`~function.__annotations__`) and have a new ``__wrapped__`` 290 attribute. 291 292 .. deprecated-removed:: 3.11 3.13 293 Class methods can no longer wrap other :term:`descriptors <descriptor>` such as 294 :func:`property`. 295 296 297.. function:: compile(source, filename, mode, flags=0, dont_inherit=False, optimize=-1) 298 299 Compile the *source* into a code or AST object. Code objects can be executed 300 by :func:`exec` or :func:`eval`. *source* can either be a normal string, a 301 byte string, or an AST object. Refer to the :mod:`ast` module documentation 302 for information on how to work with AST objects. 303 304 The *filename* argument should give the file from which the code was read; 305 pass some recognizable value if it wasn't read from a file (``'<string>'`` is 306 commonly used). 307 308 The *mode* argument specifies what kind of code must be compiled; it can be 309 ``'exec'`` if *source* consists of a sequence of statements, ``'eval'`` if it 310 consists of a single expression, or ``'single'`` if it consists of a single 311 interactive statement (in the latter case, expression statements that 312 evaluate to something other than ``None`` will be printed). 313 314 The optional arguments *flags* and *dont_inherit* control which 315 :ref:`compiler options <ast-compiler-flags>` should be activated 316 and which :ref:`future features <future>` should be allowed. If neither 317 is present (or both are zero) the code is compiled with the same flags that 318 affect the code that is calling :func:`compile`. If the *flags* 319 argument is given and *dont_inherit* is not (or is zero) then the compiler 320 options and the future statements specified by the *flags* argument are used 321 in addition to those that would be used anyway. If *dont_inherit* is a 322 non-zero integer then the *flags* argument is it -- the flags (future 323 features and compiler options) in the surrounding code are ignored. 324 325 Compiler options and future statements are specified by bits which can be 326 bitwise ORed together to specify multiple options. The bitfield required to 327 specify a given future feature can be found as the 328 :attr:`~__future__._Feature.compiler_flag` attribute on the 329 :class:`~__future__._Feature` instance in the :mod:`__future__` module. 330 :ref:`Compiler flags <ast-compiler-flags>` can be found in :mod:`ast` 331 module, with ``PyCF_`` prefix. 332 333 The argument *optimize* specifies the optimization level of the compiler; the 334 default value of ``-1`` selects the optimization level of the interpreter as 335 given by :option:`-O` options. Explicit levels are ``0`` (no optimization; 336 ``__debug__`` is true), ``1`` (asserts are removed, ``__debug__`` is false) 337 or ``2`` (docstrings are removed too). 338 339 This function raises :exc:`SyntaxError` if the compiled source is invalid, 340 and :exc:`ValueError` if the source contains null bytes. 341 342 If you want to parse Python code into its AST representation, see 343 :func:`ast.parse`. 344 345 .. audit-event:: compile source,filename compile 346 347 Raises an :ref:`auditing event <auditing>` ``compile`` with arguments 348 ``source`` and ``filename``. This event may also be raised by implicit 349 compilation. 350 351 .. note:: 352 353 When compiling a string with multi-line code in ``'single'`` or 354 ``'eval'`` mode, input must be terminated by at least one newline 355 character. This is to facilitate detection of incomplete and complete 356 statements in the :mod:`code` module. 357 358 .. warning:: 359 360 It is possible to crash the Python interpreter with a 361 sufficiently large/complex string when compiling to an AST 362 object due to stack depth limitations in Python's AST compiler. 363 364 .. versionchanged:: 3.2 365 Allowed use of Windows and Mac newlines. Also, input in ``'exec'`` mode 366 does not have to end in a newline anymore. Added the *optimize* parameter. 367 368 .. versionchanged:: 3.5 369 Previously, :exc:`TypeError` was raised when null bytes were encountered 370 in *source*. 371 372 .. versionadded:: 3.8 373 ``ast.PyCF_ALLOW_TOP_LEVEL_AWAIT`` can now be passed in flags to enable 374 support for top-level ``await``, ``async for``, and ``async with``. 375 376 377.. class:: complex(number=0, /) 378 complex(string, /) 379 complex(real=0, imag=0) 380 381 Convert a single string or number to a complex number, or create a 382 complex number from real and imaginary parts. 383 384 Examples: 385 386 .. doctest:: 387 388 >>> complex('+1.23') 389 (1.23+0j) 390 >>> complex('-4.5j') 391 -4.5j 392 >>> complex('-1.23+4.5j') 393 (-1.23+4.5j) 394 >>> complex('\t( -1.23+4.5J )\n') 395 (-1.23+4.5j) 396 >>> complex('-Infinity+NaNj') 397 (-inf+nanj) 398 >>> complex(1.23) 399 (1.23+0j) 400 >>> complex(imag=-4.5) 401 -4.5j 402 >>> complex(-1.23, 4.5) 403 (-1.23+4.5j) 404 405 If the argument is a string, it must contain either a real part (in the 406 same format as for :func:`float`) or an imaginary part (in the same 407 format but with a ``'j'`` or ``'J'`` suffix), or both real and imaginary 408 parts (the sign of the imaginary part is mandatory in this case). 409 The string can optionally be surrounded by whitespaces and the round 410 parentheses ``'('`` and ``')'``, which are ignored. 411 The string must not contain whitespace between ``'+'``, ``'-'``, the 412 ``'j'`` or ``'J'`` suffix, and the decimal number. 413 For example, ``complex('1+2j')`` is fine, but ``complex('1 + 2j')`` raises 414 :exc:`ValueError`. 415 More precisely, the input must conform to the :token:`~float:complexvalue` 416 production rule in the following grammar, after parentheses and leading and 417 trailing whitespace characters are removed: 418 419 .. productionlist:: float 420 complexvalue: `floatvalue` | 421 : `floatvalue` ("j" | "J") | 422 : `floatvalue` `sign` `absfloatvalue` ("j" | "J") 423 424 If the argument is a number, the constructor serves as a numeric 425 conversion like :class:`int` and :class:`float`. 426 For a general Python object ``x``, ``complex(x)`` delegates to 427 ``x.__complex__()``. 428 If :meth:`~object.__complex__` is not defined then it falls back 429 to :meth:`~object.__float__`. 430 If :meth:`!__float__` is not defined then it falls back 431 to :meth:`~object.__index__`. 432 433 If two arguments are provided or keyword arguments are used, each argument 434 may be any numeric type (including complex). 435 If both arguments are real numbers, return a complex number with the real 436 component *real* and the imaginary component *imag*. 437 If both arguments are complex numbers, return a complex number with the real 438 component ``real.real-imag.imag`` and the imaginary component 439 ``real.imag+imag.real``. 440 If one of arguments is a real number, only its real component is used in 441 the above expressions. 442 443 If all arguments are omitted, returns ``0j``. 444 445 The complex type is described in :ref:`typesnumeric`. 446 447 .. versionchanged:: 3.6 448 Grouping digits with underscores as in code literals is allowed. 449 450 .. versionchanged:: 3.8 451 Falls back to :meth:`~object.__index__` if :meth:`~object.__complex__` and 452 :meth:`~object.__float__` are not defined. 453 454 455.. function:: delattr(object, name) 456 457 This is a relative of :func:`setattr`. The arguments are an object and a 458 string. The string must be the name of one of the object's attributes. The 459 function deletes the named attribute, provided the object allows it. For 460 example, ``delattr(x, 'foobar')`` is equivalent to ``del x.foobar``. 461 *name* need not be a Python identifier (see :func:`setattr`). 462 463 464.. _func-dict: 465.. class:: dict(**kwarg) 466 dict(mapping, **kwarg) 467 dict(iterable, **kwarg) 468 :noindex: 469 470 Create a new dictionary. The :class:`dict` object is the dictionary class. 471 See :class:`dict` and :ref:`typesmapping` for documentation about this class. 472 473 For other containers see the built-in :class:`list`, :class:`set`, and 474 :class:`tuple` classes, as well as the :mod:`collections` module. 475 476 477.. function:: dir() 478 dir(object) 479 480 Without arguments, return the list of names in the current local scope. With an 481 argument, attempt to return a list of valid attributes for that object. 482 483 If the object has a method named :meth:`~object.__dir__`, 484 this method will be called and 485 must return the list of attributes. This allows objects that implement a custom 486 :func:`~object.__getattr__` or :func:`~object.__getattribute__` function 487 to customize the way 488 :func:`dir` reports their attributes. 489 490 If the object does not provide :meth:`~object.__dir__`, 491 the function tries its best to gather information from the object's 492 :attr:`~object.__dict__` attribute, if defined, and 493 from its type object. The resulting list is not necessarily complete and may 494 be inaccurate when the object has a custom :func:`~object.__getattr__`. 495 496 The default :func:`dir` mechanism behaves differently with different types of 497 objects, as it attempts to produce the most relevant, rather than complete, 498 information: 499 500 * If the object is a module object, the list contains the names of the module's 501 attributes. 502 503 * If the object is a type or class object, the list contains the names of its 504 attributes, and recursively of the attributes of its bases. 505 506 * Otherwise, the list contains the object's attributes' names, the names of its 507 class's attributes, and recursively of the attributes of its class's base 508 classes. 509 510 The resulting list is sorted alphabetically. For example: 511 512 >>> import struct 513 >>> dir() # show the names in the module namespace # doctest: +SKIP 514 ['__builtins__', '__name__', 'struct'] 515 >>> dir(struct) # show the names in the struct module # doctest: +SKIP 516 ['Struct', '__all__', '__builtins__', '__cached__', '__doc__', '__file__', 517 '__initializing__', '__loader__', '__name__', '__package__', 518 '_clearcache', 'calcsize', 'error', 'pack', 'pack_into', 519 'unpack', 'unpack_from'] 520 >>> class Shape: 521 ... def __dir__(self): 522 ... return ['area', 'perimeter', 'location'] 523 ... 524 >>> s = Shape() 525 >>> dir(s) 526 ['area', 'location', 'perimeter'] 527 528 .. note:: 529 530 Because :func:`dir` is supplied primarily as a convenience for use at an 531 interactive prompt, it tries to supply an interesting set of names more 532 than it tries to supply a rigorously or consistently defined set of names, 533 and its detailed behavior may change across releases. For example, 534 metaclass attributes are not in the result list when the argument is a 535 class. 536 537 538.. function:: divmod(a, b) 539 540 Take two (non-complex) numbers as arguments and return a pair of numbers 541 consisting of their quotient and remainder when using integer division. With 542 mixed operand types, the rules for binary arithmetic operators apply. For 543 integers, the result is the same as ``(a // b, a % b)``. For floating-point 544 numbers the result is ``(q, a % b)``, where *q* is usually ``math.floor(a / 545 b)`` but may be 1 less than that. In any case ``q * b + a % b`` is very 546 close to *a*, if ``a % b`` is non-zero it has the same sign as *b*, and ``0 547 <= abs(a % b) < abs(b)``. 548 549 550.. function:: enumerate(iterable, start=0) 551 552 Return an enumerate object. *iterable* must be a sequence, an 553 :term:`iterator`, or some other object which supports iteration. 554 The :meth:`~iterator.__next__` method of the iterator returned by 555 :func:`enumerate` returns a tuple containing a count (from *start* which 556 defaults to 0) and the values obtained from iterating over *iterable*. 557 558 >>> seasons = ['Spring', 'Summer', 'Fall', 'Winter'] 559 >>> list(enumerate(seasons)) 560 [(0, 'Spring'), (1, 'Summer'), (2, 'Fall'), (3, 'Winter')] 561 >>> list(enumerate(seasons, start=1)) 562 [(1, 'Spring'), (2, 'Summer'), (3, 'Fall'), (4, 'Winter')] 563 564 Equivalent to:: 565 566 def enumerate(iterable, start=0): 567 n = start 568 for elem in iterable: 569 yield n, elem 570 n += 1 571 572.. _func-eval: 573 574.. function:: eval(source, /, globals=None, locals=None) 575 576 :param source: 577 A Python expression. 578 :type source: :class:`str` | :ref:`code object <code-objects>` 579 580 :param globals: 581 The global namespace (default: ``None``). 582 :type globals: :class:`dict` | ``None`` 583 584 :param locals: 585 The local namespace (default: ``None``). 586 :type locals: :term:`mapping` | ``None`` 587 588 :returns: The result of the evaluated expression. 589 :raises: Syntax errors are reported as exceptions. 590 591 .. warning:: 592 593 This function executes arbitrary code. Calling it with 594 user-supplied input may lead to security vulnerabilities. 595 596 The *expression* argument is parsed and evaluated as a Python expression 597 (technically speaking, a condition list) using the *globals* and *locals* 598 mappings as global and local namespace. If the *globals* dictionary is 599 present and does not contain a value for the key ``__builtins__``, a 600 reference to the dictionary of the built-in module :mod:`builtins` is 601 inserted under that key before *expression* is parsed. That way you can 602 control what builtins are available to the executed code by inserting your 603 own ``__builtins__`` dictionary into *globals* before passing it to 604 :func:`eval`. If the *locals* mapping is omitted it defaults to the 605 *globals* dictionary. If both mappings are omitted, the expression is 606 executed with the *globals* and *locals* in the environment where 607 :func:`eval` is called. Note, *eval()* will only have access to the 608 :term:`nested scopes <nested scope>` (non-locals) in the enclosing 609 environment if they are already referenced in the scope that is calling 610 :func:`eval` (e.g. via a :keyword:`nonlocal` statement). 611 612 Example: 613 614 >>> x = 1 615 >>> eval('x+1') 616 2 617 618 This function can also be used to execute arbitrary code objects (such as 619 those created by :func:`compile`). In this case, pass a code object instead 620 of a string. If the code object has been compiled with ``'exec'`` as the 621 *mode* argument, :func:`eval`\'s return value will be ``None``. 622 623 Hints: dynamic execution of statements is supported by the :func:`exec` 624 function. The :func:`globals` and :func:`locals` functions 625 return the current global and local dictionary, respectively, which may be 626 useful to pass around for use by :func:`eval` or :func:`exec`. 627 628 If the given source is a string, then leading and trailing spaces and tabs 629 are stripped. 630 631 See :func:`ast.literal_eval` for a function that can safely evaluate strings 632 with expressions containing only literals. 633 634 .. audit-event:: exec code_object eval 635 636 Raises an :ref:`auditing event <auditing>` ``exec`` with the code object 637 as the argument. Code compilation events may also be raised. 638 639 .. versionchanged:: 3.13 640 641 The *globals* and *locals* arguments can now be passed as keywords. 642 643 .. versionchanged:: 3.13 644 645 The semantics of the default *locals* namespace have been adjusted as 646 described for the :func:`locals` builtin. 647 648.. index:: pair: built-in function; exec 649 650.. function:: exec(source, /, globals=None, locals=None, *, closure=None) 651 652 .. warning:: 653 654 This function executes arbitrary code. Calling it with 655 user-supplied input may lead to security vulnerabilities. 656 657 This function supports dynamic execution of Python code. *source* must be 658 either a string or a code object. If it is a string, the string is parsed as 659 a suite of Python statements which is then executed (unless a syntax error 660 occurs). [#]_ If it is a code object, it is simply executed. In all cases, 661 the code that's executed is expected to be valid as file input (see the 662 section :ref:`file-input` in the Reference Manual). Be aware that the 663 :keyword:`nonlocal`, :keyword:`yield`, and :keyword:`return` 664 statements may not be used outside of 665 function definitions even within the context of code passed to the 666 :func:`exec` function. The return value is ``None``. 667 668 In all cases, if the optional parts are omitted, the code is executed in the 669 current scope. If only *globals* is provided, it must be a dictionary 670 (and not a subclass of dictionary), which 671 will be used for both the global and the local variables. If *globals* and 672 *locals* are given, they are used for the global and local variables, 673 respectively. If provided, *locals* can be any mapping object. Remember 674 that at the module level, globals and locals are the same dictionary. 675 676 .. note:: 677 678 When ``exec`` gets two separate objects as *globals* and *locals*, the 679 code will be executed as if it were embedded in a class definition. This 680 means functions and classes defined in the executed code will not be able 681 to access variables assigned at the top level (as the "top level" 682 variables are treated as class variables in a class definition). 683 684 If the *globals* dictionary does not contain a value for the key 685 ``__builtins__``, a reference to the dictionary of the built-in module 686 :mod:`builtins` is inserted under that key. That way you can control what 687 builtins are available to the executed code by inserting your own 688 ``__builtins__`` dictionary into *globals* before passing it to :func:`exec`. 689 690 The *closure* argument specifies a closure--a tuple of cellvars. 691 It's only valid when the *object* is a code object containing 692 :term:`free (closure) variables <closure variable>`. 693 The length of the tuple must exactly match the length of the code object's 694 :attr:`~codeobject.co_freevars` attribute. 695 696 .. audit-event:: exec code_object exec 697 698 Raises an :ref:`auditing event <auditing>` ``exec`` with the code object 699 as the argument. Code compilation events may also be raised. 700 701 .. note:: 702 703 The built-in functions :func:`globals` and :func:`locals` return the current 704 global and local namespace, respectively, which may be useful to pass around 705 for use as the second and third argument to :func:`exec`. 706 707 .. note:: 708 709 The default *locals* act as described for function :func:`locals` below. 710 Pass an explicit *locals* dictionary if you need to see effects of the 711 code on *locals* after function :func:`exec` returns. 712 713 .. versionchanged:: 3.11 714 Added the *closure* parameter. 715 716 .. versionchanged:: 3.13 717 718 The *globals* and *locals* arguments can now be passed as keywords. 719 720 .. versionchanged:: 3.13 721 722 The semantics of the default *locals* namespace have been adjusted as 723 described for the :func:`locals` builtin. 724 725 726.. function:: filter(function, iterable) 727 728 Construct an iterator from those elements of *iterable* for which *function* 729 is true. *iterable* may be either a sequence, a container which 730 supports iteration, or an iterator. If *function* is ``None``, the identity 731 function is assumed, that is, all elements of *iterable* that are false are 732 removed. 733 734 Note that ``filter(function, iterable)`` is equivalent to the generator 735 expression ``(item for item in iterable if function(item))`` if function is 736 not ``None`` and ``(item for item in iterable if item)`` if function is 737 ``None``. 738 739 See :func:`itertools.filterfalse` for the complementary function that returns 740 elements of *iterable* for which *function* is false. 741 742 743.. class:: float(number=0.0, /) 744 float(string, /) 745 746 .. index:: 747 single: NaN 748 single: Infinity 749 750 Return a floating-point number constructed from a number or a string. 751 752 Examples: 753 754 .. doctest:: 755 756 >>> float('+1.23') 757 1.23 758 >>> float(' -12345\n') 759 -12345.0 760 >>> float('1e-003') 761 0.001 762 >>> float('+1E6') 763 1000000.0 764 >>> float('-Infinity') 765 -inf 766 767 If the argument is a string, it should contain a decimal number, optionally 768 preceded by a sign, and optionally embedded in whitespace. The optional 769 sign may be ``'+'`` or ``'-'``; a ``'+'`` sign has no effect on the value 770 produced. The argument may also be a string representing a NaN 771 (not-a-number), or positive or negative infinity. 772 More precisely, the input must conform to the :token:`~float:floatvalue` 773 production rule in the following grammar, after leading and trailing 774 whitespace characters are removed: 775 776 .. productionlist:: float 777 sign: "+" | "-" 778 infinity: "Infinity" | "inf" 779 nan: "nan" 780 digit: <a Unicode decimal digit, i.e. characters in Unicode general category Nd> 781 digitpart: `digit` (["_"] `digit`)* 782 number: [`digitpart`] "." `digitpart` | `digitpart` ["."] 783 exponent: ("e" | "E") [`sign`] `digitpart` 784 floatnumber: `number` [`exponent`] 785 absfloatvalue: `floatnumber` | `infinity` | `nan` 786 floatvalue: [`sign`] `absfloatvalue` 787 788 Case is not significant, so, for example, "inf", "Inf", "INFINITY", and 789 "iNfINity" are all acceptable spellings for positive infinity. 790 791 Otherwise, if the argument is an integer or a floating-point number, a 792 floating-point number with the same value (within Python's floating-point 793 precision) is returned. If the argument is outside the range of a Python 794 float, an :exc:`OverflowError` will be raised. 795 796 For a general Python object ``x``, ``float(x)`` delegates to 797 ``x.__float__()``. If :meth:`~object.__float__` is not defined then it falls back 798 to :meth:`~object.__index__`. 799 800 If no argument is given, ``0.0`` is returned. 801 802 The float type is described in :ref:`typesnumeric`. 803 804 .. versionchanged:: 3.6 805 Grouping digits with underscores as in code literals is allowed. 806 807 .. versionchanged:: 3.7 808 The parameter is now positional-only. 809 810 .. versionchanged:: 3.8 811 Falls back to :meth:`~object.__index__` if :meth:`~object.__float__` is not defined. 812 813 814.. index:: 815 single: __format__ 816 single: string; format() (built-in function) 817 818.. function:: format(value, format_spec="") 819 820 Convert a *value* to a "formatted" representation, as controlled by 821 *format_spec*. The interpretation of *format_spec* will depend on the type 822 of the *value* argument; however, there is a standard formatting syntax that 823 is used by most built-in types: :ref:`formatspec`. 824 825 The default *format_spec* is an empty string which usually gives the same 826 effect as calling :func:`str(value) <str>`. 827 828 A call to ``format(value, format_spec)`` is translated to 829 ``type(value).__format__(value, format_spec)`` which bypasses the instance 830 dictionary when searching for the value's :meth:`~object.__format__` method. 831 A :exc:`TypeError` exception is raised if the method search reaches 832 :mod:`object` and the *format_spec* is non-empty, or if either the 833 *format_spec* or the return value are not strings. 834 835 .. versionchanged:: 3.4 836 ``object().__format__(format_spec)`` raises :exc:`TypeError` 837 if *format_spec* is not an empty string. 838 839 840.. _func-frozenset: 841.. class:: frozenset(iterable=set()) 842 :noindex: 843 844 Return a new :class:`frozenset` object, optionally with elements taken from 845 *iterable*. ``frozenset`` is a built-in class. See :class:`frozenset` and 846 :ref:`types-set` for documentation about this class. 847 848 For other containers see the built-in :class:`set`, :class:`list`, 849 :class:`tuple`, and :class:`dict` classes, as well as the :mod:`collections` 850 module. 851 852 853.. function:: getattr(object, name) 854 getattr(object, name, default) 855 856 Return the value of the named attribute of *object*. *name* must be a string. 857 If the string is the name of one of the object's attributes, the result is the 858 value of that attribute. For example, ``getattr(x, 'foobar')`` is equivalent to 859 ``x.foobar``. If the named attribute does not exist, *default* is returned if 860 provided, otherwise :exc:`AttributeError` is raised. 861 *name* need not be a Python identifier (see :func:`setattr`). 862 863 .. note:: 864 865 Since :ref:`private name mangling <private-name-mangling>` happens at 866 compilation time, one must manually mangle a private attribute's 867 (attributes with two leading underscores) name in order to retrieve it with 868 :func:`getattr`. 869 870 871.. function:: globals() 872 873 Return the dictionary implementing the current module namespace. For code within 874 functions, this is set when the function is defined and remains the same 875 regardless of where the function is called. 876 877 878.. function:: hasattr(object, name) 879 880 The arguments are an object and a string. The result is ``True`` if the 881 string is the name of one of the object's attributes, ``False`` if not. (This 882 is implemented by calling ``getattr(object, name)`` and seeing whether it 883 raises an :exc:`AttributeError` or not.) 884 885 886.. function:: hash(object) 887 888 Return the hash value of the object (if it has one). Hash values are 889 integers. They are used to quickly compare dictionary keys during a 890 dictionary lookup. Numeric values that compare equal have the same hash 891 value (even if they are of different types, as is the case for 1 and 1.0). 892 893 .. note:: 894 895 For objects with custom :meth:`~object.__hash__` methods, 896 note that :func:`hash` 897 truncates the return value based on the bit width of the host machine. 898 899.. function:: help() 900 help(request) 901 902 Invoke the built-in help system. (This function is intended for interactive 903 use.) If no argument is given, the interactive help system starts on the 904 interpreter console. If the argument is a string, then the string is looked up 905 as the name of a module, function, class, method, keyword, or documentation 906 topic, and a help page is printed on the console. If the argument is any other 907 kind of object, a help page on the object is generated. 908 909 Note that if a slash(/) appears in the parameter list of a function when 910 invoking :func:`help`, it means that the parameters prior to the slash are 911 positional-only. For more info, see 912 :ref:`the FAQ entry on positional-only parameters <faq-positional-only-arguments>`. 913 914 This function is added to the built-in namespace by the :mod:`site` module. 915 916 .. versionchanged:: 3.4 917 Changes to :mod:`pydoc` and :mod:`inspect` mean that the reported 918 signatures for callables are now more comprehensive and consistent. 919 920 921.. function:: hex(x) 922 923 Convert an integer number to a lowercase hexadecimal string prefixed with 924 "0x". If *x* is not a Python :class:`int` object, it has to define an 925 :meth:`~object.__index__` method that returns an integer. Some examples: 926 927 >>> hex(255) 928 '0xff' 929 >>> hex(-42) 930 '-0x2a' 931 932 If you want to convert an integer number to an uppercase or lower hexadecimal 933 string with prefix or not, you can use either of the following ways: 934 935 >>> '%#x' % 255, '%x' % 255, '%X' % 255 936 ('0xff', 'ff', 'FF') 937 >>> format(255, '#x'), format(255, 'x'), format(255, 'X') 938 ('0xff', 'ff', 'FF') 939 >>> f'{255:#x}', f'{255:x}', f'{255:X}' 940 ('0xff', 'ff', 'FF') 941 942 See also :func:`format` for more information. 943 944 See also :func:`int` for converting a hexadecimal string to an 945 integer using a base of 16. 946 947 .. note:: 948 949 To obtain a hexadecimal string representation for a float, use the 950 :meth:`float.hex` method. 951 952 953.. function:: id(object) 954 955 Return the "identity" of an object. This is an integer which 956 is guaranteed to be unique and constant for this object during its lifetime. 957 Two objects with non-overlapping lifetimes may have the same :func:`id` 958 value. 959 960 .. impl-detail:: This is the address of the object in memory. 961 962 .. audit-event:: builtins.id id id 963 964 965.. function:: input() 966 input(prompt) 967 968 If the *prompt* argument is present, it is written to standard output without 969 a trailing newline. The function then reads a line from input, converts it 970 to a string (stripping a trailing newline), and returns that. When EOF is 971 read, :exc:`EOFError` is raised. Example:: 972 973 >>> s = input('--> ') # doctest: +SKIP 974 --> Monty Python's Flying Circus 975 >>> s # doctest: +SKIP 976 "Monty Python's Flying Circus" 977 978 If the :mod:`readline` module was loaded, then :func:`input` will use it 979 to provide elaborate line editing and history features. 980 981 .. audit-event:: builtins.input prompt input 982 983 Raises an :ref:`auditing event <auditing>` ``builtins.input`` with 984 argument ``prompt`` before reading input 985 986 .. audit-event:: builtins.input/result result input 987 988 Raises an :ref:`auditing event <auditing>` ``builtins.input/result`` 989 with the result after successfully reading input. 990 991 992.. class:: int(number=0, /) 993 int(string, /, base=10) 994 995 Return an integer object constructed from a number or a string, or return 996 ``0`` if no arguments are given. 997 998 Examples: 999 1000 .. doctest:: 1001 1002 >>> int(123.45) 1003 123 1004 >>> int('123') 1005 123 1006 >>> int(' -12_345\n') 1007 -12345 1008 >>> int('FACE', 16) 1009 64206 1010 >>> int('0xface', 0) 1011 64206 1012 >>> int('01110011', base=2) 1013 115 1014 1015 If the argument defines :meth:`~object.__int__`, 1016 ``int(x)`` returns ``x.__int__()``. If the argument defines :meth:`~object.__index__`, 1017 it returns ``x.__index__()``. If the argument defines :meth:`~object.__trunc__`, 1018 it returns ``x.__trunc__()``. 1019 For floating-point numbers, this truncates towards zero. 1020 1021 If the argument is not a number or if *base* is given, then it must be a string, 1022 :class:`bytes`, or :class:`bytearray` instance representing an integer 1023 in radix *base*. Optionally, the string can be preceded by ``+`` or ``-`` 1024 (with no space in between), have leading zeros, be surrounded by whitespace, 1025 and have single underscores interspersed between digits. 1026 1027 A base-n integer string contains digits, each representing a value from 0 to 1028 n-1. The values 0--9 can be represented by any Unicode decimal digit. The 1029 values 10--35 can be represented by ``a`` to ``z`` (or ``A`` to ``Z``). The 1030 default *base* is 10. The allowed bases are 0 and 2--36. Base-2, -8, and -16 1031 strings can be optionally prefixed with ``0b``/``0B``, ``0o``/``0O``, or 1032 ``0x``/``0X``, as with integer literals in code. For base 0, the string is 1033 interpreted in a similar way to an :ref:`integer literal in code <integers>`, 1034 in that the actual base is 2, 8, 10, or 16 as determined by the prefix. Base 1035 0 also disallows leading zeros: ``int('010', 0)`` is not legal, while 1036 ``int('010')`` and ``int('010', 8)`` are. 1037 1038 The integer type is described in :ref:`typesnumeric`. 1039 1040 .. versionchanged:: 3.4 1041 If *base* is not an instance of :class:`int` and the *base* object has a 1042 :meth:`base.__index__ <object.__index__>` method, that method is called 1043 to obtain an integer for the base. Previous versions used 1044 :meth:`base.__int__ <object.__int__>` instead of :meth:`base.__index__ 1045 <object.__index__>`. 1046 1047 .. versionchanged:: 3.6 1048 Grouping digits with underscores as in code literals is allowed. 1049 1050 .. versionchanged:: 3.7 1051 The first parameter is now positional-only. 1052 1053 .. versionchanged:: 3.8 1054 Falls back to :meth:`~object.__index__` if :meth:`~object.__int__` is not defined. 1055 1056 .. versionchanged:: 3.11 1057 The delegation to :meth:`~object.__trunc__` is deprecated. 1058 1059 .. versionchanged:: 3.11 1060 :class:`int` string inputs and string representations can be limited to 1061 help avoid denial of service attacks. A :exc:`ValueError` is raised when 1062 the limit is exceeded while converting a string to an :class:`int` or 1063 when converting an :class:`int` into a string would exceed the limit. 1064 See the :ref:`integer string conversion length limitation 1065 <int_max_str_digits>` documentation. 1066 1067.. function:: isinstance(object, classinfo) 1068 1069 Return ``True`` if the *object* argument is an instance of the *classinfo* 1070 argument, or of a (direct, indirect, or :term:`virtual <abstract base 1071 class>`) subclass thereof. If *object* is not 1072 an object of the given type, the function always returns ``False``. 1073 If *classinfo* is a tuple of type objects (or recursively, other such 1074 tuples) or a :ref:`types-union` of multiple types, return ``True`` if 1075 *object* is an instance of any of the types. 1076 If *classinfo* is not a type or tuple of types and such tuples, 1077 a :exc:`TypeError` exception is raised. :exc:`TypeError` may not be 1078 raised for an invalid type if an earlier check succeeds. 1079 1080 .. versionchanged:: 3.10 1081 *classinfo* can be a :ref:`types-union`. 1082 1083 1084.. function:: issubclass(class, classinfo) 1085 1086 Return ``True`` if *class* is a subclass (direct, indirect, or :term:`virtual 1087 <abstract base class>`) of *classinfo*. A 1088 class is considered a subclass of itself. *classinfo* may be a tuple of class 1089 objects (or recursively, other such tuples) 1090 or a :ref:`types-union`, in which case return ``True`` if *class* is a 1091 subclass of any entry in *classinfo*. In any other case, a :exc:`TypeError` 1092 exception is raised. 1093 1094 .. versionchanged:: 3.10 1095 *classinfo* can be a :ref:`types-union`. 1096 1097 1098.. function:: iter(object) 1099 iter(object, sentinel) 1100 1101 Return an :term:`iterator` object. The first argument is interpreted very 1102 differently depending on the presence of the second argument. Without a 1103 second argument, *object* must be a collection object which supports the 1104 :term:`iterable` protocol (the :meth:`~object.__iter__` method), 1105 or it must support 1106 the sequence protocol (the :meth:`~object.__getitem__` method with integer arguments 1107 starting at ``0``). If it does not support either of those protocols, 1108 :exc:`TypeError` is raised. If the second argument, *sentinel*, is given, 1109 then *object* must be a callable object. The iterator created in this case 1110 will call *object* with no arguments for each call to its 1111 :meth:`~iterator.__next__` method; if the value returned is equal to 1112 *sentinel*, :exc:`StopIteration` will be raised, otherwise the value will 1113 be returned. 1114 1115 See also :ref:`typeiter`. 1116 1117 One useful application of the second form of :func:`iter` is to build a 1118 block-reader. For example, reading fixed-width blocks from a binary 1119 database file until the end of file is reached:: 1120 1121 from functools import partial 1122 with open('mydata.db', 'rb') as f: 1123 for block in iter(partial(f.read, 64), b''): 1124 process_block(block) 1125 1126 1127.. function:: len(s) 1128 1129 Return the length (the number of items) of an object. The argument may be a 1130 sequence (such as a string, bytes, tuple, list, or range) or a collection 1131 (such as a dictionary, set, or frozen set). 1132 1133 .. impl-detail:: 1134 1135 ``len`` raises :exc:`OverflowError` on lengths larger than 1136 :data:`sys.maxsize`, such as :class:`range(2 ** 100) <range>`. 1137 1138 1139.. _func-list: 1140.. class:: list() 1141 list(iterable) 1142 :noindex: 1143 1144 Rather than being a function, :class:`list` is actually a mutable 1145 sequence type, as documented in :ref:`typesseq-list` and :ref:`typesseq`. 1146 1147 1148.. function:: locals() 1149 1150 Return a mapping object representing the current local symbol table, with 1151 variable names as the keys, and their currently bound references as the 1152 values. 1153 1154 At module scope, as well as when using :func:`exec` or :func:`eval` with 1155 a single namespace, this function returns the same namespace as 1156 :func:`globals`. 1157 1158 At class scope, it returns the namespace that will be passed to the 1159 metaclass constructor. 1160 1161 When using ``exec()`` or ``eval()`` with separate local and global 1162 arguments, it returns the local namespace passed in to the function call. 1163 1164 In all of the above cases, each call to ``locals()`` in a given frame of 1165 execution will return the *same* mapping object. Changes made through 1166 the mapping object returned from ``locals()`` will be visible as assigned, 1167 reassigned, or deleted local variables, and assigning, reassigning, or 1168 deleting local variables will immediately affect the contents of the 1169 returned mapping object. 1170 1171 In an :term:`optimized scope` (including functions, generators, and 1172 coroutines), each call to ``locals()`` instead returns a fresh dictionary 1173 containing the current bindings of the function's local variables and any 1174 nonlocal cell references. In this case, name binding changes made via the 1175 returned dict are *not* written back to the corresponding local variables 1176 or nonlocal cell references, and assigning, reassigning, or deleting local 1177 variables and nonlocal cell references does *not* affect the contents 1178 of previously returned dictionaries. 1179 1180 Calling ``locals()`` as part of a comprehension in a function, generator, or 1181 coroutine is equivalent to calling it in the containing scope, except that 1182 the comprehension's initialised iteration variables will be included. In 1183 other scopes, it behaves as if the comprehension were running as a nested 1184 function. 1185 1186 Calling ``locals()`` as part of a generator expression is equivalent to 1187 calling it in a nested generator function. 1188 1189 .. versionchanged:: 3.12 1190 The behaviour of ``locals()`` in a comprehension has been updated as 1191 described in :pep:`709`. 1192 1193 .. versionchanged:: 3.13 1194 As part of :pep:`667`, the semantics of mutating the mapping objects 1195 returned from this function are now defined. The behavior in 1196 :term:`optimized scopes <optimized scope>` is now as described above. 1197 Aside from being defined, the behaviour in other scopes remains 1198 unchanged from previous versions. 1199 1200 1201.. function:: map(function, iterable, *iterables) 1202 1203 Return an iterator that applies *function* to every item of *iterable*, 1204 yielding the results. If additional *iterables* arguments are passed, 1205 *function* must take that many arguments and is applied to the items from all 1206 iterables in parallel. With multiple iterables, the iterator stops when the 1207 shortest iterable is exhausted. For cases where the function inputs are 1208 already arranged into argument tuples, see :func:`itertools.starmap`\. 1209 1210 1211.. function:: max(iterable, *, key=None) 1212 max(iterable, *, default, key=None) 1213 max(arg1, arg2, *args, key=None) 1214 1215 Return the largest item in an iterable or the largest of two or more 1216 arguments. 1217 1218 If one positional argument is provided, it should be an :term:`iterable`. 1219 The largest item in the iterable is returned. If two or more positional 1220 arguments are provided, the largest of the positional arguments is 1221 returned. 1222 1223 There are two optional keyword-only arguments. The *key* argument specifies 1224 a one-argument ordering function like that used for :meth:`list.sort`. The 1225 *default* argument specifies an object to return if the provided iterable is 1226 empty. If the iterable is empty and *default* is not provided, a 1227 :exc:`ValueError` is raised. 1228 1229 If multiple items are maximal, the function returns the first one 1230 encountered. This is consistent with other sort-stability preserving tools 1231 such as ``sorted(iterable, key=keyfunc, reverse=True)[0]`` and 1232 ``heapq.nlargest(1, iterable, key=keyfunc)``. 1233 1234 .. versionchanged:: 3.4 1235 Added the *default* keyword-only parameter. 1236 1237 .. versionchanged:: 3.8 1238 The *key* can be ``None``. 1239 1240 1241.. _func-memoryview: 1242.. class:: memoryview(object) 1243 :noindex: 1244 1245 Return a "memory view" object created from the given argument. See 1246 :ref:`typememoryview` for more information. 1247 1248 1249.. function:: min(iterable, *, key=None) 1250 min(iterable, *, default, key=None) 1251 min(arg1, arg2, *args, key=None) 1252 1253 Return the smallest item in an iterable or the smallest of two or more 1254 arguments. 1255 1256 If one positional argument is provided, it should be an :term:`iterable`. 1257 The smallest item in the iterable is returned. If two or more positional 1258 arguments are provided, the smallest of the positional arguments is 1259 returned. 1260 1261 There are two optional keyword-only arguments. The *key* argument specifies 1262 a one-argument ordering function like that used for :meth:`list.sort`. The 1263 *default* argument specifies an object to return if the provided iterable is 1264 empty. If the iterable is empty and *default* is not provided, a 1265 :exc:`ValueError` is raised. 1266 1267 If multiple items are minimal, the function returns the first one 1268 encountered. This is consistent with other sort-stability preserving tools 1269 such as ``sorted(iterable, key=keyfunc)[0]`` and ``heapq.nsmallest(1, 1270 iterable, key=keyfunc)``. 1271 1272 .. versionchanged:: 3.4 1273 Added the *default* keyword-only parameter. 1274 1275 .. versionchanged:: 3.8 1276 The *key* can be ``None``. 1277 1278 1279.. function:: next(iterator) 1280 next(iterator, default) 1281 1282 Retrieve the next item from the :term:`iterator` by calling its 1283 :meth:`~iterator.__next__` method. If *default* is given, it is returned 1284 if the iterator is exhausted, otherwise :exc:`StopIteration` is raised. 1285 1286 1287.. class:: object() 1288 1289 This is the ultimate base class of all other classes. It has methods 1290 that are common to all instances of Python classes. When the constructor 1291 is called, it returns a new featureless object. The constructor does not 1292 accept any arguments. 1293 1294 .. note:: 1295 1296 :class:`object` instances do *not* have :attr:`~object.__dict__` 1297 attributes, so you can't assign arbitrary attributes to an instance of 1298 :class:`object`. 1299 1300 1301.. function:: oct(x) 1302 1303 Convert an integer number to an octal string prefixed with "0o". The result 1304 is a valid Python expression. If *x* is not a Python :class:`int` object, it 1305 has to define an :meth:`~object.__index__` method that returns an integer. For 1306 example: 1307 1308 >>> oct(8) 1309 '0o10' 1310 >>> oct(-56) 1311 '-0o70' 1312 1313 If you want to convert an integer number to an octal string either with the prefix 1314 "0o" or not, you can use either of the following ways. 1315 1316 >>> '%#o' % 10, '%o' % 10 1317 ('0o12', '12') 1318 >>> format(10, '#o'), format(10, 'o') 1319 ('0o12', '12') 1320 >>> f'{10:#o}', f'{10:o}' 1321 ('0o12', '12') 1322 1323 See also :func:`format` for more information. 1324 1325.. index:: 1326 single: file object; open() built-in function 1327 1328.. function:: open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None) 1329 1330 Open *file* and return a corresponding :term:`file object`. If the file 1331 cannot be opened, an :exc:`OSError` is raised. See 1332 :ref:`tut-files` for more examples of how to use this function. 1333 1334 *file* is a :term:`path-like object` giving the pathname (absolute or 1335 relative to the current working directory) of the file to be opened or an 1336 integer file descriptor of the file to be wrapped. (If a file descriptor is 1337 given, it is closed when the returned I/O object is closed unless *closefd* 1338 is set to ``False``.) 1339 1340 *mode* is an optional string that specifies the mode in which the file is 1341 opened. It defaults to ``'r'`` which means open for reading in text mode. 1342 Other common values are ``'w'`` for writing (truncating the file if it 1343 already exists), ``'x'`` for exclusive creation, and ``'a'`` for appending 1344 (which on *some* Unix systems, means that *all* writes append to the end of 1345 the file regardless of the current seek position). In text mode, if 1346 *encoding* is not specified the encoding used is platform-dependent: 1347 :func:`locale.getencoding` is called to get the current locale encoding. 1348 (For reading and writing raw bytes use binary mode and leave 1349 *encoding* unspecified.) The available modes are: 1350 1351 .. _filemodes: 1352 1353 .. index:: 1354 pair: file; modes 1355 1356 ========= =============================================================== 1357 Character Meaning 1358 ========= =============================================================== 1359 ``'r'`` open for reading (default) 1360 ``'w'`` open for writing, truncating the file first 1361 ``'x'`` open for exclusive creation, failing if the file already exists 1362 ``'a'`` open for writing, appending to the end of file if it exists 1363 ``'b'`` binary mode 1364 ``'t'`` text mode (default) 1365 ``'+'`` open for updating (reading and writing) 1366 ========= =============================================================== 1367 1368 The default mode is ``'r'`` (open for reading text, a synonym of ``'rt'``). 1369 Modes ``'w+'`` and ``'w+b'`` open and truncate the file. Modes ``'r+'`` 1370 and ``'r+b'`` open the file with no truncation. 1371 1372 As mentioned in the :ref:`io-overview`, Python distinguishes between binary 1373 and text I/O. Files opened in binary mode (including ``'b'`` in the *mode* 1374 argument) return contents as :class:`bytes` objects without any decoding. In 1375 text mode (the default, or when ``'t'`` is included in the *mode* argument), 1376 the contents of the file are returned as :class:`str`, the bytes having been 1377 first decoded using a platform-dependent encoding or using the specified 1378 *encoding* if given. 1379 1380 .. note:: 1381 1382 Python doesn't depend on the underlying operating system's notion of text 1383 files; all the processing is done by Python itself, and is therefore 1384 platform-independent. 1385 1386 *buffering* is an optional integer used to set the buffering policy. Pass 0 1387 to switch buffering off (only allowed in binary mode), 1 to select line 1388 buffering (only usable when writing in text mode), and an integer > 1 to indicate the size 1389 in bytes of a fixed-size chunk buffer. Note that specifying a buffer size this 1390 way applies for binary buffered I/O, but ``TextIOWrapper`` (i.e., files opened 1391 with ``mode='r+'``) would have another buffering. To disable buffering in 1392 ``TextIOWrapper``, consider using the ``write_through`` flag for 1393 :func:`io.TextIOWrapper.reconfigure`. When no *buffering* argument is 1394 given, the default buffering policy works as follows: 1395 1396 * Binary files are buffered in fixed-size chunks; the size of the buffer is 1397 chosen using a heuristic trying to determine the underlying device's "block 1398 size" and falling back on :const:`io.DEFAULT_BUFFER_SIZE`. On many systems, 1399 the buffer will typically be 4096 or 8192 bytes long. 1400 1401 * "Interactive" text files (files for which :meth:`~io.IOBase.isatty` 1402 returns ``True``) use line buffering. Other text files use the policy 1403 described above for binary files. 1404 1405 *encoding* is the name of the encoding used to decode or encode the file. 1406 This should only be used in text mode. The default encoding is platform 1407 dependent (whatever :func:`locale.getencoding` returns), but any 1408 :term:`text encoding` supported by Python can be used. 1409 See the :mod:`codecs` module for the list of supported encodings. 1410 1411 *errors* is an optional string that specifies how encoding and decoding 1412 errors are to be handled—this cannot be used in binary mode. 1413 A variety of standard error handlers are available 1414 (listed under :ref:`error-handlers`), though any 1415 error handling name that has been registered with 1416 :func:`codecs.register_error` is also valid. The standard names 1417 include: 1418 1419 * ``'strict'`` to raise a :exc:`ValueError` exception if there is 1420 an encoding error. The default value of ``None`` has the same 1421 effect. 1422 1423 * ``'ignore'`` ignores errors. Note that ignoring encoding errors 1424 can lead to data loss. 1425 1426 * ``'replace'`` causes a replacement marker (such as ``'?'``) to be inserted 1427 where there is malformed data. 1428 1429 * ``'surrogateescape'`` will represent any incorrect bytes as low 1430 surrogate code units ranging from U+DC80 to U+DCFF. 1431 These surrogate code units will then be turned back into 1432 the same bytes when the ``surrogateescape`` error handler is used 1433 when writing data. This is useful for processing files in an 1434 unknown encoding. 1435 1436 * ``'xmlcharrefreplace'`` is only supported when writing to a file. 1437 Characters not supported by the encoding are replaced with the 1438 appropriate XML character reference :samp:`&#{nnn};`. 1439 1440 * ``'backslashreplace'`` replaces malformed data by Python's backslashed 1441 escape sequences. 1442 1443 * ``'namereplace'`` (also only supported when writing) 1444 replaces unsupported characters with ``\N{...}`` escape sequences. 1445 1446 .. index:: 1447 single: universal newlines; open() built-in function 1448 1449 .. _open-newline-parameter: 1450 1451 *newline* determines how to parse newline characters from the stream. 1452 It can be ``None``, ``''``, ``'\n'``, ``'\r'``, and 1453 ``'\r\n'``. It works as follows: 1454 1455 * When reading input from the stream, if *newline* is ``None``, universal 1456 newlines mode is enabled. Lines in the input can end in ``'\n'``, 1457 ``'\r'``, or ``'\r\n'``, and these are translated into ``'\n'`` before 1458 being returned to the caller. If it is ``''``, universal newlines mode is 1459 enabled, but line endings are returned to the caller untranslated. If it 1460 has any of the other legal values, input lines are only terminated by the 1461 given string, and the line ending is returned to the caller untranslated. 1462 1463 * When writing output to the stream, if *newline* is ``None``, any ``'\n'`` 1464 characters written are translated to the system default line separator, 1465 :data:`os.linesep`. If *newline* is ``''`` or ``'\n'``, no translation 1466 takes place. If *newline* is any of the other legal values, any ``'\n'`` 1467 characters written are translated to the given string. 1468 1469 If *closefd* is ``False`` and a file descriptor rather than a filename was 1470 given, the underlying file descriptor will be kept open when the file is 1471 closed. If a filename is given *closefd* must be ``True`` (the default); 1472 otherwise, an error will be raised. 1473 1474 A custom opener can be used by passing a callable as *opener*. The underlying 1475 file descriptor for the file object is then obtained by calling *opener* with 1476 (*file*, *flags*). *opener* must return an open file descriptor (passing 1477 :mod:`os.open` as *opener* results in functionality similar to passing 1478 ``None``). 1479 1480 The newly created file is :ref:`non-inheritable <fd_inheritance>`. 1481 1482 The following example uses the :ref:`dir_fd <dir_fd>` parameter of the 1483 :func:`os.open` function to open a file relative to a given directory:: 1484 1485 >>> import os 1486 >>> dir_fd = os.open('somedir', os.O_RDONLY) 1487 >>> def opener(path, flags): 1488 ... return os.open(path, flags, dir_fd=dir_fd) 1489 ... 1490 >>> with open('spamspam.txt', 'w', opener=opener) as f: 1491 ... print('This will be written to somedir/spamspam.txt', file=f) 1492 ... 1493 >>> os.close(dir_fd) # don't leak a file descriptor 1494 1495 The type of :term:`file object` returned by the :func:`open` function 1496 depends on the mode. When :func:`open` is used to open a file in a text 1497 mode (``'w'``, ``'r'``, ``'wt'``, ``'rt'``, etc.), it returns a subclass of 1498 :class:`io.TextIOBase` (specifically :class:`io.TextIOWrapper`). When used 1499 to open a file in a binary mode with buffering, the returned class is a 1500 subclass of :class:`io.BufferedIOBase`. The exact class varies: in read 1501 binary mode, it returns an :class:`io.BufferedReader`; in write binary and 1502 append binary modes, it returns an :class:`io.BufferedWriter`, and in 1503 read/write mode, it returns an :class:`io.BufferedRandom`. When buffering is 1504 disabled, the raw stream, a subclass of :class:`io.RawIOBase`, 1505 :class:`io.FileIO`, is returned. 1506 1507 .. index:: 1508 single: line-buffered I/O 1509 single: unbuffered I/O 1510 single: buffer size, I/O 1511 single: I/O control; buffering 1512 single: binary mode 1513 single: text mode 1514 pair: module; sys 1515 1516 See also the file handling modules, such as :mod:`fileinput`, :mod:`io` 1517 (where :func:`open` is declared), :mod:`os`, :mod:`os.path`, :mod:`tempfile`, 1518 and :mod:`shutil`. 1519 1520 .. audit-event:: open path,mode,flags open 1521 1522 The ``mode`` and ``flags`` arguments may have been modified or inferred from 1523 the original call. 1524 1525 .. versionchanged:: 3.3 1526 1527 * The *opener* parameter was added. 1528 * The ``'x'`` mode was added. 1529 * :exc:`IOError` used to be raised, it is now an alias of :exc:`OSError`. 1530 * :exc:`FileExistsError` is now raised if the file opened in exclusive 1531 creation mode (``'x'``) already exists. 1532 1533 .. versionchanged:: 3.4 1534 1535 * The file is now non-inheritable. 1536 1537 .. versionchanged:: 3.5 1538 1539 * If the system call is interrupted and the signal handler does not raise an 1540 exception, the function now retries the system call instead of raising an 1541 :exc:`InterruptedError` exception (see :pep:`475` for the rationale). 1542 * The ``'namereplace'`` error handler was added. 1543 1544 .. versionchanged:: 3.6 1545 1546 * Support added to accept objects implementing :class:`os.PathLike`. 1547 * On Windows, opening a console buffer may return a subclass of 1548 :class:`io.RawIOBase` other than :class:`io.FileIO`. 1549 1550 .. versionchanged:: 3.11 1551 The ``'U'`` mode has been removed. 1552 1553.. function:: ord(c) 1554 1555 Given a string representing one Unicode character, return an integer 1556 representing the Unicode code point of that character. For example, 1557 ``ord('a')`` returns the integer ``97`` and ``ord('€')`` (Euro sign) 1558 returns ``8364``. This is the inverse of :func:`chr`. 1559 1560 1561.. function:: pow(base, exp, mod=None) 1562 1563 Return *base* to the power *exp*; if *mod* is present, return *base* to the 1564 power *exp*, modulo *mod* (computed more efficiently than 1565 ``pow(base, exp) % mod``). The two-argument form ``pow(base, exp)`` is 1566 equivalent to using the power operator: ``base**exp``. 1567 1568 The arguments must have numeric types. With mixed operand types, the 1569 coercion rules for binary arithmetic operators apply. For :class:`int` 1570 operands, the result has the same type as the operands (after coercion) 1571 unless the second argument is negative; in that case, all arguments are 1572 converted to float and a float result is delivered. For example, ``pow(10, 2)`` 1573 returns ``100``, but ``pow(10, -2)`` returns ``0.01``. For a negative base of 1574 type :class:`int` or :class:`float` and a non-integral exponent, a complex 1575 result is delivered. For example, ``pow(-9, 0.5)`` returns a value close 1576 to ``3j``. Whereas, for a negative base of type :class:`int` or :class:`float` 1577 with an integral exponent, a float result is delivered. For example, 1578 ``pow(-9, 2.0)`` returns ``81.0``. 1579 1580 For :class:`int` operands *base* and *exp*, if *mod* is present, *mod* must 1581 also be of integer type and *mod* must be nonzero. If *mod* is present and 1582 *exp* is negative, *base* must be relatively prime to *mod*. In that case, 1583 ``pow(inv_base, -exp, mod)`` is returned, where *inv_base* is an inverse to 1584 *base* modulo *mod*. 1585 1586 Here's an example of computing an inverse for ``38`` modulo ``97``:: 1587 1588 >>> pow(38, -1, mod=97) 1589 23 1590 >>> 23 * 38 % 97 == 1 1591 True 1592 1593 .. versionchanged:: 3.8 1594 For :class:`int` operands, the three-argument form of ``pow`` now allows 1595 the second argument to be negative, permitting computation of modular 1596 inverses. 1597 1598 .. versionchanged:: 3.8 1599 Allow keyword arguments. Formerly, only positional arguments were 1600 supported. 1601 1602 1603.. function:: print(*objects, sep=' ', end='\n', file=None, flush=False) 1604 1605 Print *objects* to the text stream *file*, separated by *sep* and followed 1606 by *end*. *sep*, *end*, *file*, and *flush*, if present, must be given as keyword 1607 arguments. 1608 1609 All non-keyword arguments are converted to strings like :func:`str` does and 1610 written to the stream, separated by *sep* and followed by *end*. Both *sep* 1611 and *end* must be strings; they can also be ``None``, which means to use the 1612 default values. If no *objects* are given, :func:`print` will just write 1613 *end*. 1614 1615 The *file* argument must be an object with a ``write(string)`` method; if it 1616 is not present or ``None``, :data:`sys.stdout` will be used. Since printed 1617 arguments are converted to text strings, :func:`print` cannot be used with 1618 binary mode file objects. For these, use ``file.write(...)`` instead. 1619 1620 Output buffering is usually determined by *file*. 1621 However, if *flush* is true, the stream is forcibly flushed. 1622 1623 1624 .. versionchanged:: 3.3 1625 Added the *flush* keyword argument. 1626 1627 1628.. class:: property(fget=None, fset=None, fdel=None, doc=None) 1629 1630 Return a property attribute. 1631 1632 *fget* is a function for getting an attribute value. *fset* is a function 1633 for setting an attribute value. *fdel* is a function for deleting an attribute 1634 value. And *doc* creates a docstring for the attribute. 1635 1636 A typical use is to define a managed attribute ``x``:: 1637 1638 class C: 1639 def __init__(self): 1640 self._x = None 1641 1642 def getx(self): 1643 return self._x 1644 1645 def setx(self, value): 1646 self._x = value 1647 1648 def delx(self): 1649 del self._x 1650 1651 x = property(getx, setx, delx, "I'm the 'x' property.") 1652 1653 If *c* is an instance of *C*, ``c.x`` will invoke the getter, 1654 ``c.x = value`` will invoke the setter, and ``del c.x`` the deleter. 1655 1656 If given, *doc* will be the docstring of the property attribute. Otherwise, the 1657 property will copy *fget*'s docstring (if it exists). This makes it possible to 1658 create read-only properties easily using :func:`property` as a :term:`decorator`:: 1659 1660 class Parrot: 1661 def __init__(self): 1662 self._voltage = 100000 1663 1664 @property 1665 def voltage(self): 1666 """Get the current voltage.""" 1667 return self._voltage 1668 1669 The ``@property`` decorator turns the :meth:`!voltage` method into a "getter" 1670 for a read-only attribute with the same name, and it sets the docstring for 1671 *voltage* to "Get the current voltage." 1672 1673 .. decorator:: property.getter 1674 .. decorator:: property.setter 1675 .. decorator:: property.deleter 1676 1677 A property object has ``getter``, ``setter``, 1678 and ``deleter`` methods usable as decorators that create a 1679 copy of the property with the corresponding accessor function set to the 1680 decorated function. This is best explained with an example: 1681 1682 .. testcode:: 1683 1684 class C: 1685 def __init__(self): 1686 self._x = None 1687 1688 @property 1689 def x(self): 1690 """I'm the 'x' property.""" 1691 return self._x 1692 1693 @x.setter 1694 def x(self, value): 1695 self._x = value 1696 1697 @x.deleter 1698 def x(self): 1699 del self._x 1700 1701 This code is exactly equivalent to the first example. Be sure to give the 1702 additional functions the same name as the original property (``x`` in this 1703 case.) 1704 1705 The returned property object also has the attributes ``fget``, ``fset``, and 1706 ``fdel`` corresponding to the constructor arguments. 1707 1708 .. versionchanged:: 3.5 1709 The docstrings of property objects are now writeable. 1710 1711 .. attribute:: __name__ 1712 1713 Attribute holding the name of the property. The name of the property 1714 can be changed at runtime. 1715 1716 .. versionadded:: 3.13 1717 1718 1719.. _func-range: 1720.. class:: range(stop) 1721 range(start, stop, step=1) 1722 :noindex: 1723 1724 Rather than being a function, :class:`range` is actually an immutable 1725 sequence type, as documented in :ref:`typesseq-range` and :ref:`typesseq`. 1726 1727 1728.. function:: repr(object) 1729 1730 Return a string containing a printable representation of an object. For many 1731 types, this function makes an attempt to return a string that would yield an 1732 object with the same value when passed to :func:`eval`; otherwise, the 1733 representation is a string enclosed in angle brackets that contains the name 1734 of the type of the object together with additional information often 1735 including the name and address of the object. A class can control what this 1736 function returns for its instances 1737 by defining a :meth:`~object.__repr__` method. 1738 If :func:`sys.displayhook` is not accessible, this function will raise 1739 :exc:`RuntimeError`. 1740 1741 This class has a custom representation that can be evaluated:: 1742 1743 class Person: 1744 def __init__(self, name, age): 1745 self.name = name 1746 self.age = age 1747 1748 def __repr__(self): 1749 return f"Person('{self.name}', {self.age})" 1750 1751 1752.. function:: reversed(seq) 1753 1754 Return a reverse :term:`iterator`. *seq* must be an object which has 1755 a :meth:`~object.__reversed__` method or supports the sequence protocol (the 1756 :meth:`~object.__len__` method and the :meth:`~object.__getitem__` method 1757 with integer arguments starting at ``0``). 1758 1759 1760.. function:: round(number, ndigits=None) 1761 1762 Return *number* rounded to *ndigits* precision after the decimal 1763 point. If *ndigits* is omitted or is ``None``, it returns the 1764 nearest integer to its input. 1765 1766 For the built-in types supporting :func:`round`, values are rounded to the 1767 closest multiple of 10 to the power minus *ndigits*; if two multiples are 1768 equally close, rounding is done toward the even choice (so, for example, 1769 both ``round(0.5)`` and ``round(-0.5)`` are ``0``, and ``round(1.5)`` is 1770 ``2``). Any integer value is valid for *ndigits* (positive, zero, or 1771 negative). The return value is an integer if *ndigits* is omitted or 1772 ``None``. 1773 Otherwise, the return value has the same type as *number*. 1774 1775 For a general Python object ``number``, ``round`` delegates to 1776 ``number.__round__``. 1777 1778 .. note:: 1779 1780 The behavior of :func:`round` for floats can be surprising: for example, 1781 ``round(2.675, 2)`` gives ``2.67`` instead of the expected ``2.68``. 1782 This is not a bug: it's a result of the fact that most decimal fractions 1783 can't be represented exactly as a float. See :ref:`tut-fp-issues` for 1784 more information. 1785 1786 1787.. _func-set: 1788.. class:: set() 1789 set(iterable) 1790 :noindex: 1791 1792 Return a new :class:`set` object, optionally with elements taken from 1793 *iterable*. ``set`` is a built-in class. See :class:`set` and 1794 :ref:`types-set` for documentation about this class. 1795 1796 For other containers see the built-in :class:`frozenset`, :class:`list`, 1797 :class:`tuple`, and :class:`dict` classes, as well as the :mod:`collections` 1798 module. 1799 1800 1801.. function:: setattr(object, name, value) 1802 1803 This is the counterpart of :func:`getattr`. The arguments are an object, a 1804 string, and an arbitrary value. The string may name an existing attribute or a 1805 new attribute. The function assigns the value to the attribute, provided the 1806 object allows it. For example, ``setattr(x, 'foobar', 123)`` is equivalent to 1807 ``x.foobar = 123``. 1808 1809 *name* need not be a Python identifier as defined in :ref:`identifiers` 1810 unless the object chooses to enforce that, for example in a custom 1811 :meth:`~object.__getattribute__` or via :attr:`~object.__slots__`. 1812 An attribute whose name is not an identifier will not be accessible using 1813 the dot notation, but is accessible through :func:`getattr` etc.. 1814 1815 .. note:: 1816 1817 Since :ref:`private name mangling <private-name-mangling>` happens at 1818 compilation time, one must manually mangle a private attribute's 1819 (attributes with two leading underscores) name in order to set it with 1820 :func:`setattr`. 1821 1822 1823.. class:: slice(stop) 1824 slice(start, stop, step=None) 1825 1826 Return a :term:`slice` object representing the set of indices specified by 1827 ``range(start, stop, step)``. The *start* and *step* arguments default to 1828 ``None``. 1829 1830 .. attribute:: slice.start 1831 .. attribute:: slice.stop 1832 .. attribute:: slice.step 1833 1834 Slice objects have read-only data attributes :attr:`!start`, 1835 :attr:`!stop`, and :attr:`!step` which merely return the argument 1836 values (or their default). They have no other explicit functionality; 1837 however, they are used by NumPy and other third-party packages. 1838 1839 Slice objects are also generated when extended indexing syntax is used. For 1840 example: ``a[start:stop:step]`` or ``a[start:stop, i]``. See 1841 :func:`itertools.islice` for an alternate version that returns an 1842 :term:`iterator`. 1843 1844 .. versionchanged:: 3.12 1845 Slice objects are now :term:`hashable` (provided :attr:`~slice.start`, 1846 :attr:`~slice.stop`, and :attr:`~slice.step` are hashable). 1847 1848.. function:: sorted(iterable, /, *, key=None, reverse=False) 1849 1850 Return a new sorted list from the items in *iterable*. 1851 1852 Has two optional arguments which must be specified as keyword arguments. 1853 1854 *key* specifies a function of one argument that is used to extract a comparison 1855 key from each element in *iterable* (for example, ``key=str.lower``). The 1856 default value is ``None`` (compare the elements directly). 1857 1858 *reverse* is a boolean value. If set to ``True``, then the list elements are 1859 sorted as if each comparison were reversed. 1860 1861 Use :func:`functools.cmp_to_key` to convert an old-style *cmp* function to a 1862 *key* function. 1863 1864 The built-in :func:`sorted` function is guaranteed to be stable. A sort is 1865 stable if it guarantees not to change the relative order of elements that 1866 compare equal --- this is helpful for sorting in multiple passes (for 1867 example, sort by department, then by salary grade). 1868 1869 The sort algorithm uses only ``<`` comparisons between items. While 1870 defining an :meth:`~object.__lt__` method will suffice for sorting, 1871 :PEP:`8` recommends that all six :ref:`rich comparisons 1872 <comparisons>` be implemented. This will help avoid bugs when using 1873 the same data with other ordering tools such as :func:`max` that rely 1874 on a different underlying method. Implementing all six comparisons 1875 also helps avoid confusion for mixed type comparisons which can call 1876 reflected the :meth:`~object.__gt__` method. 1877 1878 For sorting examples and a brief sorting tutorial, see :ref:`sortinghowto`. 1879 1880.. decorator:: staticmethod 1881 1882 Transform a method into a static method. 1883 1884 A static method does not receive an implicit first argument. To declare a static 1885 method, use this idiom:: 1886 1887 class C: 1888 @staticmethod 1889 def f(arg1, arg2, argN): ... 1890 1891 The ``@staticmethod`` form is a function :term:`decorator` -- see 1892 :ref:`function` for details. 1893 1894 A static method can be called either on the class (such as ``C.f()``) or on 1895 an instance (such as ``C().f()``). 1896 Moreover, the static method :term:`descriptor` is also callable, so it can 1897 be used in the class definition (such as ``f()``). 1898 1899 Static methods in Python are similar to those found in Java or C++. Also, see 1900 :func:`classmethod` for a variant that is useful for creating alternate class 1901 constructors. 1902 1903 Like all decorators, it is also possible to call ``staticmethod`` as 1904 a regular function and do something with its result. This is needed 1905 in some cases where you need a reference to a function from a class 1906 body and you want to avoid the automatic transformation to instance 1907 method. For these cases, use this idiom:: 1908 1909 def regular_function(): 1910 ... 1911 1912 class C: 1913 method = staticmethod(regular_function) 1914 1915 For more information on static methods, see :ref:`types`. 1916 1917 .. versionchanged:: 3.10 1918 Static methods now inherit the method attributes 1919 (:attr:`~function.__module__`, :attr:`~function.__name__`, 1920 :attr:`~function.__qualname__`, :attr:`~function.__doc__` and 1921 :attr:`~function.__annotations__`), have a new ``__wrapped__`` attribute, 1922 and are now callable as regular functions. 1923 1924 1925.. index:: 1926 single: string; str() (built-in function) 1927 1928.. _func-str: 1929.. class:: str(object='') 1930 str(object=b'', encoding='utf-8', errors='strict') 1931 :noindex: 1932 1933 Return a :class:`str` version of *object*. See :func:`str` for details. 1934 1935 ``str`` is the built-in string :term:`class`. For general information 1936 about strings, see :ref:`textseq`. 1937 1938 1939.. function:: sum(iterable, /, start=0) 1940 1941 Sums *start* and the items of an *iterable* from left to right and returns the 1942 total. The *iterable*'s items are normally numbers, and the start value is not 1943 allowed to be a string. 1944 1945 For some use cases, there are good alternatives to :func:`sum`. 1946 The preferred, fast way to concatenate a sequence of strings is by calling 1947 ``''.join(sequence)``. To add floating-point values with extended precision, 1948 see :func:`math.fsum`\. To concatenate a series of iterables, consider using 1949 :func:`itertools.chain`. 1950 1951 .. versionchanged:: 3.8 1952 The *start* parameter can be specified as a keyword argument. 1953 1954 .. versionchanged:: 3.12 Summation of floats switched to an algorithm 1955 that gives higher accuracy and better commutativity on most builds. 1956 1957 1958.. class:: super() 1959 super(type, object_or_type=None) 1960 1961 Return a proxy object that delegates method calls to a parent or sibling 1962 class of *type*. This is useful for accessing inherited methods that have 1963 been overridden in a class. 1964 1965 The *object_or_type* determines the :term:`method resolution order` 1966 to be searched. The search starts from the class right after the 1967 *type*. 1968 1969 For example, if :attr:`~type.__mro__` of *object_or_type* is 1970 ``D -> B -> C -> A -> object`` and the value of *type* is ``B``, 1971 then :func:`super` searches ``C -> A -> object``. 1972 1973 The :attr:`~type.__mro__` attribute of the class corresponding to 1974 *object_or_type* lists the method resolution search order used by both 1975 :func:`getattr` and :func:`super`. The attribute is dynamic and can change 1976 whenever the inheritance hierarchy is updated. 1977 1978 If the second argument is omitted, the super object returned is unbound. If 1979 the second argument is an object, ``isinstance(obj, type)`` must be true. If 1980 the second argument is a type, ``issubclass(type2, type)`` must be true (this 1981 is useful for classmethods). 1982 1983 When called directly within an ordinary method of a class, both arguments may 1984 be omitted ("zero-argument :func:`!super`"). In this case, *type* will be the 1985 enclosing class, and *obj* will be the first argument of the immediately 1986 enclosing function (typically ``self``). (This means that zero-argument 1987 :func:`!super` will not work as expected within nested functions, including 1988 generator expressions, which implicitly create nested functions.) 1989 1990 There are two typical use cases for *super*. In a class hierarchy with 1991 single inheritance, *super* can be used to refer to parent classes without 1992 naming them explicitly, thus making the code more maintainable. This use 1993 closely parallels the use of *super* in other programming languages. 1994 1995 The second use case is to support cooperative multiple inheritance in a 1996 dynamic execution environment. This use case is unique to Python and is 1997 not found in statically compiled languages or languages that only support 1998 single inheritance. This makes it possible to implement "diamond diagrams" 1999 where multiple base classes implement the same method. Good design dictates 2000 that such implementations have the same calling signature in every case (because the 2001 order of calls is determined at runtime, because that order adapts 2002 to changes in the class hierarchy, and because that order can include 2003 sibling classes that are unknown prior to runtime). 2004 2005 For both use cases, a typical superclass call looks like this:: 2006 2007 class C(B): 2008 def method(self, arg): 2009 super().method(arg) # This does the same thing as: 2010 # super(C, self).method(arg) 2011 2012 In addition to method lookups, :func:`super` also works for attribute 2013 lookups. One possible use case for this is calling :term:`descriptors <descriptor>` 2014 in a parent or sibling class. 2015 2016 Note that :func:`super` is implemented as part of the binding process for 2017 explicit dotted attribute lookups such as ``super().__getitem__(name)``. 2018 It does so by implementing its own :meth:`~object.__getattribute__` method 2019 for searching 2020 classes in a predictable order that supports cooperative multiple inheritance. 2021 Accordingly, :func:`super` is undefined for implicit lookups using statements or 2022 operators such as ``super()[name]``. 2023 2024 Also note that, aside from the zero argument form, :func:`super` is not 2025 limited to use inside methods. The two argument form specifies the 2026 arguments exactly and makes the appropriate references. The zero 2027 argument form only works inside a class definition, as the compiler fills 2028 in the necessary details to correctly retrieve the class being defined, 2029 as well as accessing the current instance for ordinary methods. 2030 2031 For practical suggestions on how to design cooperative classes using 2032 :func:`super`, see `guide to using super() 2033 <https://rhettinger.wordpress.com/2011/05/26/super-considered-super/>`_. 2034 2035 2036.. _func-tuple: 2037.. class:: tuple() 2038 tuple(iterable) 2039 :noindex: 2040 2041 Rather than being a function, :class:`tuple` is actually an immutable 2042 sequence type, as documented in :ref:`typesseq-tuple` and :ref:`typesseq`. 2043 2044 2045.. class:: type(object) 2046 type(name, bases, dict, **kwds) 2047 2048 .. index:: pair: object; type 2049 2050 With one argument, return the type of an *object*. The return value is a 2051 type object and generally the same object as returned by 2052 :attr:`object.__class__`. 2053 2054 The :func:`isinstance` built-in function is recommended for testing the type 2055 of an object, because it takes subclasses into account. 2056 2057 With three arguments, return a new type object. This is essentially a 2058 dynamic form of the :keyword:`class` statement. The *name* string is 2059 the class name and becomes the :attr:`~type.__name__` attribute. 2060 The *bases* tuple contains the base classes and becomes the 2061 :attr:`~type.__bases__` attribute; if empty, :class:`object`, the 2062 ultimate base of all classes, is added. The *dict* dictionary contains 2063 attribute and method definitions for the class body; it may be copied 2064 or wrapped before becoming the :attr:`~type.__dict__` attribute. 2065 The following two statements create identical :class:`!type` objects: 2066 2067 >>> class X: 2068 ... a = 1 2069 ... 2070 >>> X = type('X', (), dict(a=1)) 2071 2072 See also: 2073 2074 * :ref:`Documentation on attributes and methods on classes <class-attrs-and-methods>`. 2075 * :ref:`bltin-type-objects` 2076 2077 Keyword arguments provided to the three argument form are passed to the 2078 appropriate metaclass machinery (usually :meth:`~object.__init_subclass__`) 2079 in the same way that keywords in a class 2080 definition (besides *metaclass*) would. 2081 2082 See also :ref:`class-customization`. 2083 2084 .. versionchanged:: 3.6 2085 Subclasses of :class:`!type` which don't override ``type.__new__`` may no 2086 longer use the one-argument form to get the type of an object. 2087 2088.. function:: vars() 2089 vars(object) 2090 2091 Return the :attr:`~object.__dict__` attribute for a module, class, instance, 2092 or any other object with a :attr:`!__dict__` attribute. 2093 2094 Objects such as modules and instances have an updateable :attr:`~object.__dict__` 2095 attribute; however, other objects may have write restrictions on their 2096 :attr:`!__dict__` attributes (for example, classes use a 2097 :class:`types.MappingProxyType` to prevent direct dictionary updates). 2098 2099 Without an argument, :func:`vars` acts like :func:`locals`. 2100 2101 A :exc:`TypeError` exception is raised if an object is specified but 2102 it doesn't have a :attr:`~object.__dict__` attribute (for example, if 2103 its class defines the :attr:`~object.__slots__` attribute). 2104 2105 .. versionchanged:: 3.13 2106 2107 The result of calling this function without an argument has been 2108 updated as described for the :func:`locals` builtin. 2109 2110 2111.. function:: zip(*iterables, strict=False) 2112 2113 Iterate over several iterables in parallel, producing tuples with an item 2114 from each one. 2115 2116 Example:: 2117 2118 >>> for item in zip([1, 2, 3], ['sugar', 'spice', 'everything nice']): 2119 ... print(item) 2120 ... 2121 (1, 'sugar') 2122 (2, 'spice') 2123 (3, 'everything nice') 2124 2125 More formally: :func:`zip` returns an iterator of tuples, where the *i*-th 2126 tuple contains the *i*-th element from each of the argument iterables. 2127 2128 Another way to think of :func:`zip` is that it turns rows into columns, and 2129 columns into rows. This is similar to `transposing a matrix 2130 <https://en.wikipedia.org/wiki/Transpose>`_. 2131 2132 :func:`zip` is lazy: The elements won't be processed until the iterable is 2133 iterated on, e.g. by a :keyword:`!for` loop or by wrapping in a 2134 :class:`list`. 2135 2136 One thing to consider is that the iterables passed to :func:`zip` could have 2137 different lengths; sometimes by design, and sometimes because of a bug in 2138 the code that prepared these iterables. Python offers three different 2139 approaches to dealing with this issue: 2140 2141 * By default, :func:`zip` stops when the shortest iterable is exhausted. 2142 It will ignore the remaining items in the longer iterables, cutting off 2143 the result to the length of the shortest iterable:: 2144 2145 >>> list(zip(range(3), ['fee', 'fi', 'fo', 'fum'])) 2146 [(0, 'fee'), (1, 'fi'), (2, 'fo')] 2147 2148 * :func:`zip` is often used in cases where the iterables are assumed to be 2149 of equal length. In such cases, it's recommended to use the ``strict=True`` 2150 option. Its output is the same as regular :func:`zip`:: 2151 2152 >>> list(zip(('a', 'b', 'c'), (1, 2, 3), strict=True)) 2153 [('a', 1), ('b', 2), ('c', 3)] 2154 2155 Unlike the default behavior, it raises a :exc:`ValueError` if one iterable 2156 is exhausted before the others: 2157 2158 >>> for item in zip(range(3), ['fee', 'fi', 'fo', 'fum'], strict=True): # doctest: +SKIP 2159 ... print(item) 2160 ... 2161 (0, 'fee') 2162 (1, 'fi') 2163 (2, 'fo') 2164 Traceback (most recent call last): 2165 ... 2166 ValueError: zip() argument 2 is longer than argument 1 2167 2168 .. 2169 This doctest is disabled because doctest does not support capturing 2170 output and exceptions in the same code unit. 2171 https://github.com/python/cpython/issues/65382 2172 2173 Without the ``strict=True`` argument, any bug that results in iterables of 2174 different lengths will be silenced, possibly manifesting as a hard-to-find 2175 bug in another part of the program. 2176 2177 * Shorter iterables can be padded with a constant value to make all the 2178 iterables have the same length. This is done by 2179 :func:`itertools.zip_longest`. 2180 2181 Edge cases: With a single iterable argument, :func:`zip` returns an 2182 iterator of 1-tuples. With no arguments, it returns an empty iterator. 2183 2184 Tips and tricks: 2185 2186 * The left-to-right evaluation order of the iterables is guaranteed. This 2187 makes possible an idiom for clustering a data series into n-length groups 2188 using ``zip(*[iter(s)]*n, strict=True)``. This repeats the *same* iterator 2189 ``n`` times so that each output tuple has the result of ``n`` calls to the 2190 iterator. This has the effect of dividing the input into n-length chunks. 2191 2192 * :func:`zip` in conjunction with the ``*`` operator can be used to unzip a 2193 list:: 2194 2195 >>> x = [1, 2, 3] 2196 >>> y = [4, 5, 6] 2197 >>> list(zip(x, y)) 2198 [(1, 4), (2, 5), (3, 6)] 2199 >>> x2, y2 = zip(*zip(x, y)) 2200 >>> x == list(x2) and y == list(y2) 2201 True 2202 2203 .. versionchanged:: 3.10 2204 Added the ``strict`` argument. 2205 2206 2207.. function:: __import__(name, globals=None, locals=None, fromlist=(), level=0) 2208 2209 .. index:: 2210 pair: statement; import 2211 pair: module; builtins 2212 2213 .. note:: 2214 2215 This is an advanced function that is not needed in everyday Python 2216 programming, unlike :func:`importlib.import_module`. 2217 2218 This function is invoked by the :keyword:`import` statement. It can be 2219 replaced (by importing the :mod:`builtins` module and assigning to 2220 ``builtins.__import__``) in order to change semantics of the 2221 :keyword:`!import` statement, but doing so is **strongly** discouraged as it 2222 is usually simpler to use import hooks (see :pep:`302`) to attain the same 2223 goals and does not cause issues with code which assumes the default import 2224 implementation is in use. Direct use of :func:`__import__` is also 2225 discouraged in favor of :func:`importlib.import_module`. 2226 2227 The function imports the module *name*, potentially using the given *globals* 2228 and *locals* to determine how to interpret the name in a package context. 2229 The *fromlist* gives the names of objects or submodules that should be 2230 imported from the module given by *name*. The standard implementation does 2231 not use its *locals* argument at all and uses its *globals* only to 2232 determine the package context of the :keyword:`import` statement. 2233 2234 *level* specifies whether to use absolute or relative imports. ``0`` (the 2235 default) means only perform absolute imports. Positive values for 2236 *level* indicate the number of parent directories to search relative to the 2237 directory of the module calling :func:`__import__` (see :pep:`328` for the 2238 details). 2239 2240 When the *name* variable is of the form ``package.module``, normally, the 2241 top-level package (the name up till the first dot) is returned, *not* the 2242 module named by *name*. However, when a non-empty *fromlist* argument is 2243 given, the module named by *name* is returned. 2244 2245 For example, the statement ``import spam`` results in bytecode resembling the 2246 following code:: 2247 2248 spam = __import__('spam', globals(), locals(), [], 0) 2249 2250 The statement ``import spam.ham`` results in this call:: 2251 2252 spam = __import__('spam.ham', globals(), locals(), [], 0) 2253 2254 Note how :func:`__import__` returns the toplevel module here because this is 2255 the object that is bound to a name by the :keyword:`import` statement. 2256 2257 On the other hand, the statement ``from spam.ham import eggs, sausage as 2258 saus`` results in :: 2259 2260 _temp = __import__('spam.ham', globals(), locals(), ['eggs', 'sausage'], 0) 2261 eggs = _temp.eggs 2262 saus = _temp.sausage 2263 2264 Here, the ``spam.ham`` module is returned from :func:`__import__`. From this 2265 object, the names to import are retrieved and assigned to their respective 2266 names. 2267 2268 If you simply want to import a module (potentially within a package) by name, 2269 use :func:`importlib.import_module`. 2270 2271 .. versionchanged:: 3.3 2272 Negative values for *level* are no longer supported (which also changes 2273 the default value to 0). 2274 2275 .. versionchanged:: 3.9 2276 When the command line options :option:`-E` or :option:`-I` are being used, 2277 the environment variable :envvar:`PYTHONCASEOK` is now ignored. 2278 2279.. rubric:: Footnotes 2280 2281.. [#] Note that the parser only accepts the Unix-style end of line convention. 2282 If you are reading the code from a file, make sure to use newline conversion 2283 mode to convert Windows or Mac-style newlines. 2284