| 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. |