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