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 .. versionchanged:: 3.10.7 895 :class:`int` string inputs and string representations can be limited to 896 help avoid denial of service attacks. A :exc:`ValueError` is raised when 897 the limit is exceeded while converting a string *x* to an :class:`int` or 898 when converting an :class:`int` into a string would exceed the limit. 899 See the :ref:`integer string conversion length limitation 900 <int_max_str_digits>` documentation. 901 902 903.. function:: isinstance(object, classinfo) 904 905 Return ``True`` if the *object* argument is an instance of the *classinfo* 906 argument, or of a (direct, indirect, or :term:`virtual <abstract base 907 class>`) subclass thereof. If *object* is not 908 an object of the given type, the function always returns ``False``. 909 If *classinfo* is a tuple of type objects (or recursively, other such 910 tuples) or a :ref:`types-union` of multiple types, return ``True`` if 911 *object* is an instance of any of the types. 912 If *classinfo* is not a type or tuple of types and such tuples, 913 a :exc:`TypeError` exception is raised. 914 915 .. versionchanged:: 3.10 916 *classinfo* can be a :ref:`types-union`. 917 918 919.. function:: issubclass(class, classinfo) 920 921 Return ``True`` if *class* is a subclass (direct, indirect, or :term:`virtual 922 <abstract base class>`) of *classinfo*. A 923 class is considered a subclass of itself. *classinfo* may be a tuple of class 924 objects or a :ref:`types-union`, in which case return ``True`` if *class* is a 925 subclass of any entry in *classinfo*. In any other case, a :exc:`TypeError` 926 exception is raised. 927 928 .. versionchanged:: 3.10 929 *classinfo* can be a :ref:`types-union`. 930 931 932.. function:: iter(object[, sentinel]) 933 934 Return an :term:`iterator` object. The first argument is interpreted very 935 differently depending on the presence of the second argument. Without a 936 second argument, *object* must be a collection object which supports the 937 :term:`iterable` protocol (the :meth:`__iter__` method), or it must support 938 the sequence protocol (the :meth:`__getitem__` method with integer arguments 939 starting at ``0``). If it does not support either of those protocols, 940 :exc:`TypeError` is raised. If the second argument, *sentinel*, is given, 941 then *object* must be a callable object. The iterator created in this case 942 will call *object* with no arguments for each call to its 943 :meth:`~iterator.__next__` method; if the value returned is equal to 944 *sentinel*, :exc:`StopIteration` will be raised, otherwise the value will 945 be returned. 946 947 See also :ref:`typeiter`. 948 949 One useful application of the second form of :func:`iter` is to build a 950 block-reader. For example, reading fixed-width blocks from a binary 951 database file until the end of file is reached:: 952 953 from functools import partial 954 with open('mydata.db', 'rb') as f: 955 for block in iter(partial(f.read, 64), b''): 956 process_block(block) 957 958 959.. function:: len(s) 960 961 Return the length (the number of items) of an object. The argument may be a 962 sequence (such as a string, bytes, tuple, list, or range) or a collection 963 (such as a dictionary, set, or frozen set). 964 965 .. impl-detail:: 966 967 ``len`` raises :exc:`OverflowError` on lengths larger than 968 :data:`sys.maxsize`, such as :class:`range(2 ** 100) <range>`. 969 970 971.. _func-list: 972.. class:: list([iterable]) 973 :noindex: 974 975 Rather than being a function, :class:`list` is actually a mutable 976 sequence type, as documented in :ref:`typesseq-list` and :ref:`typesseq`. 977 978 979.. function:: locals() 980 981 Update and return a dictionary representing the current local symbol table. 982 Free variables are returned by :func:`locals` when it is called in function 983 blocks, but not in class blocks. Note that at the module level, :func:`locals` 984 and :func:`globals` are the same dictionary. 985 986 .. note:: 987 The contents of this dictionary should not be modified; changes may not 988 affect the values of local and free variables used by the interpreter. 989 990.. function:: map(function, iterable, ...) 991 992 Return an iterator that applies *function* to every item of *iterable*, 993 yielding the results. If additional *iterable* arguments are passed, 994 *function* must take that many arguments and is applied to the items from all 995 iterables in parallel. With multiple iterables, the iterator stops when the 996 shortest iterable is exhausted. For cases where the function inputs are 997 already arranged into argument tuples, see :func:`itertools.starmap`\. 998 999 1000.. function:: max(iterable, *[, key, default]) 1001 max(arg1, arg2, *args[, key]) 1002 1003 Return the largest item in an iterable or the largest of two or more 1004 arguments. 1005 1006 If one positional argument is provided, it should be an :term:`iterable`. 1007 The largest item in the iterable is returned. If two or more positional 1008 arguments are provided, the largest of the positional arguments is 1009 returned. 1010 1011 There are two optional keyword-only arguments. The *key* argument specifies 1012 a one-argument ordering function like that used for :meth:`list.sort`. The 1013 *default* argument specifies an object to return if the provided iterable is 1014 empty. If the iterable is empty and *default* is not provided, a 1015 :exc:`ValueError` is raised. 1016 1017 If multiple items are maximal, the function returns the first one 1018 encountered. This is consistent with other sort-stability preserving tools 1019 such as ``sorted(iterable, key=keyfunc, reverse=True)[0]`` and 1020 ``heapq.nlargest(1, iterable, key=keyfunc)``. 1021 1022 .. versionadded:: 3.4 1023 The *default* keyword-only argument. 1024 1025 .. versionchanged:: 3.8 1026 The *key* can be ``None``. 1027 1028 1029.. _func-memoryview: 1030.. class:: memoryview(object) 1031 :noindex: 1032 1033 Return a "memory view" object created from the given argument. See 1034 :ref:`typememoryview` for more information. 1035 1036 1037.. function:: min(iterable, *[, key, default]) 1038 min(arg1, arg2, *args[, key]) 1039 1040 Return the smallest item in an iterable or the smallest of two or more 1041 arguments. 1042 1043 If one positional argument is provided, it should be an :term:`iterable`. 1044 The smallest item in the iterable is returned. If two or more positional 1045 arguments are provided, the smallest of the positional arguments is 1046 returned. 1047 1048 There are two optional keyword-only arguments. The *key* argument specifies 1049 a one-argument ordering function like that used for :meth:`list.sort`. The 1050 *default* argument specifies an object to return if the provided iterable is 1051 empty. If the iterable is empty and *default* is not provided, a 1052 :exc:`ValueError` is raised. 1053 1054 If multiple items are minimal, the function returns the first one 1055 encountered. This is consistent with other sort-stability preserving tools 1056 such as ``sorted(iterable, key=keyfunc)[0]`` and ``heapq.nsmallest(1, 1057 iterable, key=keyfunc)``. 1058 1059 .. versionadded:: 3.4 1060 The *default* keyword-only argument. 1061 1062 .. versionchanged:: 3.8 1063 The *key* can be ``None``. 1064 1065 1066.. function:: next(iterator[, default]) 1067 1068 Retrieve the next item from the :term:`iterator` by calling its 1069 :meth:`~iterator.__next__` method. If *default* is given, it is returned 1070 if the iterator is exhausted, otherwise :exc:`StopIteration` is raised. 1071 1072 1073.. class:: object() 1074 1075 Return a new featureless object. :class:`object` is a base for all classes. 1076 It has methods that are common to all instances of Python classes. This 1077 function does not accept any arguments. 1078 1079 .. note:: 1080 1081 :class:`object` does *not* have a :attr:`~object.__dict__`, so you can't 1082 assign arbitrary attributes to an instance of the :class:`object` class. 1083 1084 1085.. function:: oct(x) 1086 1087 Convert an integer number to an octal string prefixed with "0o". The result 1088 is a valid Python expression. If *x* is not a Python :class:`int` object, it 1089 has to define an :meth:`__index__` method that returns an integer. For 1090 example: 1091 1092 >>> oct(8) 1093 '0o10' 1094 >>> oct(-56) 1095 '-0o70' 1096 1097 If you want to convert an integer number to an octal string either with the prefix 1098 "0o" or not, you can use either of the following ways. 1099 1100 >>> '%#o' % 10, '%o' % 10 1101 ('0o12', '12') 1102 >>> format(10, '#o'), format(10, 'o') 1103 ('0o12', '12') 1104 >>> f'{10:#o}', f'{10:o}' 1105 ('0o12', '12') 1106 1107 See also :func:`format` for more information. 1108 1109 .. index:: 1110 single: file object; open() built-in function 1111 1112.. function:: open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None) 1113 1114 Open *file* and return a corresponding :term:`file object`. If the file 1115 cannot be opened, an :exc:`OSError` is raised. See 1116 :ref:`tut-files` for more examples of how to use this function. 1117 1118 *file* is a :term:`path-like object` giving the pathname (absolute or 1119 relative to the current working directory) of the file to be opened or an 1120 integer file descriptor of the file to be wrapped. (If a file descriptor is 1121 given, it is closed when the returned I/O object is closed unless *closefd* 1122 is set to ``False``.) 1123 1124 *mode* is an optional string that specifies the mode in which the file is 1125 opened. It defaults to ``'r'`` which means open for reading in text mode. 1126 Other common values are ``'w'`` for writing (truncating the file if it 1127 already exists), ``'x'`` for exclusive creation, and ``'a'`` for appending 1128 (which on *some* Unix systems, means that *all* writes append to the end of 1129 the file regardless of the current seek position). In text mode, if 1130 *encoding* is not specified the encoding used is platform-dependent: 1131 ``locale.getpreferredencoding(False)`` is called to get the current locale 1132 encoding. (For reading and writing raw bytes use binary mode and leave 1133 *encoding* unspecified.) The available modes are: 1134 1135 .. _filemodes: 1136 1137 .. index:: 1138 pair: file; modes 1139 1140 ========= =============================================================== 1141 Character Meaning 1142 ========= =============================================================== 1143 ``'r'`` open for reading (default) 1144 ``'w'`` open for writing, truncating the file first 1145 ``'x'`` open for exclusive creation, failing if the file already exists 1146 ``'a'`` open for writing, appending to the end of file if it exists 1147 ``'b'`` binary mode 1148 ``'t'`` text mode (default) 1149 ``'+'`` open for updating (reading and writing) 1150 ========= =============================================================== 1151 1152 The default mode is ``'r'`` (open for reading text, a synonym of ``'rt'``). 1153 Modes ``'w+'`` and ``'w+b'`` open and truncate the file. Modes ``'r+'`` 1154 and ``'r+b'`` open the file with no truncation. 1155 1156 As mentioned in the :ref:`io-overview`, Python distinguishes between binary 1157 and text I/O. Files opened in binary mode (including ``'b'`` in the *mode* 1158 argument) return contents as :class:`bytes` objects without any decoding. In 1159 text mode (the default, or when ``'t'`` is included in the *mode* argument), 1160 the contents of the file are returned as :class:`str`, the bytes having been 1161 first decoded using a platform-dependent encoding or using the specified 1162 *encoding* if given. 1163 1164 There is an additional mode character permitted, ``'U'``, which no longer 1165 has any effect, and is considered deprecated. It previously enabled 1166 :term:`universal newlines` in text mode, which became the default behavior 1167 in Python 3.0. Refer to the documentation of the 1168 :ref:`newline <open-newline-parameter>` parameter for further details. 1169 1170 .. note:: 1171 1172 Python doesn't depend on the underlying operating system's notion of text 1173 files; all the processing is done by Python itself, and is therefore 1174 platform-independent. 1175 1176 *buffering* is an optional integer used to set the buffering policy. Pass 0 1177 to switch buffering off (only allowed in binary mode), 1 to select line 1178 buffering (only usable in text mode), and an integer > 1 to indicate the size 1179 in bytes of a fixed-size chunk buffer. When no *buffering* argument is 1180 given, the default buffering policy works as follows: 1181 1182 * Binary files are buffered in fixed-size chunks; the size of the buffer is 1183 chosen using a heuristic trying to determine the underlying device's "block 1184 size" and falling back on :attr:`io.DEFAULT_BUFFER_SIZE`. On many systems, 1185 the buffer will typically be 4096 or 8192 bytes long. 1186 1187 * "Interactive" text files (files for which :meth:`~io.IOBase.isatty` 1188 returns ``True``) use line buffering. Other text files use the policy 1189 described above for binary files. 1190 1191 *encoding* is the name of the encoding used to decode or encode the file. 1192 This should only be used in text mode. The default encoding is platform 1193 dependent (whatever :func:`locale.getpreferredencoding` returns), but any 1194 :term:`text encoding` supported by Python 1195 can be used. See the :mod:`codecs` module for 1196 the list of supported encodings. 1197 1198 *errors* is an optional string that specifies how encoding and decoding 1199 errors are to be handled—this cannot be used in binary mode. 1200 A variety of standard error handlers are available 1201 (listed under :ref:`error-handlers`), though any 1202 error handling name that has been registered with 1203 :func:`codecs.register_error` is also valid. The standard names 1204 include: 1205 1206 * ``'strict'`` to raise a :exc:`ValueError` exception if there is 1207 an encoding error. The default value of ``None`` has the same 1208 effect. 1209 1210 * ``'ignore'`` ignores errors. Note that ignoring encoding errors 1211 can lead to data loss. 1212 1213 * ``'replace'`` causes a replacement marker (such as ``'?'``) to be inserted 1214 where there is malformed data. 1215 1216 * ``'surrogateescape'`` will represent any incorrect bytes as low 1217 surrogate code units ranging from U+DC80 to U+DCFF. 1218 These surrogate code units will then be turned back into 1219 the same bytes when the ``surrogateescape`` error handler is used 1220 when writing data. This is useful for processing files in an 1221 unknown encoding. 1222 1223 * ``'xmlcharrefreplace'`` is only supported when writing to a file. 1224 Characters not supported by the encoding are replaced with the 1225 appropriate XML character reference ``&#nnn;``. 1226 1227 * ``'backslashreplace'`` replaces malformed data by Python's backslashed 1228 escape sequences. 1229 1230 * ``'namereplace'`` (also only supported when writing) 1231 replaces unsupported characters with ``\N{...}`` escape sequences. 1232 1233 .. index:: 1234 single: universal newlines; open() built-in function 1235 1236 .. _open-newline-parameter: 1237 1238 *newline* controls how :term:`universal newlines` mode works (it only 1239 applies to text mode). It can be ``None``, ``''``, ``'\n'``, ``'\r'``, and 1240 ``'\r\n'``. It works as follows: 1241 1242 * When reading input from the stream, if *newline* is ``None``, universal 1243 newlines mode is enabled. Lines in the input can end in ``'\n'``, 1244 ``'\r'``, or ``'\r\n'``, and these are translated into ``'\n'`` before 1245 being returned to the caller. If it is ``''``, universal newlines mode is 1246 enabled, but line endings are returned to the caller untranslated. If it 1247 has any of the other legal values, input lines are only terminated by the 1248 given string, and the line ending is returned to the caller untranslated. 1249 1250 * When writing output to the stream, if *newline* is ``None``, any ``'\n'`` 1251 characters written are translated to the system default line separator, 1252 :data:`os.linesep`. If *newline* is ``''`` or ``'\n'``, no translation 1253 takes place. If *newline* is any of the other legal values, any ``'\n'`` 1254 characters written are translated to the given string. 1255 1256 If *closefd* is ``False`` and a file descriptor rather than a filename was 1257 given, the underlying file descriptor will be kept open when the file is 1258 closed. If a filename is given *closefd* must be ``True`` (the default); 1259 otherwise, an error will be raised. 1260 1261 A custom opener can be used by passing a callable as *opener*. The underlying 1262 file descriptor for the file object is then obtained by calling *opener* with 1263 (*file*, *flags*). *opener* must return an open file descriptor (passing 1264 :mod:`os.open` as *opener* results in functionality similar to passing 1265 ``None``). 1266 1267 The newly created file is :ref:`non-inheritable <fd_inheritance>`. 1268 1269 The following example uses the :ref:`dir_fd <dir_fd>` parameter of the 1270 :func:`os.open` function to open a file relative to a given directory:: 1271 1272 >>> import os 1273 >>> dir_fd = os.open('somedir', os.O_RDONLY) 1274 >>> def opener(path, flags): 1275 ... return os.open(path, flags, dir_fd=dir_fd) 1276 ... 1277 >>> with open('spamspam.txt', 'w', opener=opener) as f: 1278 ... print('This will be written to somedir/spamspam.txt', file=f) 1279 ... 1280 >>> os.close(dir_fd) # don't leak a file descriptor 1281 1282 The type of :term:`file object` returned by the :func:`open` function 1283 depends on the mode. When :func:`open` is used to open a file in a text 1284 mode (``'w'``, ``'r'``, ``'wt'``, ``'rt'``, etc.), it returns a subclass of 1285 :class:`io.TextIOBase` (specifically :class:`io.TextIOWrapper`). When used 1286 to open a file in a binary mode with buffering, the returned class is a 1287 subclass of :class:`io.BufferedIOBase`. The exact class varies: in read 1288 binary mode, it returns an :class:`io.BufferedReader`; in write binary and 1289 append binary modes, it returns an :class:`io.BufferedWriter`, and in 1290 read/write mode, it returns an :class:`io.BufferedRandom`. When buffering is 1291 disabled, the raw stream, a subclass of :class:`io.RawIOBase`, 1292 :class:`io.FileIO`, is returned. 1293 1294 .. index:: 1295 single: line-buffered I/O 1296 single: unbuffered I/O 1297 single: buffer size, I/O 1298 single: I/O control; buffering 1299 single: binary mode 1300 single: text mode 1301 module: sys 1302 1303 See also the file handling modules, such as :mod:`fileinput`, :mod:`io` 1304 (where :func:`open` is declared), :mod:`os`, :mod:`os.path`, :mod:`tempfile`, 1305 and :mod:`shutil`. 1306 1307 .. audit-event:: open file,mode,flags open 1308 1309 The ``mode`` and ``flags`` arguments may have been modified or inferred from 1310 the original call. 1311 1312 .. versionchanged:: 1313 3.3 1314 1315 * The *opener* parameter was added. 1316 * The ``'x'`` mode was added. 1317 * :exc:`IOError` used to be raised, it is now an alias of :exc:`OSError`. 1318 * :exc:`FileExistsError` is now raised if the file opened in exclusive 1319 creation mode (``'x'``) already exists. 1320 1321 .. versionchanged:: 1322 3.4 1323 1324 * The file is now non-inheritable. 1325 1326 .. deprecated-removed:: 3.4 3.10 1327 1328 The ``'U'`` mode. 1329 1330 .. versionchanged:: 1331 3.5 1332 1333 * If the system call is interrupted and the signal handler does not raise an 1334 exception, the function now retries the system call instead of raising an 1335 :exc:`InterruptedError` exception (see :pep:`475` for the rationale). 1336 * The ``'namereplace'`` error handler was added. 1337 1338 .. versionchanged:: 1339 3.6 1340 1341 * Support added to accept objects implementing :class:`os.PathLike`. 1342 * On Windows, opening a console buffer may return a subclass of 1343 :class:`io.RawIOBase` other than :class:`io.FileIO`. 1344 1345.. function:: ord(c) 1346 1347 Given a string representing one Unicode character, return an integer 1348 representing the Unicode code point of that character. For example, 1349 ``ord('a')`` returns the integer ``97`` and ``ord('€')`` (Euro sign) 1350 returns ``8364``. This is the inverse of :func:`chr`. 1351 1352 1353.. function:: pow(base, exp[, mod]) 1354 1355 Return *base* to the power *exp*; if *mod* is present, return *base* to the 1356 power *exp*, modulo *mod* (computed more efficiently than 1357 ``pow(base, exp) % mod``). The two-argument form ``pow(base, exp)`` is 1358 equivalent to using the power operator: ``base**exp``. 1359 1360 The arguments must have numeric types. With mixed operand types, the 1361 coercion rules for binary arithmetic operators apply. For :class:`int` 1362 operands, the result has the same type as the operands (after coercion) 1363 unless the second argument is negative; in that case, all arguments are 1364 converted to float and a float result is delivered. For example, ``pow(10, 2)`` 1365 returns ``100``, but ``pow(10, -2)`` returns ``0.01``. For a negative base of 1366 type :class:`int` or :class:`float` and a non-integral exponent, a complex 1367 result is delivered. For example, ``pow(-9, 0.5)`` returns a value close 1368 to ``3j``. 1369 1370 For :class:`int` operands *base* and *exp*, if *mod* is present, *mod* must 1371 also be of integer type and *mod* must be nonzero. If *mod* is present and 1372 *exp* is negative, *base* must be relatively prime to *mod*. In that case, 1373 ``pow(inv_base, -exp, mod)`` is returned, where *inv_base* is an inverse to 1374 *base* modulo *mod*. 1375 1376 Here's an example of computing an inverse for ``38`` modulo ``97``:: 1377 1378 >>> pow(38, -1, mod=97) 1379 23 1380 >>> 23 * 38 % 97 == 1 1381 True 1382 1383 .. versionchanged:: 3.8 1384 For :class:`int` operands, the three-argument form of ``pow`` now allows 1385 the second argument to be negative, permitting computation of modular 1386 inverses. 1387 1388 .. versionchanged:: 3.8 1389 Allow keyword arguments. Formerly, only positional arguments were 1390 supported. 1391 1392 1393.. function:: print(*objects, sep=' ', end='\\n', file=sys.stdout, flush=False) 1394 1395 Print *objects* to the text stream *file*, separated by *sep* and followed 1396 by *end*. *sep*, *end*, *file*, and *flush*, if present, must be given as keyword 1397 arguments. 1398 1399 All non-keyword arguments are converted to strings like :func:`str` does and 1400 written to the stream, separated by *sep* and followed by *end*. Both *sep* 1401 and *end* must be strings; they can also be ``None``, which means to use the 1402 default values. If no *objects* are given, :func:`print` will just write 1403 *end*. 1404 1405 The *file* argument must be an object with a ``write(string)`` method; if it 1406 is not present or ``None``, :data:`sys.stdout` will be used. Since printed 1407 arguments are converted to text strings, :func:`print` cannot be used with 1408 binary mode file objects. For these, use ``file.write(...)`` instead. 1409 1410 Whether the output is buffered is usually determined by *file*, but if the 1411 *flush* keyword argument is true, the stream is forcibly flushed. 1412 1413 .. versionchanged:: 3.3 1414 Added the *flush* keyword argument. 1415 1416 1417.. class:: property(fget=None, fset=None, fdel=None, doc=None) 1418 1419 Return a property attribute. 1420 1421 *fget* is a function for getting an attribute value. *fset* is a function 1422 for setting an attribute value. *fdel* is a function for deleting an attribute 1423 value. And *doc* creates a docstring for the attribute. 1424 1425 A typical use is to define a managed attribute ``x``:: 1426 1427 class C: 1428 def __init__(self): 1429 self._x = None 1430 1431 def getx(self): 1432 return self._x 1433 1434 def setx(self, value): 1435 self._x = value 1436 1437 def delx(self): 1438 del self._x 1439 1440 x = property(getx, setx, delx, "I'm the 'x' property.") 1441 1442 If *c* is an instance of *C*, ``c.x`` will invoke the getter, 1443 ``c.x = value`` will invoke the setter, and ``del c.x`` the deleter. 1444 1445 If given, *doc* will be the docstring of the property attribute. Otherwise, the 1446 property will copy *fget*'s docstring (if it exists). This makes it possible to 1447 create read-only properties easily using :func:`property` as a :term:`decorator`:: 1448 1449 class Parrot: 1450 def __init__(self): 1451 self._voltage = 100000 1452 1453 @property 1454 def voltage(self): 1455 """Get the current voltage.""" 1456 return self._voltage 1457 1458 The ``@property`` decorator turns the :meth:`voltage` method into a "getter" 1459 for a read-only attribute with the same name, and it sets the docstring for 1460 *voltage* to "Get the current voltage." 1461 1462 A property object has :attr:`~property.getter`, :attr:`~property.setter`, 1463 and :attr:`~property.deleter` methods usable as decorators that create a 1464 copy of the property with the corresponding accessor function set to the 1465 decorated function. This is best explained with an example:: 1466 1467 class C: 1468 def __init__(self): 1469 self._x = None 1470 1471 @property 1472 def x(self): 1473 """I'm the 'x' property.""" 1474 return self._x 1475 1476 @x.setter 1477 def x(self, value): 1478 self._x = value 1479 1480 @x.deleter 1481 def x(self): 1482 del self._x 1483 1484 This code is exactly equivalent to the first example. Be sure to give the 1485 additional functions the same name as the original property (``x`` in this 1486 case.) 1487 1488 The returned property object also has the attributes ``fget``, ``fset``, and 1489 ``fdel`` corresponding to the constructor arguments. 1490 1491 .. versionchanged:: 3.5 1492 The docstrings of property objects are now writeable. 1493 1494 1495.. _func-range: 1496.. class:: range(stop) 1497 range(start, stop[, step]) 1498 :noindex: 1499 1500 Rather than being a function, :class:`range` is actually an immutable 1501 sequence type, as documented in :ref:`typesseq-range` and :ref:`typesseq`. 1502 1503 1504.. function:: repr(object) 1505 1506 Return a string containing a printable representation of an object. For many 1507 types, this function makes an attempt to return a string that would yield an 1508 object with the same value when passed to :func:`eval`; otherwise, the 1509 representation is a string enclosed in angle brackets that contains the name 1510 of the type of the object together with additional information often 1511 including the name and address of the object. A class can control what this 1512 function returns for its instances by defining a :meth:`__repr__` method. 1513 1514 1515.. function:: reversed(seq) 1516 1517 Return a reverse :term:`iterator`. *seq* must be an object which has 1518 a :meth:`__reversed__` method or supports the sequence protocol (the 1519 :meth:`__len__` method and the :meth:`__getitem__` method with integer 1520 arguments starting at ``0``). 1521 1522 1523.. function:: round(number[, ndigits]) 1524 1525 Return *number* rounded to *ndigits* precision after the decimal 1526 point. If *ndigits* is omitted or is ``None``, it returns the 1527 nearest integer to its input. 1528 1529 For the built-in types supporting :func:`round`, values are rounded to the 1530 closest multiple of 10 to the power minus *ndigits*; if two multiples are 1531 equally close, rounding is done toward the even choice (so, for example, 1532 both ``round(0.5)`` and ``round(-0.5)`` are ``0``, and ``round(1.5)`` is 1533 ``2``). Any integer value is valid for *ndigits* (positive, zero, or 1534 negative). The return value is an integer if *ndigits* is omitted or 1535 ``None``. 1536 Otherwise, the return value has the same type as *number*. 1537 1538 For a general Python object ``number``, ``round`` delegates to 1539 ``number.__round__``. 1540 1541 .. note:: 1542 1543 The behavior of :func:`round` for floats can be surprising: for example, 1544 ``round(2.675, 2)`` gives ``2.67`` instead of the expected ``2.68``. 1545 This is not a bug: it's a result of the fact that most decimal fractions 1546 can't be represented exactly as a float. See :ref:`tut-fp-issues` for 1547 more information. 1548 1549 1550.. _func-set: 1551.. class:: set([iterable]) 1552 :noindex: 1553 1554 Return a new :class:`set` object, optionally with elements taken from 1555 *iterable*. ``set`` is a built-in class. See :class:`set` and 1556 :ref:`types-set` for documentation about this class. 1557 1558 For other containers see the built-in :class:`frozenset`, :class:`list`, 1559 :class:`tuple`, and :class:`dict` classes, as well as the :mod:`collections` 1560 module. 1561 1562 1563.. function:: setattr(object, name, value) 1564 1565 This is the counterpart of :func:`getattr`. The arguments are an object, a 1566 string, and an arbitrary value. The string may name an existing attribute or a 1567 new attribute. The function assigns the value to the attribute, provided the 1568 object allows it. For example, ``setattr(x, 'foobar', 123)`` is equivalent to 1569 ``x.foobar = 123``. 1570 1571 .. note:: 1572 1573 Since :ref:`private name mangling <private-name-mangling>` happens at 1574 compilation time, one must manually mangle a private attribute's 1575 (attributes with two leading underscores) name in order to set it with 1576 :func:`setattr`. 1577 1578 1579.. class:: slice(stop) 1580 slice(start, stop[, step]) 1581 1582 Return a :term:`slice` object representing the set of indices specified by 1583 ``range(start, stop, step)``. The *start* and *step* arguments default to 1584 ``None``. Slice objects have read-only data attributes :attr:`~slice.start`, 1585 :attr:`~slice.stop`, and :attr:`~slice.step` which merely return the argument 1586 values (or their default). They have no other explicit functionality; 1587 however, they are used by NumPy and other third-party packages. 1588 Slice objects are also generated when extended indexing syntax is used. For 1589 example: ``a[start:stop:step]`` or ``a[start:stop, i]``. See 1590 :func:`itertools.islice` for an alternate version that returns an iterator. 1591 1592 1593.. function:: sorted(iterable, /, *, key=None, reverse=False) 1594 1595 Return a new sorted list from the items in *iterable*. 1596 1597 Has two optional arguments which must be specified as keyword arguments. 1598 1599 *key* specifies a function of one argument that is used to extract a comparison 1600 key from each element in *iterable* (for example, ``key=str.lower``). The 1601 default value is ``None`` (compare the elements directly). 1602 1603 *reverse* is a boolean value. If set to ``True``, then the list elements are 1604 sorted as if each comparison were reversed. 1605 1606 Use :func:`functools.cmp_to_key` to convert an old-style *cmp* function to a 1607 *key* function. 1608 1609 The built-in :func:`sorted` function is guaranteed to be stable. A sort is 1610 stable if it guarantees not to change the relative order of elements that 1611 compare equal --- this is helpful for sorting in multiple passes (for 1612 example, sort by department, then by salary grade). 1613 1614 The sort algorithm uses only ``<`` comparisons between items. While 1615 defining an :meth:`~object.__lt__` method will suffice for sorting, 1616 :PEP:`8` recommends that all six :ref:`rich comparisons 1617 <comparisons>` be implemented. This will help avoid bugs when using 1618 the same data with other ordering tools such as :func:`max` that rely 1619 on a different underlying method. Implementing all six comparisons 1620 also helps avoid confusion for mixed type comparisons which can call 1621 reflected the :meth:`~object.__gt__` method. 1622 1623 For sorting examples and a brief sorting tutorial, see :ref:`sortinghowto`. 1624 1625.. decorator:: staticmethod 1626 1627 Transform a method into a static method. 1628 1629 A static method does not receive an implicit first argument. To declare a static 1630 method, use this idiom:: 1631 1632 class C: 1633 @staticmethod 1634 def f(arg1, arg2, ...): ... 1635 1636 The ``@staticmethod`` form is a function :term:`decorator` -- see 1637 :ref:`function` for details. 1638 1639 A static method can be called either on the class (such as ``C.f()``) or on 1640 an instance (such as ``C().f()``). Moreover, they can be called as regular 1641 functions (such as ``f()``). 1642 1643 Static methods in Python are similar to those found in Java or C++. Also, see 1644 :func:`classmethod` for a variant that is useful for creating alternate class 1645 constructors. 1646 1647 Like all decorators, it is also possible to call ``staticmethod`` as 1648 a regular function and do something with its result. This is needed 1649 in some cases where you need a reference to a function from a class 1650 body and you want to avoid the automatic transformation to instance 1651 method. For these cases, use this idiom:: 1652 1653 def regular_function(): 1654 ... 1655 1656 class C: 1657 method = staticmethod(regular_function) 1658 1659 For more information on static methods, see :ref:`types`. 1660 1661 .. versionchanged:: 3.10 1662 Static methods now inherit the method attributes (``__module__``, 1663 ``__name__``, ``__qualname__``, ``__doc__`` and ``__annotations__``), 1664 have a new ``__wrapped__`` attribute, and are now callable as regular 1665 functions. 1666 1667 1668.. index:: 1669 single: string; str() (built-in function) 1670 1671.. _func-str: 1672.. class:: str(object='') 1673 str(object=b'', encoding='utf-8', errors='strict') 1674 :noindex: 1675 1676 Return a :class:`str` version of *object*. See :func:`str` for details. 1677 1678 ``str`` is the built-in string :term:`class`. For general information 1679 about strings, see :ref:`textseq`. 1680 1681 1682.. function:: sum(iterable, /, start=0) 1683 1684 Sums *start* and the items of an *iterable* from left to right and returns the 1685 total. The *iterable*'s items are normally numbers, and the start value is not 1686 allowed to be a string. 1687 1688 For some use cases, there are good alternatives to :func:`sum`. 1689 The preferred, fast way to concatenate a sequence of strings is by calling 1690 ``''.join(sequence)``. To add floating point values with extended precision, 1691 see :func:`math.fsum`\. To concatenate a series of iterables, consider using 1692 :func:`itertools.chain`. 1693 1694 .. versionchanged:: 3.8 1695 The *start* parameter can be specified as a keyword argument. 1696 1697.. class:: super([type[, object-or-type]]) 1698 1699 Return a proxy object that delegates method calls to a parent or sibling 1700 class of *type*. This is useful for accessing inherited methods that have 1701 been overridden in a class. 1702 1703 The *object-or-type* determines the :term:`method resolution order` 1704 to be searched. The search starts from the class right after the 1705 *type*. 1706 1707 For example, if :attr:`~class.__mro__` of *object-or-type* is 1708 ``D -> B -> C -> A -> object`` and the value of *type* is ``B``, 1709 then :func:`super` searches ``C -> A -> object``. 1710 1711 The :attr:`~class.__mro__` attribute of the *object-or-type* lists the method 1712 resolution search order used by both :func:`getattr` and :func:`super`. The 1713 attribute is dynamic and can change whenever the inheritance hierarchy is 1714 updated. 1715 1716 If the second argument is omitted, the super object returned is unbound. If 1717 the second argument is an object, ``isinstance(obj, type)`` must be true. If 1718 the second argument is a type, ``issubclass(type2, type)`` must be true (this 1719 is useful for classmethods). 1720 1721 There are two typical use cases for *super*. In a class hierarchy with 1722 single inheritance, *super* can be used to refer to parent classes without 1723 naming them explicitly, thus making the code more maintainable. This use 1724 closely parallels the use of *super* in other programming languages. 1725 1726 The second use case is to support cooperative multiple inheritance in a 1727 dynamic execution environment. This use case is unique to Python and is 1728 not found in statically compiled languages or languages that only support 1729 single inheritance. This makes it possible to implement "diamond diagrams" 1730 where multiple base classes implement the same method. Good design dictates 1731 that such implementations have the same calling signature in every case (because the 1732 order of calls is determined at runtime, because that order adapts 1733 to changes in the class hierarchy, and because that order can include 1734 sibling classes that are unknown prior to runtime). 1735 1736 For both use cases, a typical superclass call looks like this:: 1737 1738 class C(B): 1739 def method(self, arg): 1740 super().method(arg) # This does the same thing as: 1741 # super(C, self).method(arg) 1742 1743 In addition to method lookups, :func:`super` also works for attribute 1744 lookups. One possible use case for this is calling :term:`descriptors <descriptor>` 1745 in a parent or sibling class. 1746 1747 Note that :func:`super` is implemented as part of the binding process for 1748 explicit dotted attribute lookups such as ``super().__getitem__(name)``. 1749 It does so by implementing its own :meth:`__getattribute__` method for searching 1750 classes in a predictable order that supports cooperative multiple inheritance. 1751 Accordingly, :func:`super` is undefined for implicit lookups using statements or 1752 operators such as ``super()[name]``. 1753 1754 Also note that, aside from the zero argument form, :func:`super` is not 1755 limited to use inside methods. The two argument form specifies the 1756 arguments exactly and makes the appropriate references. The zero 1757 argument form only works inside a class definition, as the compiler fills 1758 in the necessary details to correctly retrieve the class being defined, 1759 as well as accessing the current instance for ordinary methods. 1760 1761 For practical suggestions on how to design cooperative classes using 1762 :func:`super`, see `guide to using super() 1763 <https://rhettinger.wordpress.com/2011/05/26/super-considered-super/>`_. 1764 1765 1766.. _func-tuple: 1767.. class:: tuple([iterable]) 1768 :noindex: 1769 1770 Rather than being a function, :class:`tuple` is actually an immutable 1771 sequence type, as documented in :ref:`typesseq-tuple` and :ref:`typesseq`. 1772 1773 1774.. class:: type(object) 1775 type(name, bases, dict, **kwds) 1776 1777 .. index:: object: type 1778 1779 With one argument, return the type of an *object*. The return value is a 1780 type object and generally the same object as returned by 1781 :attr:`object.__class__ <instance.__class__>`. 1782 1783 The :func:`isinstance` built-in function is recommended for testing the type 1784 of an object, because it takes subclasses into account. 1785 1786 1787 With three arguments, return a new type object. This is essentially a 1788 dynamic form of the :keyword:`class` statement. The *name* string is 1789 the class name and becomes the :attr:`~definition.__name__` attribute. 1790 The *bases* tuple contains the base classes and becomes the 1791 :attr:`~class.__bases__` attribute; if empty, :class:`object`, the 1792 ultimate base of all classes, is added. The *dict* dictionary contains 1793 attribute and method definitions for the class body; it may be copied 1794 or wrapped before becoming the :attr:`~object.__dict__` attribute. 1795 The following two statements create identical :class:`type` objects: 1796 1797 >>> class X: 1798 ... a = 1 1799 ... 1800 >>> X = type('X', (), dict(a=1)) 1801 1802 See also :ref:`bltin-type-objects`. 1803 1804 Keyword arguments provided to the three argument form are passed to the 1805 appropriate metaclass machinery (usually :meth:`~object.__init_subclass__`) 1806 in the same way that keywords in a class 1807 definition (besides *metaclass*) would. 1808 1809 See also :ref:`class-customization`. 1810 1811 .. versionchanged:: 3.6 1812 Subclasses of :class:`type` which don't override ``type.__new__`` may no 1813 longer use the one-argument form to get the type of an object. 1814 1815.. function:: vars([object]) 1816 1817 Return the :attr:`~object.__dict__` attribute for a module, class, instance, 1818 or any other object with a :attr:`~object.__dict__` attribute. 1819 1820 Objects such as modules and instances have an updateable :attr:`~object.__dict__` 1821 attribute; however, other objects may have write restrictions on their 1822 :attr:`~object.__dict__` attributes (for example, classes use a 1823 :class:`types.MappingProxyType` to prevent direct dictionary updates). 1824 1825 Without an argument, :func:`vars` acts like :func:`locals`. Note, the 1826 locals dictionary is only useful for reads since updates to the locals 1827 dictionary are ignored. 1828 1829 A :exc:`TypeError` exception is raised if an object is specified but 1830 it doesn't have a :attr:`~object.__dict__` attribute (for example, if 1831 its class defines the :attr:`~object.__slots__` attribute). 1832 1833.. function:: zip(*iterables, strict=False) 1834 1835 Iterate over several iterables in parallel, producing tuples with an item 1836 from each one. 1837 1838 Example:: 1839 1840 >>> for item in zip([1, 2, 3], ['sugar', 'spice', 'everything nice']): 1841 ... print(item) 1842 ... 1843 (1, 'sugar') 1844 (2, 'spice') 1845 (3, 'everything nice') 1846 1847 More formally: :func:`zip` returns an iterator of tuples, where the *i*-th 1848 tuple contains the *i*-th element from each of the argument iterables. 1849 1850 Another way to think of :func:`zip` is that it turns rows into columns, and 1851 columns into rows. This is similar to `transposing a matrix 1852 <https://en.wikipedia.org/wiki/Transpose>`_. 1853 1854 :func:`zip` is lazy: The elements won't be processed until the iterable is 1855 iterated on, e.g. by a :keyword:`!for` loop or by wrapping in a 1856 :class:`list`. 1857 1858 One thing to consider is that the iterables passed to :func:`zip` could have 1859 different lengths; sometimes by design, and sometimes because of a bug in 1860 the code that prepared these iterables. Python offers three different 1861 approaches to dealing with this issue: 1862 1863 * By default, :func:`zip` stops when the shortest iterable is exhausted. 1864 It will ignore the remaining items in the longer iterables, cutting off 1865 the result to the length of the shortest iterable:: 1866 1867 >>> list(zip(range(3), ['fee', 'fi', 'fo', 'fum'])) 1868 [(0, 'fee'), (1, 'fi'), (2, 'fo')] 1869 1870 * :func:`zip` is often used in cases where the iterables are assumed to be 1871 of equal length. In such cases, it's recommended to use the ``strict=True`` 1872 option. Its output is the same as regular :func:`zip`:: 1873 1874 >>> list(zip(('a', 'b', 'c'), (1, 2, 3), strict=True)) 1875 [('a', 1), ('b', 2), ('c', 3)] 1876 1877 Unlike the default behavior, it checks that the lengths of iterables are 1878 identical, raising a :exc:`ValueError` if they aren't: 1879 1880 >>> list(zip(range(3), ['fee', 'fi', 'fo', 'fum'], strict=True)) 1881 Traceback (most recent call last): 1882 ... 1883 ValueError: zip() argument 2 is longer than argument 1 1884 1885 Without the ``strict=True`` argument, any bug that results in iterables of 1886 different lengths will be silenced, possibly manifesting as a hard-to-find 1887 bug in another part of the program. 1888 1889 * Shorter iterables can be padded with a constant value to make all the 1890 iterables have the same length. This is done by 1891 :func:`itertools.zip_longest`. 1892 1893 Edge cases: With a single iterable argument, :func:`zip` returns an 1894 iterator of 1-tuples. With no arguments, it returns an empty iterator. 1895 1896 Tips and tricks: 1897 1898 * The left-to-right evaluation order of the iterables is guaranteed. This 1899 makes possible an idiom for clustering a data series into n-length groups 1900 using ``zip(*[iter(s)]*n, strict=True)``. This repeats the *same* iterator 1901 ``n`` times so that each output tuple has the result of ``n`` calls to the 1902 iterator. This has the effect of dividing the input into n-length chunks. 1903 1904 * :func:`zip` in conjunction with the ``*`` operator can be used to unzip a 1905 list:: 1906 1907 >>> x = [1, 2, 3] 1908 >>> y = [4, 5, 6] 1909 >>> list(zip(x, y)) 1910 [(1, 4), (2, 5), (3, 6)] 1911 >>> x2, y2 = zip(*zip(x, y)) 1912 >>> x == list(x2) and y == list(y2) 1913 True 1914 1915 .. versionchanged:: 3.10 1916 Added the ``strict`` argument. 1917 1918 1919.. function:: __import__(name, globals=None, locals=None, fromlist=(), level=0) 1920 1921 .. index:: 1922 statement: import 1923 module: imp 1924 1925 .. note:: 1926 1927 This is an advanced function that is not needed in everyday Python 1928 programming, unlike :func:`importlib.import_module`. 1929 1930 This function is invoked by the :keyword:`import` statement. It can be 1931 replaced (by importing the :mod:`builtins` module and assigning to 1932 ``builtins.__import__``) in order to change semantics of the 1933 :keyword:`!import` statement, but doing so is **strongly** discouraged as it 1934 is usually simpler to use import hooks (see :pep:`302`) to attain the same 1935 goals and does not cause issues with code which assumes the default import 1936 implementation is in use. Direct use of :func:`__import__` is also 1937 discouraged in favor of :func:`importlib.import_module`. 1938 1939 The function imports the module *name*, potentially using the given *globals* 1940 and *locals* to determine how to interpret the name in a package context. 1941 The *fromlist* gives the names of objects or submodules that should be 1942 imported from the module given by *name*. The standard implementation does 1943 not use its *locals* argument at all and uses its *globals* only to 1944 determine the package context of the :keyword:`import` statement. 1945 1946 *level* specifies whether to use absolute or relative imports. ``0`` (the 1947 default) means only perform absolute imports. Positive values for 1948 *level* indicate the number of parent directories to search relative to the 1949 directory of the module calling :func:`__import__` (see :pep:`328` for the 1950 details). 1951 1952 When the *name* variable is of the form ``package.module``, normally, the 1953 top-level package (the name up till the first dot) is returned, *not* the 1954 module named by *name*. However, when a non-empty *fromlist* argument is 1955 given, the module named by *name* is returned. 1956 1957 For example, the statement ``import spam`` results in bytecode resembling the 1958 following code:: 1959 1960 spam = __import__('spam', globals(), locals(), [], 0) 1961 1962 The statement ``import spam.ham`` results in this call:: 1963 1964 spam = __import__('spam.ham', globals(), locals(), [], 0) 1965 1966 Note how :func:`__import__` returns the toplevel module here because this is 1967 the object that is bound to a name by the :keyword:`import` statement. 1968 1969 On the other hand, the statement ``from spam.ham import eggs, sausage as 1970 saus`` results in :: 1971 1972 _temp = __import__('spam.ham', globals(), locals(), ['eggs', 'sausage'], 0) 1973 eggs = _temp.eggs 1974 saus = _temp.sausage 1975 1976 Here, the ``spam.ham`` module is returned from :func:`__import__`. From this 1977 object, the names to import are retrieved and assigned to their respective 1978 names. 1979 1980 If you simply want to import a module (potentially within a package) by name, 1981 use :func:`importlib.import_module`. 1982 1983 .. versionchanged:: 3.3 1984 Negative values for *level* are no longer supported (which also changes 1985 the default value to 0). 1986 1987 .. versionchanged:: 3.9 1988 When the command line options :option:`-E` or :option:`-I` are being used, 1989 the environment variable :envvar:`PYTHONCASEOK` is now ignored. 1990 1991.. rubric:: Footnotes 1992 1993.. [#] Note that the parser only accepts the Unix-style end of line convention. 1994 If you are reading the code from a file, make sure to use newline conversion 1995 mode to convert Windows or Mac-style newlines. 1996