Debian Codegraph @

Doc/library/functions.rst

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