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