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