| 1 |
|
| 2 |
.. _expressions: |
| 3 |
|
| 4 |
*********** |
| 5 |
Expressions |
| 6 |
*********** |
| 7 |
|
| 8 |
.. index:: expression, BNF |
| 9 |
|
| 10 |
This chapter explains the meaning of the elements of expressions in Python. |
| 11 |
|
| 12 |
**Syntax Notes:** In this and the following chapters, |
| 13 |
:ref:`grammar notation <notation>` will be used to describe syntax, |
| 14 |
not lexical analysis. |
| 15 |
|
| 16 |
When (one alternative of) a syntax rule has the form: |
| 17 |
|
| 18 |
.. productionlist:: python-grammar |
| 19 |
name: othername |
| 20 |
|
| 21 |
and no semantics are given, the semantics of this form of ``name`` are the same |
| 22 |
as for ``othername``. |
| 23 |
|
| 24 |
|
| 25 |
.. _conversions: |
| 26 |
|
| 27 |
Arithmetic conversions |
| 28 |
====================== |
| 29 |
|
| 30 |
.. index:: pair: arithmetic; conversion |
| 31 |
|
| 32 |
When a description of an arithmetic operator below uses the phrase "the numeric |
| 33 |
arguments are converted to a common real type", this means that the operator |
| 34 |
implementation for built-in numeric types works as described in the |
| 35 |
:ref:`Numeric Types <stdtypes-mixed-arithmetic>` section of the standard |
| 36 |
library documentation. |
| 37 |
|
| 38 |
Some additional rules apply for certain operators and non-numeric operands |
| 39 |
(for example, a string as a left argument to the ``%`` operator). |
| 40 |
Extensions must define their own conversion behavior. |
| 41 |
|
| 42 |
|
| 43 |
.. _atoms: |
| 44 |
|
| 45 |
Atoms |
| 46 |
===== |
| 47 |
|
| 48 |
.. index:: atom |
| 49 |
|
| 50 |
Atoms are the most basic elements of expressions. |
| 51 |
The simplest atoms are :ref:`names <identifiers>` or literals. |
| 52 |
Forms enclosed in parentheses, brackets or braces are also categorized |
| 53 |
syntactically as atoms. |
| 54 |
|
| 55 |
Formally, the syntax for atoms is: |
| 56 |
|
| 57 |
.. grammar-snippet:: |
| 58 |
:group: python-grammar |
| 59 |
|
| 60 |
atom: |
| 61 |
| 'True' |
| 62 |
| 'False' |
| 63 |
| 'None' |
| 64 |
| '...' |
| 65 |
| `identifier` |
| 66 |
| `literal` |
| 67 |
| `enclosure` |
| 68 |
enclosure: |
| 69 |
| `parenth_form` |
| 70 |
| `list_display` |
| 71 |
| `dict_display` |
| 72 |
| `set_display` |
| 73 |
| `generator_expression` |
| 74 |
| `yield_atom` |
| 75 |
|
| 76 |
|
| 77 |
.. _atom-singletons: |
| 78 |
|
| 79 |
Built-in constants |
| 80 |
------------------ |
| 81 |
|
| 82 |
The keywords ``True``, ``False``, and ``None`` name |
| 83 |
:ref:`built-in constants <built-in-consts>`. |
| 84 |
The token ``...`` names the :py:data:`Ellipsis` constant. |
| 85 |
|
| 86 |
Evaluation of these atoms yields the corresponding value. |
| 87 |
|
| 88 |
.. note:: |
| 89 |
|
| 90 |
Several more built-in constants are available as global variables, |
| 91 |
but only the ones mentioned here are :ref:`keywords <keywords>`. |
| 92 |
In particular, these names cannot be reassigned or used as attributes: |
| 93 |
|
| 94 |
.. code-block:: pycon |
| 95 |
|
| 96 |
>>> False = 123 |
| 97 |
File "<input>", line 1 |
| 98 |
False = 123 |
| 99 |
^^^^^ |
| 100 |
SyntaxError: cannot assign to False |
| 101 |
|
| 102 |
.. _atom-identifiers: |
| 103 |
|
| 104 |
Identifiers (Names) |
| 105 |
------------------- |
| 106 |
|
| 107 |
.. index:: name, identifier |
| 108 |
|
| 109 |
An identifier occurring as an atom is a name. See section :ref:`identifiers` |
| 110 |
for lexical definition and section :ref:`naming` for documentation of naming and |
| 111 |
binding. |
| 112 |
|
| 113 |
.. index:: pair: exception; NameError |
| 114 |
|
| 115 |
When the name is bound to an object, evaluation of the atom yields that object. |
| 116 |
When a name is not bound, an attempt to evaluate it raises a :exc:`NameError` |
| 117 |
exception. |
| 118 |
|
| 119 |
.. _private-name-mangling: |
| 120 |
|
| 121 |
.. index:: |
| 122 |
pair: name; mangling |
| 123 |
pair: private; names |
| 124 |
|
| 125 |
Private name mangling |
| 126 |
^^^^^^^^^^^^^^^^^^^^^ |
| 127 |
|
| 128 |
When an identifier that textually occurs in a class definition begins with two |
| 129 |
or more underscore characters and does not end in two or more underscores, it |
| 130 |
is considered a :dfn:`private name` of that class. |
| 131 |
|
| 132 |
.. seealso:: |
| 133 |
|
| 134 |
The :ref:`class specifications <class>`. |
| 135 |
|
| 136 |
More precisely, private names are transformed to a longer form before code is |
| 137 |
generated for them. If the transformed name is longer than 255 characters, |
| 138 |
implementation-defined truncation may happen. |
| 139 |
|
| 140 |
The transformation is independent of the syntactical context in which the |
| 141 |
identifier is used but only the following private identifiers are mangled: |
| 142 |
|
| 143 |
- Any name used as the name of a variable that is assigned or read or any |
| 144 |
name of an attribute being accessed. |
| 145 |
|
| 146 |
The :attr:`~definition.__name__` attribute of nested functions, classes, and |
| 147 |
type aliases is however not mangled. |
| 148 |
|
| 149 |
- The name of imported modules, e.g., ``__spam`` in ``import __spam``. |
| 150 |
If the module is part of a package (i.e., its name contains a dot), |
| 151 |
the name is *not* mangled, e.g., the ``__foo`` in ``import __foo.bar`` |
| 152 |
is not mangled. |
| 153 |
|
| 154 |
- The name of an imported member, e.g., ``__f`` in ``from spam import __f``. |
| 155 |
|
| 156 |
The transformation rule is defined as follows: |
| 157 |
|
| 158 |
- The class name, with leading underscores removed and a single leading |
| 159 |
underscore inserted, is inserted in front of the identifier, e.g., the |
| 160 |
identifier ``__spam`` occurring in a class named ``Foo``, ``_Foo`` or |
| 161 |
``__Foo`` is transformed to ``_Foo__spam``. |
| 162 |
|
| 163 |
- If the class name consists only of underscores, the transformation is the |
| 164 |
identity, e.g., the identifier ``__spam`` occurring in a class named ``_`` |
| 165 |
or ``__`` is left as is. |
| 166 |
|
| 167 |
.. _atom-literals: |
| 168 |
|
| 169 |
Literals |
| 170 |
-------- |
| 171 |
|
| 172 |
.. index:: single: literal |
| 173 |
|
| 174 |
A :dfn:`literal` is a textual representation of a value. |
| 175 |
Python supports numeric, string and bytes literals. |
| 176 |
:ref:`Format strings <f-strings>` and :ref:`template strings <t-strings>` |
| 177 |
are treated as string literals. |
| 178 |
|
| 179 |
Numeric literals consist of a single :token:`NUMBER <python-grammar:NUMBER>` |
| 180 |
token, which names an integer, floating-point number, or an imaginary number. |
| 181 |
See the :ref:`numbers` section in Lexical analysis documentation for details. |
| 182 |
|
| 183 |
String and bytes literals may consist of several tokens. |
| 184 |
See section :ref:`string-concatenation` for details. |
| 185 |
|
| 186 |
Note that negative and complex numbers, like ``-3`` or ``3+4.2j``, |
| 187 |
are syntactically not literals, but :ref:`unary <unary>` or |
| 188 |
:ref:`binary <binary>` arithmetic operations involving the ``-`` or ``+`` |
| 189 |
operator. |
| 190 |
|
| 191 |
Evaluation of a literal yields an object of the given type |
| 192 |
(:class:`int`, :class:`float`, :class:`complex`, :class:`str`, |
| 193 |
:class:`bytes`, or :class:`~string.templatelib.Template`) with the given value. |
| 194 |
The value may be approximated in the case of floating-point |
| 195 |
and imaginary literals. |
| 196 |
|
| 197 |
The formal grammar for literals is: |
| 198 |
|
| 199 |
.. grammar-snippet:: |
| 200 |
:group: python-grammar |
| 201 |
|
| 202 |
literal: `strings` | `NUMBER` |
| 203 |
|
| 204 |
|
| 205 |
.. index:: |
| 206 |
triple: immutable; data; type |
| 207 |
pair: immutable; object |
| 208 |
|
| 209 |
Literals and object identity |
| 210 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 211 |
|
| 212 |
All literals correspond to immutable data types, and hence the object's identity |
| 213 |
is less important than its value. Multiple evaluations of literals with the |
| 214 |
same value (either the same occurrence in the program text or a different |
| 215 |
occurrence) may obtain the same object or a different object with the same |
| 216 |
value. |
| 217 |
|
| 218 |
.. admonition:: CPython implementation detail |
| 219 |
|
| 220 |
For example, in CPython, *small* integers with the same value evaluate |
| 221 |
to the same object:: |
| 222 |
|
| 223 |
>>> x = 7 |
| 224 |
>>> y = 7 |
| 225 |
>>> x is y |
| 226 |
True |
| 227 |
|
| 228 |
However, large integers evaluate to different objects:: |
| 229 |
|
| 230 |
>>> x = 123456789 |
| 231 |
>>> y = 123456789 |
| 232 |
>>> x is y |
| 233 |
False |
| 234 |
|
| 235 |
This behavior may change in future versions of CPython. |
| 236 |
In particular, the boundary between "small" and "large" integers has |
| 237 |
already changed in the past. |
| 238 |
|
| 239 |
CPython will emit a :py:exc:`SyntaxWarning` when you compare literals |
| 240 |
using ``is``:: |
| 241 |
|
| 242 |
>>> x = 7 |
| 243 |
>>> x is 7 |
| 244 |
<input>:1: SyntaxWarning: "is" with 'int' literal. Did you mean "=="? |
| 245 |
True |
| 246 |
|
| 247 |
See :ref:`faq-identity-with-is` for more information. |
| 248 |
|
| 249 |
:ref:`Template strings <t-strings>` are immutable but may reference mutable |
| 250 |
objects as :class:`~string.templatelib.Interpolation` values. |
| 251 |
For the purposes of this section, two t-strings have the "same value" if |
| 252 |
both their structure and the *identity* of the values match. |
| 253 |
|
| 254 |
.. impl-detail:: |
| 255 |
|
| 256 |
Currently, each evaluation of a template string results in |
| 257 |
a different object. |
| 258 |
|
| 259 |
|
| 260 |
.. _string-concatenation: |
| 261 |
|
| 262 |
String literal concatenation |
| 263 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 264 |
|
| 265 |
Multiple adjacent string or bytes literals, possibly |
| 266 |
using different quoting conventions, are allowed, and their meaning is the same |
| 267 |
as their concatenation:: |
| 268 |
|
| 269 |
>>> "hello" 'world' |
| 270 |
"helloworld" |
| 271 |
|
| 272 |
This feature is defined at the syntactical level, so it only works with literals. |
| 273 |
To concatenate string expressions at run time, the '+' operator may be used:: |
| 274 |
|
| 275 |
>>> greeting = "Hello" |
| 276 |
>>> space = " " |
| 277 |
>>> name = "Blaise" |
| 278 |
>>> print(greeting + space + name) # not: print(greeting space name) |
| 279 |
Hello Blaise |
| 280 |
|
| 281 |
Literal concatenation can freely mix raw strings, triple-quoted strings, |
| 282 |
and formatted string literals. |
| 283 |
For example:: |
| 284 |
|
| 285 |
>>> "Hello" r', ' f"{name}!" |
| 286 |
"Hello, Blaise!" |
| 287 |
|
| 288 |
This feature can be used to reduce the number of backslashes |
| 289 |
needed, to split long strings conveniently across long lines, or even to add |
| 290 |
comments to parts of strings. For example:: |
| 291 |
|
| 292 |
re.compile("[A-Za-z_]" # letter or underscore |
| 293 |
"[A-Za-z0-9_]*" # letter, digit or underscore |
| 294 |
) |
| 295 |
|
| 296 |
However, bytes literals may only be combined with other byte literals; |
| 297 |
not with string literals of any kind. |
| 298 |
Also, template string literals may only be combined with other template |
| 299 |
string literals:: |
| 300 |
|
| 301 |
>>> t"Hello" t"{name}!" |
| 302 |
Template(strings=('Hello', '!'), interpolations=(...)) |
| 303 |
|
| 304 |
Formally: |
| 305 |
|
| 306 |
.. grammar-snippet:: |
| 307 |
:group: python-grammar |
| 308 |
|
| 309 |
strings: (`STRING` | `fstring`)+ | `tstring`+ |
| 310 |
|
| 311 |
|
| 312 |
.. _parenthesized: |
| 313 |
|
| 314 |
Parenthesized forms |
| 315 |
------------------- |
| 316 |
|
| 317 |
.. index:: |
| 318 |
single: parenthesized form |
| 319 |
single: () (parentheses); tuple display |
| 320 |
|
| 321 |
A parenthesized form is an optional expression list enclosed in parentheses: |
| 322 |
|
| 323 |
.. productionlist:: python-grammar |
| 324 |
parenth_form: "(" [`starred_expression`] ")" |
| 325 |
|
| 326 |
A parenthesized expression list yields whatever that expression list yields: if |
| 327 |
the list contains at least one comma, it yields a tuple; otherwise, it yields |
| 328 |
the single expression that makes up the expression list. |
| 329 |
|
| 330 |
.. index:: pair: empty; tuple |
| 331 |
|
| 332 |
An empty pair of parentheses yields an empty tuple object. Since tuples are |
| 333 |
immutable, the same rules as for literals apply (i.e., two occurrences of the empty |
| 334 |
tuple may or may not yield the same object). |
| 335 |
|
| 336 |
.. index:: |
| 337 |
single: comma |
| 338 |
single: , (comma) |
| 339 |
|
| 340 |
Note that tuples are not formed by the parentheses, but rather by use of the |
| 341 |
comma. The exception is the empty tuple, for which parentheses *are* |
| 342 |
required --- allowing unparenthesized "nothing" in expressions would cause |
| 343 |
ambiguities and allow common typos to pass uncaught. |
| 344 |
|
| 345 |
|
| 346 |
.. _comprehensions: |
| 347 |
|
| 348 |
Displays for lists, sets and dictionaries |
| 349 |
----------------------------------------- |
| 350 |
|
| 351 |
.. index:: single: comprehensions |
| 352 |
|
| 353 |
For constructing a list, a set or a dictionary Python provides special syntax |
| 354 |
called "displays", each of them in two flavors: |
| 355 |
|
| 356 |
* either the container contents are listed explicitly, or |
| 357 |
|
| 358 |
* they are computed via a set of looping and filtering instructions, called a |
| 359 |
:dfn:`comprehension`. |
| 360 |
|
| 361 |
.. index:: |
| 362 |
single: for; in comprehensions |
| 363 |
single: if; in comprehensions |
| 364 |
single: async for; in comprehensions |
| 365 |
|
| 366 |
Common syntax elements for comprehensions are: |
| 367 |
|
| 368 |
.. productionlist:: python-grammar |
| 369 |
comprehension: `assignment_expression` `comp_for` |
| 370 |
comp_for: ["async"] "for" `target_list` "in" `or_test` [`comp_iter`] |
| 371 |
comp_iter: `comp_for` | `comp_if` |
| 372 |
comp_if: "if" `or_test` [`comp_iter`] |
| 373 |
|
| 374 |
The comprehension consists of a single expression followed by at least one |
| 375 |
:keyword:`!for` clause and zero or more :keyword:`!for` or :keyword:`!if` clauses. |
| 376 |
In this case, the elements of the new container are those that would be produced |
| 377 |
by considering each of the :keyword:`!for` or :keyword:`!if` clauses a block, |
| 378 |
nesting from left to right, and evaluating the expression to produce an element |
| 379 |
each time the innermost block is reached. |
| 380 |
|
| 381 |
However, aside from the iterable expression in the leftmost :keyword:`!for` clause, |
| 382 |
the comprehension is executed in a separate implicitly nested scope. This ensures |
| 383 |
that names assigned to in the target list don't "leak" into the enclosing scope. |
| 384 |
|
| 385 |
The iterable expression in the leftmost :keyword:`!for` clause is evaluated |
| 386 |
directly in the enclosing scope and then passed as an argument to the implicitly |
| 387 |
nested scope. Subsequent :keyword:`!for` clauses and any filter condition in the |
| 388 |
leftmost :keyword:`!for` clause cannot be evaluated in the enclosing scope as |
| 389 |
they may depend on the values obtained from the leftmost iterable. For example: |
| 390 |
``[x*y for x in range(10) for y in range(x, x+10)]``. |
| 391 |
|
| 392 |
To ensure the comprehension always results in a container of the appropriate |
| 393 |
type, ``yield`` and ``yield from`` expressions are prohibited in the implicitly |
| 394 |
nested scope. |
| 395 |
|
| 396 |
.. index:: |
| 397 |
single: await; in comprehensions |
| 398 |
|
| 399 |
Since Python 3.6, in an :keyword:`async def` function, an :keyword:`!async for` |
| 400 |
clause may be used to iterate over a :term:`asynchronous iterator`. |
| 401 |
A comprehension in an :keyword:`!async def` function may consist of either a |
| 402 |
:keyword:`!for` or :keyword:`!async for` clause following the leading |
| 403 |
expression, may contain additional :keyword:`!for` or :keyword:`!async for` |
| 404 |
clauses, and may also use :keyword:`await` expressions. |
| 405 |
|
| 406 |
If a comprehension contains :keyword:`!async for` clauses, or if it contains |
| 407 |
:keyword:`!await` expressions or other asynchronous comprehensions anywhere except |
| 408 |
the iterable expression in the leftmost :keyword:`!for` clause, it is called an |
| 409 |
:dfn:`asynchronous comprehension`. An asynchronous comprehension may suspend the |
| 410 |
execution of the coroutine function in which it appears. |
| 411 |
See also :pep:`530`. |
| 412 |
|
| 413 |
.. versionadded:: 3.6 |
| 414 |
Asynchronous comprehensions were introduced. |
| 415 |
|
| 416 |
.. versionchanged:: 3.8 |
| 417 |
``yield`` and ``yield from`` prohibited in the implicitly nested scope. |
| 418 |
|
| 419 |
.. versionchanged:: 3.11 |
| 420 |
Asynchronous comprehensions are now allowed inside comprehensions in |
| 421 |
asynchronous functions. Outer comprehensions implicitly become |
| 422 |
asynchronous. |
| 423 |
|
| 424 |
|
| 425 |
.. _lists: |
| 426 |
|
| 427 |
List displays |
| 428 |
------------- |
| 429 |
|
| 430 |
.. index:: |
| 431 |
pair: list; display |
| 432 |
pair: list; comprehensions |
| 433 |
pair: empty; list |
| 434 |
pair: object; list |
| 435 |
single: [] (square brackets); list expression |
| 436 |
single: , (comma); expression list |
| 437 |
|
| 438 |
A list display is a possibly empty series of expressions enclosed in square |
| 439 |
brackets: |
| 440 |
|
| 441 |
.. productionlist:: python-grammar |
| 442 |
list_display: "[" [`flexible_expression_list` | `comprehension`] "]" |
| 443 |
|
| 444 |
A list display yields a new list object, the contents being specified by either |
| 445 |
a list of expressions or a comprehension. When a comma-separated list of |
| 446 |
expressions is supplied, its elements are evaluated from left to right and |
| 447 |
placed into the list object in that order. When a comprehension is supplied, |
| 448 |
the list is constructed from the elements resulting from the comprehension. |
| 449 |
|
| 450 |
|
| 451 |
.. _set: |
| 452 |
|
| 453 |
Set displays |
| 454 |
------------ |
| 455 |
|
| 456 |
.. index:: |
| 457 |
pair: set; display |
| 458 |
pair: set; comprehensions |
| 459 |
pair: object; set |
| 460 |
single: {} (curly brackets); set expression |
| 461 |
single: , (comma); expression list |
| 462 |
|
| 463 |
A set display is denoted by curly braces and distinguishable from dictionary |
| 464 |
displays by the lack of colons separating keys and values: |
| 465 |
|
| 466 |
.. productionlist:: python-grammar |
| 467 |
set_display: "{" (`flexible_expression_list` | `comprehension`) "}" |
| 468 |
|
| 469 |
A set display yields a new mutable set object, the contents being specified by |
| 470 |
either a sequence of expressions or a comprehension. When a comma-separated |
| 471 |
list of expressions is supplied, its elements are evaluated from left to right |
| 472 |
and added to the set object. When a comprehension is supplied, the set is |
| 473 |
constructed from the elements resulting from the comprehension. |
| 474 |
|
| 475 |
An empty set cannot be constructed with ``{}``; this literal constructs an empty |
| 476 |
dictionary. |
| 477 |
|
| 478 |
|
| 479 |
.. _dict: |
| 480 |
|
| 481 |
Dictionary displays |
| 482 |
------------------- |
| 483 |
|
| 484 |
.. index:: |
| 485 |
pair: dictionary; display |
| 486 |
pair: dictionary; comprehensions |
| 487 |
key, value, key/value pair |
| 488 |
pair: object; dictionary |
| 489 |
single: {} (curly brackets); dictionary expression |
| 490 |
single: : (colon); in dictionary expressions |
| 491 |
single: , (comma); in dictionary displays |
| 492 |
|
| 493 |
A dictionary display is a possibly empty series of dict items (key/value pairs) |
| 494 |
enclosed in curly braces: |
| 495 |
|
| 496 |
.. productionlist:: python-grammar |
| 497 |
dict_display: "{" [`dict_item_list` | `dict_comprehension`] "}" |
| 498 |
dict_item_list: `dict_item` ("," `dict_item`)* [","] |
| 499 |
dict_item: `expression` ":" `expression` | "**" `or_expr` |
| 500 |
dict_comprehension: `expression` ":" `expression` `comp_for` |
| 501 |
|
| 502 |
A dictionary display yields a new dictionary object. |
| 503 |
|
| 504 |
If a comma-separated sequence of dict items is given, they are evaluated |
| 505 |
from left to right to define the entries of the dictionary: each key object is |
| 506 |
used as a key into the dictionary to store the corresponding value. This means |
| 507 |
that you can specify the same key multiple times in the dict item list, and the |
| 508 |
final dictionary's value for that key will be the last one given. |
| 509 |
|
| 510 |
.. index:: |
| 511 |
unpacking; dictionary |
| 512 |
single: **; in dictionary displays |
| 513 |
|
| 514 |
A double asterisk ``**`` denotes :dfn:`dictionary unpacking`. |
| 515 |
Its operand must be a :term:`mapping`. Each mapping item is added |
| 516 |
to the new dictionary. Later values replace values already set by |
| 517 |
earlier dict items and earlier dictionary unpackings. |
| 518 |
|
| 519 |
.. versionadded:: 3.5 |
| 520 |
Unpacking into dictionary displays, originally proposed by :pep:`448`. |
| 521 |
|
| 522 |
A dict comprehension, in contrast to list and set comprehensions, needs two |
| 523 |
expressions separated with a colon followed by the usual "for" and "if" clauses. |
| 524 |
When the comprehension is run, the resulting key and value elements are inserted |
| 525 |
in the new dictionary in the order they are produced. |
| 526 |
|
| 527 |
.. index:: pair: immutable; object |
| 528 |
hashable |
| 529 |
|
| 530 |
Restrictions on the types of the key values are listed earlier in section |
| 531 |
:ref:`types`. (To summarize, the key type should be :term:`hashable`, which excludes |
| 532 |
all mutable objects.) Clashes between duplicate keys are not detected; the last |
| 533 |
value (textually rightmost in the display) stored for a given key value |
| 534 |
prevails. |
| 535 |
|
| 536 |
.. versionchanged:: 3.8 |
| 537 |
Prior to Python 3.8, in dict comprehensions, the evaluation order of key |
| 538 |
and value was not well-defined. In CPython, the value was evaluated before |
| 539 |
the key. Starting with 3.8, the key is evaluated before the value, as |
| 540 |
proposed by :pep:`572`. |
| 541 |
|
| 542 |
|
| 543 |
.. _genexpr: |
| 544 |
|
| 545 |
Generator expressions |
| 546 |
--------------------- |
| 547 |
|
| 548 |
.. index:: |
| 549 |
pair: generator; expression |
| 550 |
pair: object; generator |
| 551 |
single: () (parentheses); generator expression |
| 552 |
|
| 553 |
A generator expression is a compact generator notation in parentheses: |
| 554 |
|
| 555 |
.. productionlist:: python-grammar |
| 556 |
generator_expression: "(" `expression` `comp_for` ")" |
| 557 |
|
| 558 |
A generator expression yields a new generator object. Its syntax is the same as |
| 559 |
for comprehensions, except that it is enclosed in parentheses instead of |
| 560 |
brackets or curly braces. |
| 561 |
|
| 562 |
Variables used in the generator expression are evaluated lazily when the |
| 563 |
:meth:`~generator.__next__` method is called for the generator object (in the same |
| 564 |
fashion as normal generators). However, the iterable expression in the |
| 565 |
leftmost :keyword:`!for` clause is immediately evaluated, and the |
| 566 |
:term:`iterator` is immediately created for that iterable, so that an error |
| 567 |
produced while creating the iterator will be emitted at the point where the generator expression |
| 568 |
is defined, rather than at the point where the first value is retrieved. |
| 569 |
Subsequent :keyword:`!for` clauses and any filter condition in the leftmost |
| 570 |
:keyword:`!for` clause cannot be evaluated in the enclosing scope as they may |
| 571 |
depend on the values obtained from the leftmost iterable. For example: |
| 572 |
``(x*y for x in range(10) for y in range(x, x+10))``. |
| 573 |
|
| 574 |
The parentheses can be omitted on calls with only one argument. See section |
| 575 |
:ref:`calls` for details. |
| 576 |
|
| 577 |
To avoid interfering with the expected operation of the generator expression |
| 578 |
itself, ``yield`` and ``yield from`` expressions are prohibited in the |
| 579 |
implicitly defined generator. |
| 580 |
|
| 581 |
If a generator expression contains either :keyword:`!async for` |
| 582 |
clauses or :keyword:`await` expressions it is called an |
| 583 |
:dfn:`asynchronous generator expression`. An asynchronous generator |
| 584 |
expression returns a new asynchronous generator object, |
| 585 |
which is an asynchronous iterator (see :ref:`async-iterators`). |
| 586 |
|
| 587 |
.. versionadded:: 3.6 |
| 588 |
Asynchronous generator expressions were introduced. |
| 589 |
|
| 590 |
.. versionchanged:: 3.7 |
| 591 |
Prior to Python 3.7, asynchronous generator expressions could |
| 592 |
only appear in :keyword:`async def` coroutines. Starting |
| 593 |
with 3.7, any function can use asynchronous generator expressions. |
| 594 |
|
| 595 |
.. versionchanged:: 3.8 |
| 596 |
``yield`` and ``yield from`` prohibited in the implicitly nested scope. |
| 597 |
|
| 598 |
|
| 599 |
.. _yieldexpr: |
| 600 |
|
| 601 |
Yield expressions |
| 602 |
----------------- |
| 603 |
|
| 604 |
.. index:: |
| 605 |
pair: keyword; yield |
| 606 |
pair: keyword; from |
| 607 |
pair: yield; expression |
| 608 |
pair: generator; function |
| 609 |
|
| 610 |
.. productionlist:: python-grammar |
| 611 |
yield_atom: "(" `yield_expression` ")" |
| 612 |
yield_from: "yield" "from" `expression` |
| 613 |
yield_expression: "yield" `yield_list` | `yield_from` |
| 614 |
|
| 615 |
The yield expression is used when defining a :term:`generator` function |
| 616 |
or an :term:`asynchronous generator` function and |
| 617 |
thus can only be used in the body of a function definition. Using a yield |
| 618 |
expression in a function's body causes that function to be a generator function, |
| 619 |
and using it in an :keyword:`async def` function's body causes that |
| 620 |
coroutine function to be an asynchronous generator function. For example:: |
| 621 |
|
| 622 |
def gen(): # defines a generator function |
| 623 |
yield 123 |
| 624 |
|
| 625 |
async def agen(): # defines an asynchronous generator function |
| 626 |
yield 123 |
| 627 |
|
| 628 |
Due to their side effects on the containing scope, ``yield`` expressions |
| 629 |
are not permitted as part of the implicitly defined scopes used to |
| 630 |
implement comprehensions and generator expressions. |
| 631 |
|
| 632 |
.. versionchanged:: 3.8 |
| 633 |
Yield expressions prohibited in the implicitly nested scopes used to |
| 634 |
implement comprehensions and generator expressions. |
| 635 |
|
| 636 |
Generator functions are described below, while asynchronous generator |
| 637 |
functions are described separately in section |
| 638 |
:ref:`asynchronous-generator-functions`. |
| 639 |
|
| 640 |
When a generator function is called, it returns an iterator known as a |
| 641 |
generator. That generator then controls the execution of the generator |
| 642 |
function. The execution starts when one of the generator's methods is called. |
| 643 |
At that time, the execution proceeds to the first yield expression, where it is |
| 644 |
suspended again, returning the value of :token:`~python-grammar:yield_list` |
| 645 |
to the generator's caller, |
| 646 |
or ``None`` if :token:`~python-grammar:yield_list` is omitted. |
| 647 |
By suspended, we mean that all local state is |
| 648 |
retained, including the current bindings of local variables, the instruction |
| 649 |
pointer, the internal evaluation stack, and the state of any exception handling. |
| 650 |
When the execution is resumed by calling one of the generator's methods, the |
| 651 |
function can proceed exactly as if the yield expression were just another |
| 652 |
external call. The value of the yield expression after resuming depends on the |
| 653 |
method which resumed the execution. If :meth:`~generator.__next__` is used |
| 654 |
(typically via either a :keyword:`for` or the :func:`next` builtin) then the |
| 655 |
result is :const:`None`. Otherwise, if :meth:`~generator.send` is used, then |
| 656 |
the result will be the value passed in to that method. |
| 657 |
|
| 658 |
.. index:: single: coroutine |
| 659 |
|
| 660 |
All of this makes generator functions quite similar to coroutines; they yield |
| 661 |
multiple times, they have more than one entry point and their execution can be |
| 662 |
suspended. The only difference is that a generator function cannot control |
| 663 |
where the execution should continue after it yields; the control is always |
| 664 |
transferred to the generator's caller. |
| 665 |
|
| 666 |
Yield expressions are allowed anywhere in a :keyword:`try` construct. If the |
| 667 |
generator is not resumed before it is |
| 668 |
finalized (by reaching a zero reference count or by being garbage collected), |
| 669 |
the generator-iterator's :meth:`~generator.close` method will be called, |
| 670 |
allowing any pending :keyword:`finally` clauses to execute. |
| 671 |
|
| 672 |
.. index:: |
| 673 |
single: from; yield from expression |
| 674 |
|
| 675 |
When ``yield from <expr>`` is used, the supplied expression must be an |
| 676 |
iterable. The values produced by iterating that iterable are passed directly |
| 677 |
to the caller of the current generator's methods. Any values passed in with |
| 678 |
:meth:`~generator.send` and any exceptions passed in with |
| 679 |
:meth:`~generator.throw` are passed to the underlying iterator if it has the |
| 680 |
appropriate methods. If this is not the case, then :meth:`~generator.send` |
| 681 |
will raise :exc:`AttributeError` or :exc:`TypeError`, while |
| 682 |
:meth:`~generator.throw` will just raise the passed in exception immediately. |
| 683 |
|
| 684 |
When the underlying iterator is complete, the :attr:`~StopIteration.value` |
| 685 |
attribute of the raised :exc:`StopIteration` instance becomes the value of |
| 686 |
the yield expression. It can be either set explicitly when raising |
| 687 |
:exc:`StopIteration`, or automatically when the subiterator is a generator |
| 688 |
(by returning a value from the subgenerator). |
| 689 |
|
| 690 |
.. versionchanged:: 3.3 |
| 691 |
Added ``yield from <expr>`` to delegate control flow to a subiterator. |
| 692 |
|
| 693 |
The parentheses may be omitted when the yield expression is the sole expression |
| 694 |
on the right hand side of an assignment statement. |
| 695 |
|
| 696 |
.. seealso:: |
| 697 |
|
| 698 |
:pep:`255` - Simple Generators |
| 699 |
The proposal for adding generators and the :keyword:`yield` statement to Python. |
| 700 |
|
| 701 |
:pep:`342` - Coroutines via Enhanced Generators |
| 702 |
The proposal to enhance the API and syntax of generators, making them |
| 703 |
usable as simple coroutines. |
| 704 |
|
| 705 |
:pep:`380` - Syntax for Delegating to a Subgenerator |
| 706 |
The proposal to introduce the :token:`~python-grammar:yield_from` syntax, |
| 707 |
making delegation to subgenerators easy. |
| 708 |
|
| 709 |
:pep:`525` - Asynchronous Generators |
| 710 |
The proposal that expanded on :pep:`492` by adding generator capabilities to |
| 711 |
coroutine functions. |
| 712 |
|
| 713 |
.. index:: pair: object; generator |
| 714 |
.. _generator-methods: |
| 715 |
|
| 716 |
Generator-iterator methods |
| 717 |
^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 718 |
|
| 719 |
This subsection describes the methods of a generator iterator. They can |
| 720 |
be used to control the execution of a generator function. |
| 721 |
|
| 722 |
Note that calling any of the generator methods below when the generator |
| 723 |
is already executing raises a :exc:`ValueError` exception. |
| 724 |
|
| 725 |
.. index:: pair: exception; StopIteration |
| 726 |
|
| 727 |
|
| 728 |
.. method:: generator.__next__() |
| 729 |
|
| 730 |
Starts the execution of a generator function or resumes it at the last |
| 731 |
executed yield expression. When a generator function is resumed with a |
| 732 |
:meth:`~generator.__next__` method, the current yield expression always |
| 733 |
evaluates to :const:`None`. The execution then continues to the next yield |
| 734 |
expression, where the generator is suspended again, and the value of the |
| 735 |
:token:`~python-grammar:yield_list` is returned to :meth:`__next__`'s |
| 736 |
caller. If the generator exits without yielding another value, a |
| 737 |
:exc:`StopIteration` exception is raised. |
| 738 |
|
| 739 |
This method is normally called implicitly, e.g. by a :keyword:`for` loop, or |
| 740 |
by the built-in :func:`next` function. |
| 741 |
|
| 742 |
|
| 743 |
.. method:: generator.send(value) |
| 744 |
|
| 745 |
Resumes the execution and "sends" a value into the generator function. The |
| 746 |
*value* argument becomes the result of the current yield expression. The |
| 747 |
:meth:`send` method returns the next value yielded by the generator, or |
| 748 |
raises :exc:`StopIteration` if the generator exits without yielding another |
| 749 |
value. When :meth:`send` is called to start the generator, it must be called |
| 750 |
with :const:`None` as the argument, because there is no yield expression that |
| 751 |
could receive the value. |
| 752 |
|
| 753 |
|
| 754 |
.. method:: generator.throw(value) |
| 755 |
generator.throw(type[, value[, traceback]]) |
| 756 |
|
| 757 |
Raises an exception at the point where the generator was paused, |
| 758 |
and returns the next value yielded by the generator function. If the generator |
| 759 |
exits without yielding another value, a :exc:`StopIteration` exception is |
| 760 |
raised. If the generator function does not catch the passed-in exception, or |
| 761 |
raises a different exception, then that exception propagates to the caller. |
| 762 |
|
| 763 |
In typical use, this is called with a single exception instance similar to the |
| 764 |
way the :keyword:`raise` keyword is used. |
| 765 |
|
| 766 |
For backwards compatibility, however, the second signature is |
| 767 |
supported, following a convention from older versions of Python. |
| 768 |
The *type* argument should be an exception class, and *value* |
| 769 |
should be an exception instance. If the *value* is not provided, the |
| 770 |
*type* constructor is called to get an instance. If *traceback* |
| 771 |
is provided, it is set on the exception, otherwise any existing |
| 772 |
:attr:`~BaseException.__traceback__` attribute stored in *value* may |
| 773 |
be cleared. |
| 774 |
|
| 775 |
.. versionchanged:: 3.12 |
| 776 |
|
| 777 |
The second signature \(type\[, value\[, traceback\]\]\) is deprecated and |
| 778 |
may be removed in a future version of Python. |
| 779 |
|
| 780 |
.. index:: pair: exception; GeneratorExit |
| 781 |
|
| 782 |
|
| 783 |
.. method:: generator.close() |
| 784 |
|
| 785 |
Raises a :exc:`GeneratorExit` exception at the point where the generator |
| 786 |
function was paused (equivalent to calling ``throw(GeneratorExit)``). |
| 787 |
The exception is raised by the yield expression where the generator was paused. |
| 788 |
If the generator function catches the exception and returns a |
| 789 |
value, this value is returned from :meth:`close`. If the generator function |
| 790 |
is already closed, or raises :exc:`GeneratorExit` (by not catching the |
| 791 |
exception), :meth:`close` returns :const:`None`. If the generator yields a |
| 792 |
value, a :exc:`RuntimeError` is raised. If the generator raises any other |
| 793 |
exception, it is propagated to the caller. If the generator has already |
| 794 |
exited due to an exception or normal exit, :meth:`close` returns |
| 795 |
:const:`None` and has no other effect. |
| 796 |
|
| 797 |
.. versionchanged:: 3.13 |
| 798 |
|
| 799 |
If a generator returns a value upon being closed, the value is returned |
| 800 |
by :meth:`close`. |
| 801 |
|
| 802 |
.. index:: single: yield; examples |
| 803 |
|
| 804 |
Examples |
| 805 |
^^^^^^^^ |
| 806 |
|
| 807 |
Here is a simple example that demonstrates the behavior of generators and |
| 808 |
generator functions:: |
| 809 |
|
| 810 |
>>> def echo(value=None): |
| 811 |
... print("Execution starts when 'next()' is called for the first time.") |
| 812 |
... try: |
| 813 |
... while True: |
| 814 |
... try: |
| 815 |
... value = (yield value) |
| 816 |
... except Exception as e: |
| 817 |
... value = e |
| 818 |
... finally: |
| 819 |
... print("Don't forget to clean up when 'close()' is called.") |
| 820 |
... |
| 821 |
>>> generator = echo(1) |
| 822 |
>>> print(next(generator)) |
| 823 |
Execution starts when 'next()' is called for the first time. |
| 824 |
1 |
| 825 |
>>> print(next(generator)) |
| 826 |
None |
| 827 |
>>> print(generator.send(2)) |
| 828 |
2 |
| 829 |
>>> generator.throw(TypeError, "spam") |
| 830 |
TypeError('spam',) |
| 831 |
>>> generator.close() |
| 832 |
Don't forget to clean up when 'close()' is called. |
| 833 |
|
| 834 |
For examples using ``yield from``, see :ref:`pep-380` in "What's New in |
| 835 |
Python." |
| 836 |
|
| 837 |
.. _asynchronous-generator-functions: |
| 838 |
|
| 839 |
Asynchronous generator functions |
| 840 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 841 |
|
| 842 |
The presence of a yield expression in a function or method defined using |
| 843 |
:keyword:`async def` further defines the function as an |
| 844 |
:term:`asynchronous generator` function. |
| 845 |
|
| 846 |
When an asynchronous generator function is called, it returns an |
| 847 |
asynchronous iterator known as an asynchronous generator object. |
| 848 |
That object then controls the execution of the generator function. |
| 849 |
An asynchronous generator object is typically used in an |
| 850 |
:keyword:`async for` statement in a coroutine function analogously to |
| 851 |
how a generator object would be used in a :keyword:`for` statement. |
| 852 |
|
| 853 |
Calling one of the asynchronous generator's methods returns an :term:`awaitable` |
| 854 |
object, and the execution starts when this object is awaited on. At that time, |
| 855 |
the execution proceeds to the first yield expression, where it is suspended |
| 856 |
again, returning the value of :token:`~python-grammar:yield_list` to the |
| 857 |
awaiting coroutine. As with a generator, suspension means that all local state |
| 858 |
is retained, including the current bindings of local variables, the instruction |
| 859 |
pointer, the internal evaluation stack, and the state of any exception handling. |
| 860 |
When the execution is resumed by awaiting on the next object returned by the |
| 861 |
asynchronous generator's methods, the function can proceed exactly as if the |
| 862 |
yield expression were just another external call. The value of the yield |
| 863 |
expression after resuming depends on the method which resumed the execution. If |
| 864 |
:meth:`~agen.__anext__` is used then the result is :const:`None`. Otherwise, if |
| 865 |
:meth:`~agen.asend` is used, then the result will be the value passed in to that |
| 866 |
method. |
| 867 |
|
| 868 |
If an asynchronous generator happens to exit early by :keyword:`break`, the caller |
| 869 |
task being cancelled, or other exceptions, the generator's async cleanup code |
| 870 |
will run and possibly raise exceptions or access context variables in an |
| 871 |
unexpected context--perhaps after the lifetime of tasks it depends, or |
| 872 |
during the event loop shutdown when the async-generator garbage collection hook |
| 873 |
is called. |
| 874 |
To prevent this, the caller must explicitly close the async generator by calling |
| 875 |
:meth:`~agen.aclose` method to finalize the generator and ultimately detach it |
| 876 |
from the event loop. |
| 877 |
|
| 878 |
In an asynchronous generator function, yield expressions are allowed anywhere |
| 879 |
in a :keyword:`try` construct. However, if an asynchronous generator is not |
| 880 |
resumed before it is finalized (by reaching a zero reference count or by |
| 881 |
being garbage collected), then a yield expression within a :keyword:`!try` |
| 882 |
construct could result in a failure to execute pending :keyword:`finally` |
| 883 |
clauses. In this case, it is the responsibility of the event loop or |
| 884 |
scheduler running the asynchronous generator to call the asynchronous |
| 885 |
generator-iterator's :meth:`~agen.aclose` method and run the resulting |
| 886 |
coroutine object, thus allowing any pending :keyword:`!finally` clauses |
| 887 |
to execute. |
| 888 |
|
| 889 |
To take care of finalization upon event loop termination, an event loop should |
| 890 |
define a *finalizer* function which takes an asynchronous generator-iterator and |
| 891 |
presumably calls :meth:`~agen.aclose` and executes the coroutine. |
| 892 |
This *finalizer* may be registered by calling :func:`sys.set_asyncgen_hooks`. |
| 893 |
When first iterated over, an asynchronous generator-iterator will store the |
| 894 |
registered *finalizer* to be called upon finalization. For a reference example |
| 895 |
of a *finalizer* method see the implementation of |
| 896 |
``asyncio.Loop.shutdown_asyncgens`` in :source:`Lib/asyncio/base_events.py`. |
| 897 |
|
| 898 |
The expression ``yield from <expr>`` is a syntax error when used in an |
| 899 |
asynchronous generator function. |
| 900 |
|
| 901 |
.. index:: pair: object; asynchronous-generator |
| 902 |
.. _asynchronous-generator-methods: |
| 903 |
|
| 904 |
Asynchronous generator-iterator methods |
| 905 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 906 |
|
| 907 |
This subsection describes the methods of an asynchronous generator iterator, |
| 908 |
which are used to control the execution of a generator function. |
| 909 |
|
| 910 |
|
| 911 |
.. index:: pair: exception; StopAsyncIteration |
| 912 |
|
| 913 |
.. method:: agen.__anext__() |
| 914 |
:async: |
| 915 |
|
| 916 |
Returns an awaitable which when run starts to execute the asynchronous |
| 917 |
generator or resumes it at the last executed yield expression. When an |
| 918 |
asynchronous generator function is resumed with an :meth:`~agen.__anext__` |
| 919 |
method, the current yield expression always evaluates to :const:`None` in the |
| 920 |
returned awaitable, which when run will continue to the next yield |
| 921 |
expression. The value of the :token:`~python-grammar:yield_list` of the |
| 922 |
yield expression is the value of the :exc:`StopIteration` exception raised by |
| 923 |
the completing coroutine. If the asynchronous generator exits without |
| 924 |
yielding another value, the awaitable instead raises a |
| 925 |
:exc:`StopAsyncIteration` exception, signalling that the asynchronous |
| 926 |
iteration has completed. |
| 927 |
|
| 928 |
This method is normally called implicitly by a :keyword:`async for` loop. |
| 929 |
|
| 930 |
|
| 931 |
.. method:: agen.asend(value) |
| 932 |
:async: |
| 933 |
|
| 934 |
Returns an awaitable which when run resumes the execution of the |
| 935 |
asynchronous generator. As with the :meth:`~generator.send` method for a |
| 936 |
generator, this "sends" a value into the asynchronous generator function, |
| 937 |
and the *value* argument becomes the result of the current yield expression. |
| 938 |
The awaitable returned by the :meth:`asend` method will return the next |
| 939 |
value yielded by the generator as the value of the raised |
| 940 |
:exc:`StopIteration`, or raises :exc:`StopAsyncIteration` if the |
| 941 |
asynchronous generator exits without yielding another value. When |
| 942 |
:meth:`asend` is called to start the asynchronous |
| 943 |
generator, it must be called with :const:`None` as the argument, |
| 944 |
because there is no yield expression that could receive the value. |
| 945 |
|
| 946 |
|
| 947 |
.. method:: agen.athrow(value) |
| 948 |
agen.athrow(type[, value[, traceback]]) |
| 949 |
:async: |
| 950 |
|
| 951 |
Returns an awaitable that raises an exception of type ``type`` at the point |
| 952 |
where the asynchronous generator was paused, and returns the next value |
| 953 |
yielded by the generator function as the value of the raised |
| 954 |
:exc:`StopIteration` exception. If the asynchronous generator exits |
| 955 |
without yielding another value, a :exc:`StopAsyncIteration` exception is |
| 956 |
raised by the awaitable. |
| 957 |
If the generator function does not catch the passed-in exception, or |
| 958 |
raises a different exception, then when the awaitable is run that exception |
| 959 |
propagates to the caller of the awaitable. |
| 960 |
|
| 961 |
.. versionchanged:: 3.12 |
| 962 |
|
| 963 |
The second signature \(type\[, value\[, traceback\]\]\) is deprecated and |
| 964 |
may be removed in a future version of Python. |
| 965 |
|
| 966 |
.. index:: pair: exception; GeneratorExit |
| 967 |
|
| 968 |
|
| 969 |
.. method:: agen.aclose() |
| 970 |
:async: |
| 971 |
|
| 972 |
Returns an awaitable that when run will throw a :exc:`GeneratorExit` into |
| 973 |
the asynchronous generator function at the point where it was paused. |
| 974 |
If the asynchronous generator function then exits gracefully, is already |
| 975 |
closed, or raises :exc:`GeneratorExit` (by not catching the exception), |
| 976 |
then the returned awaitable will raise a :exc:`StopIteration` exception. |
| 977 |
Any further awaitables returned by subsequent calls to the asynchronous |
| 978 |
generator will raise a :exc:`StopAsyncIteration` exception. If the |
| 979 |
asynchronous generator yields a value, a :exc:`RuntimeError` is raised |
| 980 |
by the awaitable. If the asynchronous generator raises any other exception, |
| 981 |
it is propagated to the caller of the awaitable. If the asynchronous |
| 982 |
generator has already exited due to an exception or normal exit, then |
| 983 |
further calls to :meth:`aclose` will return an awaitable that does nothing. |
| 984 |
|
| 985 |
.. _primaries: |
| 986 |
|
| 987 |
Primaries |
| 988 |
========= |
| 989 |
|
| 990 |
.. index:: single: primary |
| 991 |
|
| 992 |
Primaries represent the most tightly bound operations of the language. Their |
| 993 |
syntax is: |
| 994 |
|
| 995 |
.. productionlist:: python-grammar |
| 996 |
primary: `atom` | `attributeref` | `subscription` | `call` |
| 997 |
|
| 998 |
|
| 999 |
.. _attribute-references: |
| 1000 |
|
| 1001 |
Attribute references |
| 1002 |
-------------------- |
| 1003 |
|
| 1004 |
.. index:: |
| 1005 |
pair: attribute; reference |
| 1006 |
single: . (dot); attribute reference |
| 1007 |
|
| 1008 |
An attribute reference is a primary followed by a period and a name: |
| 1009 |
|
| 1010 |
.. productionlist:: python-grammar |
| 1011 |
attributeref: `primary` "." `identifier` |
| 1012 |
|
| 1013 |
.. index:: |
| 1014 |
pair: exception; AttributeError |
| 1015 |
pair: object; module |
| 1016 |
pair: object; list |
| 1017 |
|
| 1018 |
The primary must evaluate to an object of a type that supports attribute |
| 1019 |
references, which most objects do. This object is then asked to produce the |
| 1020 |
attribute whose name is the identifier. The type and value produced is |
| 1021 |
determined by the object. Multiple evaluations of the same attribute |
| 1022 |
reference may yield different objects. |
| 1023 |
|
| 1024 |
This production can be customized by overriding the |
| 1025 |
:meth:`~object.__getattribute__` method or the :meth:`~object.__getattr__` |
| 1026 |
method. The :meth:`!__getattribute__` method is called first and either |
| 1027 |
returns a value or raises :exc:`AttributeError` if the attribute is not |
| 1028 |
available. |
| 1029 |
|
| 1030 |
If an :exc:`AttributeError` is raised and the object has a :meth:`!__getattr__` |
| 1031 |
method, that method is called as a fallback. |
| 1032 |
|
| 1033 |
.. _subscriptions: |
| 1034 |
|
| 1035 |
Subscriptions and slicings |
| 1036 |
-------------------------- |
| 1037 |
|
| 1038 |
.. index:: |
| 1039 |
single: subscription |
| 1040 |
single: [] (square brackets); subscription |
| 1041 |
|
| 1042 |
.. index:: |
| 1043 |
pair: object; sequence |
| 1044 |
pair: object; mapping |
| 1045 |
pair: object; string |
| 1046 |
pair: object; tuple |
| 1047 |
pair: object; list |
| 1048 |
pair: object; dictionary |
| 1049 |
pair: sequence; item |
| 1050 |
|
| 1051 |
The :dfn:`subscription` syntax is usually used for selecting an element from a |
| 1052 |
:ref:`container <sequence-types>` -- for example, to get a value from |
| 1053 |
a :class:`dict`:: |
| 1054 |
|
| 1055 |
>>> digits_by_name = {'one': 1, 'two': 2} |
| 1056 |
>>> digits_by_name['two'] # Subscripting a dictionary using the key 'two' |
| 1057 |
2 |
| 1058 |
|
| 1059 |
In the subscription syntax, the object being subscribed -- a |
| 1060 |
:ref:`primary <primaries>` -- is followed by a :dfn:`subscript` in |
| 1061 |
square brackets. |
| 1062 |
In the simplest case, the subscript is a single expression. |
| 1063 |
|
| 1064 |
Depending on the type of the object being subscribed, the subscript is |
| 1065 |
sometimes called a :term:`key` (for mappings), :term:`index` (for sequences), |
| 1066 |
or *type argument* (for :term:`generic types <generic type>`). |
| 1067 |
Syntactically, these are all equivalent:: |
| 1068 |
|
| 1069 |
>>> colors = ['red', 'blue', 'green', 'black'] |
| 1070 |
>>> colors[3] # Subscripting a list using the index 3 |
| 1071 |
'black' |
| 1072 |
|
| 1073 |
>>> list[str] # Parameterizing the list type using the type argument str |
| 1074 |
list[str] |
| 1075 |
|
| 1076 |
At runtime, the interpreter will evaluate the primary and |
| 1077 |
the subscript, and call the primary's :meth:`~object.__getitem__` or |
| 1078 |
:meth:`~object.__class_getitem__` :term:`special method` with the subscript |
| 1079 |
as argument. |
| 1080 |
For more details on which of these methods is called, see |
| 1081 |
:ref:`classgetitem-versus-getitem`. |
| 1082 |
|
| 1083 |
To show how subscription works, we can define a custom object that |
| 1084 |
implements :meth:`~object.__getitem__` and prints out the value of |
| 1085 |
the subscript:: |
| 1086 |
|
| 1087 |
>>> class SubscriptionDemo: |
| 1088 |
... def __getitem__(self, key): |
| 1089 |
... print(f'subscripted with: {key!r}') |
| 1090 |
... |
| 1091 |
>>> demo = SubscriptionDemo() |
| 1092 |
>>> demo[1] |
| 1093 |
subscripted with: 1 |
| 1094 |
>>> demo['a' * 3] |
| 1095 |
subscripted with: 'aaa' |
| 1096 |
|
| 1097 |
See :meth:`~object.__getitem__` documentation for how built-in types handle |
| 1098 |
subscription. |
| 1099 |
|
| 1100 |
Subscriptions may also be used as targets in :ref:`assignment <assignment>` or |
| 1101 |
:ref:`deletion <del>` statements. |
| 1102 |
In these cases, the interpreter will call the subscripted object's |
| 1103 |
:meth:`~object.__setitem__` or :meth:`~object.__delitem__` |
| 1104 |
:term:`special method`, respectively, instead of :meth:`~object.__getitem__`. |
| 1105 |
|
| 1106 |
.. code-block:: |
| 1107 |
|
| 1108 |
>>> colors = ['red', 'blue', 'green', 'black'] |
| 1109 |
>>> colors[3] = 'white' # Setting item at index |
| 1110 |
>>> colors |
| 1111 |
['red', 'blue', 'green', 'white'] |
| 1112 |
>>> del colors[3] # Deleting item at index 3 |
| 1113 |
>>> colors |
| 1114 |
['red', 'blue', 'green'] |
| 1115 |
|
| 1116 |
All advanced forms of *subscript* documented in the following sections |
| 1117 |
are also usable for assignment and deletion. |
| 1118 |
|
| 1119 |
|
| 1120 |
.. index:: |
| 1121 |
single: slicing |
| 1122 |
single: slice |
| 1123 |
single: : (colon); slicing |
| 1124 |
single: , (comma); slicing |
| 1125 |
|
| 1126 |
.. index:: |
| 1127 |
pair: object; sequence |
| 1128 |
pair: object; string |
| 1129 |
pair: object; tuple |
| 1130 |
pair: object; list |
| 1131 |
|
| 1132 |
.. _slicings: |
| 1133 |
|
| 1134 |
Slicings |
| 1135 |
^^^^^^^^ |
| 1136 |
|
| 1137 |
A more advanced form of subscription, :dfn:`slicing`, is commonly used |
| 1138 |
to extract a portion of a :ref:`sequence <datamodel-sequences>`. |
| 1139 |
In this form, the subscript is a :term:`slice`: up to three |
| 1140 |
expressions separated by colons. |
| 1141 |
Any of the expressions may be omitted, but a slice must contain at least one |
| 1142 |
colon:: |
| 1143 |
|
| 1144 |
>>> number_names = ['zero', 'one', 'two', 'three', 'four', 'five'] |
| 1145 |
>>> number_names[1:3] |
| 1146 |
['one', 'two'] |
| 1147 |
>>> number_names[1:] |
| 1148 |
['one', 'two', 'three', 'four', 'five'] |
| 1149 |
>>> number_names[:3] |
| 1150 |
['zero', 'one', 'two'] |
| 1151 |
>>> number_names[:] |
| 1152 |
['zero', 'one', 'two', 'three', 'four', 'five'] |
| 1153 |
>>> number_names[::2] |
| 1154 |
['zero', 'two', 'four'] |
| 1155 |
>>> number_names[:-3] |
| 1156 |
['zero', 'one', 'two'] |
| 1157 |
>>> del number_names[4:] |
| 1158 |
>>> number_names |
| 1159 |
['zero', 'one', 'two', 'three'] |
| 1160 |
|
| 1161 |
When a slice is evaluated, the interpreter constructs a :class:`slice` object |
| 1162 |
whose :attr:`~slice.start`, :attr:`~slice.stop` and |
| 1163 |
:attr:`~slice.step` attributes, respectively, are the results of the |
| 1164 |
expressions between the colons. |
| 1165 |
Any missing expression evaluates to :const:`None`. |
| 1166 |
This :class:`!slice` object is then passed to the :meth:`~object.__getitem__` |
| 1167 |
or :meth:`~object.__class_getitem__` :term:`special method`, as above. :: |
| 1168 |
|
| 1169 |
# continuing with the SubscriptionDemo instance defined above: |
| 1170 |
>>> demo[2:3] |
| 1171 |
subscripted with: slice(2, 3, None) |
| 1172 |
>>> demo[::'spam'] |
| 1173 |
subscripted with: slice(None, None, 'spam') |
| 1174 |
|
| 1175 |
|
| 1176 |
Comma-separated subscripts |
| 1177 |
^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 1178 |
|
| 1179 |
The subscript can also be given as two or more comma-separated expressions |
| 1180 |
or slices:: |
| 1181 |
|
| 1182 |
# continuing with the SubscriptionDemo instance defined above: |
| 1183 |
>>> demo[1, 2, 3] |
| 1184 |
subscripted with: (1, 2, 3) |
| 1185 |
>>> demo[1:2, 3] |
| 1186 |
subscripted with: (slice(1, 2, None), 3) |
| 1187 |
|
| 1188 |
This form is commonly used with numerical libraries for slicing |
| 1189 |
multi-dimensional data. |
| 1190 |
In this case, the interpreter constructs a :class:`tuple` of the results of the |
| 1191 |
expressions or slices, and passes this tuple to the :meth:`~object.__getitem__` |
| 1192 |
or :meth:`~object.__class_getitem__` :term:`special method`, as above. |
| 1193 |
|
| 1194 |
The subscript may also be given as a single expression or slice followed |
| 1195 |
by a comma, to specify a one-element tuple:: |
| 1196 |
|
| 1197 |
>>> demo['spam',] |
| 1198 |
subscripted with: ('spam',) |
| 1199 |
|
| 1200 |
|
| 1201 |
"Starred" subscriptions |
| 1202 |
^^^^^^^^^^^^^^^^^^^^^^^ |
| 1203 |
|
| 1204 |
.. versionadded:: 3.11 |
| 1205 |
Expressions in *tuple_slices* may be starred. See :pep:`646`. |
| 1206 |
|
| 1207 |
The subscript can also contain a starred expression. |
| 1208 |
In this case, the interpreter unpacks the result into a tuple, and passes |
| 1209 |
this tuple to :meth:`~object.__getitem__` or :meth:`~object.__class_getitem__`:: |
| 1210 |
|
| 1211 |
# continuing with the SubscriptionDemo instance defined above: |
| 1212 |
>>> demo[*range(10)] |
| 1213 |
subscripted with: (0, 1, 2, 3, 4, 5, 6, 7, 8, 9) |
| 1214 |
|
| 1215 |
Starred expressions may be combined with comma-separated expressions |
| 1216 |
and slices:: |
| 1217 |
|
| 1218 |
>>> demo['a', 'b', *range(3), 'c'] |
| 1219 |
subscripted with: ('a', 'b', 0, 1, 2, 'c') |
| 1220 |
|
| 1221 |
|
| 1222 |
Formal subscription grammar |
| 1223 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 1224 |
|
| 1225 |
.. grammar-snippet:: |
| 1226 |
:group: python-grammar |
| 1227 |
|
| 1228 |
subscription: `primary` '[' `subscript` ']' |
| 1229 |
subscript: `single_subscript` | `tuple_subscript` |
| 1230 |
single_subscript: `proper_slice` | `assignment_expression` |
| 1231 |
proper_slice: [`expression`] ":" [`expression`] [ ":" [`expression`] ] |
| 1232 |
tuple_subscript: ','.(`single_subscript` | `starred_expression`)+ [','] |
| 1233 |
|
| 1234 |
Recall that the ``|`` operator :ref:`denotes ordered choice <notation>`. |
| 1235 |
Specifically, in :token:`!subscript`, if both alternatives would match, the |
| 1236 |
first (:token:`!single_subscript`) has priority. |
| 1237 |
|
| 1238 |
.. index:: |
| 1239 |
pair: object; callable |
| 1240 |
single: call |
| 1241 |
single: argument; call semantics |
| 1242 |
single: () (parentheses); call |
| 1243 |
single: , (comma); argument list |
| 1244 |
single: = (equals); in function calls |
| 1245 |
|
| 1246 |
.. _calls: |
| 1247 |
|
| 1248 |
Calls |
| 1249 |
----- |
| 1250 |
|
| 1251 |
A call calls a callable object (e.g., a :term:`function`) with a possibly empty |
| 1252 |
series of :term:`arguments <argument>`: |
| 1253 |
|
| 1254 |
.. productionlist:: python-grammar |
| 1255 |
call: `primary` "(" [`argument_list` [","] | `comprehension`] ")" |
| 1256 |
argument_list: `positional_arguments` ["," `starred_and_keywords`] |
| 1257 |
: ["," `keywords_arguments`] |
| 1258 |
: | `starred_and_keywords` ["," `keywords_arguments`] |
| 1259 |
: | `keywords_arguments` |
| 1260 |
positional_arguments: `positional_item` ("," `positional_item`)* |
| 1261 |
positional_item: `assignment_expression` | "*" `expression` |
| 1262 |
starred_and_keywords: ("*" `expression` | `keyword_item`) |
| 1263 |
: ("," "*" `expression` | "," `keyword_item`)* |
| 1264 |
keywords_arguments: (`keyword_item` | "**" `expression`) |
| 1265 |
: ("," `keyword_item` | "," "**" `expression`)* |
| 1266 |
keyword_item: `identifier` "=" `expression` |
| 1267 |
|
| 1268 |
An optional trailing comma may be present after the positional and keyword arguments |
| 1269 |
but does not affect the semantics. |
| 1270 |
|
| 1271 |
.. index:: |
| 1272 |
single: parameter; call semantics |
| 1273 |
|
| 1274 |
The primary must evaluate to a callable object (user-defined functions, built-in |
| 1275 |
functions, methods of built-in objects, class objects, methods of class |
| 1276 |
instances, and all objects having a :meth:`~object.__call__` method are callable). All |
| 1277 |
argument expressions are evaluated before the call is attempted. Please refer |
| 1278 |
to section :ref:`function` for the syntax of formal :term:`parameter` lists. |
| 1279 |
|
| 1280 |
.. XXX update with kwonly args PEP |
| 1281 |
|
| 1282 |
If keyword arguments are present, they are first converted to positional |
| 1283 |
arguments, as follows. First, a list of unfilled slots is created for the |
| 1284 |
formal parameters. If there are N positional arguments, they are placed in the |
| 1285 |
first N slots. Next, for each keyword argument, the identifier is used to |
| 1286 |
determine the corresponding slot (if the identifier is the same as the first |
| 1287 |
formal parameter name, the first slot is used, and so on). If the slot is |
| 1288 |
already filled, a :exc:`TypeError` exception is raised. Otherwise, the |
| 1289 |
argument is placed in the slot, filling it (even if the expression is |
| 1290 |
``None``, it fills the slot). When all arguments have been processed, the slots |
| 1291 |
that are still unfilled are filled with the corresponding default value from the |
| 1292 |
function definition. (Default values are calculated, once, when the function is |
| 1293 |
defined; thus, a mutable object such as a list or dictionary used as default |
| 1294 |
value will be shared by all calls that don't specify an argument value for the |
| 1295 |
corresponding slot; this should usually be avoided.) If there are any unfilled |
| 1296 |
slots for which no default value is specified, a :exc:`TypeError` exception is |
| 1297 |
raised. Otherwise, the list of filled slots is used as the argument list for |
| 1298 |
the call. |
| 1299 |
|
| 1300 |
.. impl-detail:: |
| 1301 |
|
| 1302 |
An implementation may provide built-in functions whose positional parameters |
| 1303 |
do not have names, even if they are 'named' for the purpose of documentation, |
| 1304 |
and which therefore cannot be supplied by keyword. In CPython, this is the |
| 1305 |
case for functions implemented in C that use :c:func:`PyArg_ParseTuple` to |
| 1306 |
parse their arguments. |
| 1307 |
|
| 1308 |
If there are more positional arguments than there are formal parameter slots, a |
| 1309 |
:exc:`TypeError` exception is raised, unless a formal parameter using the syntax |
| 1310 |
``*identifier`` is present; in this case, that formal parameter receives a tuple |
| 1311 |
containing the excess positional arguments (or an empty tuple if there were no |
| 1312 |
excess positional arguments). |
| 1313 |
|
| 1314 |
If any keyword argument does not correspond to a formal parameter name, a |
| 1315 |
:exc:`TypeError` exception is raised, unless a formal parameter using the syntax |
| 1316 |
``**identifier`` is present; in this case, that formal parameter receives a |
| 1317 |
dictionary containing the excess keyword arguments (using the keywords as keys |
| 1318 |
and the argument values as corresponding values), or a (new) empty dictionary if |
| 1319 |
there were no excess keyword arguments. |
| 1320 |
|
| 1321 |
.. index:: |
| 1322 |
single: * (asterisk); in function calls |
| 1323 |
single: unpacking; in function calls |
| 1324 |
|
| 1325 |
If the syntax ``*expression`` appears in the function call, ``expression`` must |
| 1326 |
evaluate to an :term:`iterable`. Elements from these iterables are |
| 1327 |
treated as if they were additional positional arguments. For the call |
| 1328 |
``f(x1, x2, *y, x3, x4)``, if *y* evaluates to a sequence *y1*, ..., *yM*, |
| 1329 |
this is equivalent to a call with M+4 positional arguments *x1*, *x2*, |
| 1330 |
*y1*, ..., *yM*, *x3*, *x4*. |
| 1331 |
|
| 1332 |
A consequence of this is that although the ``*expression`` syntax may appear |
| 1333 |
*after* explicit keyword arguments, it is processed *before* the |
| 1334 |
keyword arguments (and any ``**expression`` arguments -- see below). So:: |
| 1335 |
|
| 1336 |
>>> def f(a, b): |
| 1337 |
... print(a, b) |
| 1338 |
... |
| 1339 |
>>> f(b=1, *(2,)) |
| 1340 |
2 1 |
| 1341 |
>>> f(a=1, *(2,)) |
| 1342 |
Traceback (most recent call last): |
| 1343 |
File "<stdin>", line 1, in <module> |
| 1344 |
TypeError: f() got multiple values for keyword argument 'a' |
| 1345 |
>>> f(1, *(2,)) |
| 1346 |
1 2 |
| 1347 |
|
| 1348 |
It is unusual for both keyword arguments and the ``*expression`` syntax to be |
| 1349 |
used in the same call, so in practice this confusion does not often arise. |
| 1350 |
|
| 1351 |
.. index:: |
| 1352 |
single: **; in function calls |
| 1353 |
|
| 1354 |
If the syntax ``**expression`` appears in the function call, ``expression`` must |
| 1355 |
evaluate to a :term:`mapping`, the contents of which are treated as |
| 1356 |
additional keyword arguments. If a parameter matching a key has already been |
| 1357 |
given a value (by an explicit keyword argument, or from another unpacking), |
| 1358 |
a :exc:`TypeError` exception is raised. |
| 1359 |
|
| 1360 |
When ``**expression`` is used, each key in this mapping must be |
| 1361 |
a string. |
| 1362 |
Each value from the mapping is assigned to the first formal parameter |
| 1363 |
eligible for keyword assignment whose name is equal to the key. |
| 1364 |
A key need not be a Python identifier (e.g. ``"max-temp °F"`` is acceptable, |
| 1365 |
although it will not match any formal parameter that could be declared). |
| 1366 |
If there is no match to a formal parameter |
| 1367 |
the key-value pair is collected by the ``**`` parameter, if there is one, |
| 1368 |
or if there is not, a :exc:`TypeError` exception is raised. |
| 1369 |
|
| 1370 |
Formal parameters using the syntax ``*identifier`` or ``**identifier`` cannot be |
| 1371 |
used as positional argument slots or as keyword argument names. |
| 1372 |
|
| 1373 |
.. versionchanged:: 3.5 |
| 1374 |
Function calls accept any number of ``*`` and ``**`` unpackings, |
| 1375 |
positional arguments may follow iterable unpackings (``*``), |
| 1376 |
and keyword arguments may follow dictionary unpackings (``**``). |
| 1377 |
Originally proposed by :pep:`448`. |
| 1378 |
|
| 1379 |
A call always returns some value, possibly ``None``, unless it raises an |
| 1380 |
exception. How this value is computed depends on the type of the callable |
| 1381 |
object. |
| 1382 |
|
| 1383 |
If it is--- |
| 1384 |
|
| 1385 |
a user-defined function: |
| 1386 |
.. index:: |
| 1387 |
pair: function; call |
| 1388 |
triple: user-defined; function; call |
| 1389 |
pair: object; user-defined function |
| 1390 |
pair: object; function |
| 1391 |
|
| 1392 |
The code block for the function is executed, passing it the argument list. The |
| 1393 |
first thing the code block will do is bind the formal parameters to the |
| 1394 |
arguments; this is described in section :ref:`function`. When the code block |
| 1395 |
executes a :keyword:`return` statement, this specifies the return value of the |
| 1396 |
function call. If execution reaches the end of the code block without |
| 1397 |
executing a :keyword:`return` statement, the return value is ``None``. |
| 1398 |
|
| 1399 |
a built-in function or method: |
| 1400 |
.. index:: |
| 1401 |
pair: function; call |
| 1402 |
pair: built-in function; call |
| 1403 |
pair: method; call |
| 1404 |
pair: built-in method; call |
| 1405 |
pair: object; built-in method |
| 1406 |
pair: object; built-in function |
| 1407 |
pair: object; method |
| 1408 |
pair: object; function |
| 1409 |
|
| 1410 |
The result is up to the interpreter; see :ref:`built-in-funcs` for the |
| 1411 |
descriptions of built-in functions and methods. |
| 1412 |
|
| 1413 |
a class object: |
| 1414 |
.. index:: |
| 1415 |
pair: object; class |
| 1416 |
pair: class object; call |
| 1417 |
|
| 1418 |
A new instance of that class is returned. |
| 1419 |
|
| 1420 |
a class instance method: |
| 1421 |
.. index:: |
| 1422 |
pair: object; class instance |
| 1423 |
pair: object; instance |
| 1424 |
pair: class instance; call |
| 1425 |
|
| 1426 |
The corresponding user-defined function is called, with an argument list that is |
| 1427 |
one longer than the argument list of the call: the instance becomes the first |
| 1428 |
argument. |
| 1429 |
|
| 1430 |
a class instance: |
| 1431 |
.. index:: |
| 1432 |
pair: instance; call |
| 1433 |
single: __call__() (object method) |
| 1434 |
|
| 1435 |
The class must define a :meth:`~object.__call__` method; the effect is then the same as |
| 1436 |
if that method was called. |
| 1437 |
|
| 1438 |
|
| 1439 |
.. index:: pair: keyword; await |
| 1440 |
.. _await: |
| 1441 |
|
| 1442 |
Await expression |
| 1443 |
================ |
| 1444 |
|
| 1445 |
Suspend the execution of :term:`coroutine` on an :term:`awaitable` object. |
| 1446 |
Can only be used inside a :term:`coroutine function`. |
| 1447 |
|
| 1448 |
.. productionlist:: python-grammar |
| 1449 |
await_expr: "await" `primary` |
| 1450 |
|
| 1451 |
.. versionadded:: 3.5 |
| 1452 |
|
| 1453 |
|
| 1454 |
.. _power: |
| 1455 |
|
| 1456 |
The power operator |
| 1457 |
================== |
| 1458 |
|
| 1459 |
.. index:: |
| 1460 |
pair: power; operation |
| 1461 |
pair: operator; ** |
| 1462 |
|
| 1463 |
The power operator binds more tightly than unary operators on its left; it binds |
| 1464 |
less tightly than unary operators on its right. The syntax is: |
| 1465 |
|
| 1466 |
.. productionlist:: python-grammar |
| 1467 |
power: (`await_expr` | `primary`) ["**" `u_expr`] |
| 1468 |
|
| 1469 |
Thus, in an unparenthesized sequence of power and unary operators, the operators |
| 1470 |
are evaluated from right to left (this does not constrain the evaluation order |
| 1471 |
for the operands): ``-1**2`` results in ``-1``. |
| 1472 |
|
| 1473 |
The power operator has the same semantics as the built-in :func:`pow` function, |
| 1474 |
when called with two arguments: it yields its left argument raised to the power |
| 1475 |
of its right argument. |
| 1476 |
Numeric arguments are first :ref:`converted to a common type <stdtypes-mixed-arithmetic>`, |
| 1477 |
and the result is of that type. |
| 1478 |
|
| 1479 |
For int operands, the result has the same type as the operands unless the second |
| 1480 |
argument is negative; in that case, all arguments are converted to float and a |
| 1481 |
float result is delivered. For example, ``10**2`` returns ``100``, but |
| 1482 |
``10**-2`` returns ``0.01``. |
| 1483 |
|
| 1484 |
Raising ``0.0`` to a negative power results in a :exc:`ZeroDivisionError`. |
| 1485 |
Raising a negative number to a fractional power results in a :class:`complex` |
| 1486 |
number. (In earlier versions it raised a :exc:`ValueError`.) |
| 1487 |
|
| 1488 |
This operation can be customized using the special :meth:`~object.__pow__` and |
| 1489 |
:meth:`~object.__rpow__` methods. |
| 1490 |
|
| 1491 |
.. _unary: |
| 1492 |
|
| 1493 |
Unary arithmetic and bitwise operations |
| 1494 |
======================================= |
| 1495 |
|
| 1496 |
.. index:: |
| 1497 |
triple: unary; arithmetic; operation |
| 1498 |
triple: unary; bitwise; operation |
| 1499 |
|
| 1500 |
All unary arithmetic and bitwise operations have the same priority: |
| 1501 |
|
| 1502 |
.. productionlist:: python-grammar |
| 1503 |
u_expr: `power` | "-" `u_expr` | "+" `u_expr` | "~" `u_expr` |
| 1504 |
|
| 1505 |
.. index:: |
| 1506 |
single: negation |
| 1507 |
single: minus |
| 1508 |
single: operator; - (minus) |
| 1509 |
single: - (minus); unary operator |
| 1510 |
|
| 1511 |
The unary ``-`` (minus) operator yields the negation of its numeric argument; the |
| 1512 |
operation can be overridden with the :meth:`~object.__neg__` special method. |
| 1513 |
|
| 1514 |
.. index:: |
| 1515 |
single: plus |
| 1516 |
single: operator; + (plus) |
| 1517 |
single: + (plus); unary operator |
| 1518 |
|
| 1519 |
The unary ``+`` (plus) operator yields its numeric argument unchanged; the |
| 1520 |
operation can be overridden with the :meth:`~object.__pos__` special method. |
| 1521 |
|
| 1522 |
.. index:: |
| 1523 |
single: inversion |
| 1524 |
pair: operator; ~ (tilde) |
| 1525 |
|
| 1526 |
The unary ``~`` (invert) operator yields the bitwise inversion of its integer |
| 1527 |
argument. The bitwise inversion of ``x`` is defined as ``-(x+1)``. It only |
| 1528 |
applies to integral numbers or to custom objects that override the |
| 1529 |
:meth:`~object.__invert__` special method. |
| 1530 |
|
| 1531 |
|
| 1532 |
|
| 1533 |
.. index:: pair: exception; TypeError |
| 1534 |
|
| 1535 |
In all three cases, if the argument does not have the proper type, a |
| 1536 |
:exc:`TypeError` exception is raised. |
| 1537 |
|
| 1538 |
|
| 1539 |
.. _binary: |
| 1540 |
|
| 1541 |
Binary arithmetic operations |
| 1542 |
============================ |
| 1543 |
|
| 1544 |
.. index:: triple: binary; arithmetic; operation |
| 1545 |
|
| 1546 |
The binary arithmetic operations have the conventional priority levels. Note |
| 1547 |
that some of these operations also apply to certain non-numeric types. Apart |
| 1548 |
from the power operator, there are only two levels, one for multiplicative |
| 1549 |
operators and one for additive operators: |
| 1550 |
|
| 1551 |
.. productionlist:: python-grammar |
| 1552 |
m_expr: `u_expr` | `m_expr` "*" `u_expr` | `m_expr` "@" `m_expr` | |
| 1553 |
: `m_expr` "//" `u_expr` | `m_expr` "/" `u_expr` | |
| 1554 |
: `m_expr` "%" `u_expr` |
| 1555 |
a_expr: `m_expr` | `a_expr` "+" `m_expr` | `a_expr` "-" `m_expr` |
| 1556 |
|
| 1557 |
.. index:: |
| 1558 |
single: multiplication |
| 1559 |
pair: operator; * (asterisk) |
| 1560 |
|
| 1561 |
The ``*`` (multiplication) operator yields the product of its arguments. The |
| 1562 |
arguments must either both be numbers, or one argument must be an integer and |
| 1563 |
the other must be a sequence. In the former case, the numbers are |
| 1564 |
:ref:`converted to a common real type <stdtypes-mixed-arithmetic>` and then |
| 1565 |
multiplied together. In the latter case, sequence repetition is performed; |
| 1566 |
a negative repetition factor yields an empty sequence. |
| 1567 |
|
| 1568 |
This operation can be customized using the special :meth:`~object.__mul__` and |
| 1569 |
:meth:`~object.__rmul__` methods. |
| 1570 |
|
| 1571 |
.. versionchanged:: 3.14 |
| 1572 |
If only one operand is a complex number, the other operand is converted |
| 1573 |
to a floating-point number. |
| 1574 |
|
| 1575 |
.. index:: |
| 1576 |
single: matrix multiplication |
| 1577 |
pair: operator; @ (at) |
| 1578 |
|
| 1579 |
The ``@`` (at) operator is intended to be used for matrix multiplication. No |
| 1580 |
builtin Python types implement this operator. |
| 1581 |
|
| 1582 |
This operation can be customized using the special :meth:`~object.__matmul__` and |
| 1583 |
:meth:`~object.__rmatmul__` methods. |
| 1584 |
|
| 1585 |
.. versionadded:: 3.5 |
| 1586 |
|
| 1587 |
.. index:: |
| 1588 |
pair: exception; ZeroDivisionError |
| 1589 |
single: division |
| 1590 |
pair: operator; / (slash) |
| 1591 |
pair: operator; // |
| 1592 |
|
| 1593 |
The ``/`` (division) and ``//`` (floor division) operators yield the quotient of |
| 1594 |
their arguments. The numeric arguments are first |
| 1595 |
:ref:`converted to a common type <stdtypes-mixed-arithmetic>`. |
| 1596 |
Division of integers yields a float, while floor division of integers results in an |
| 1597 |
integer; the result is that of mathematical division with the 'floor' function |
| 1598 |
applied to the result. Division by zero raises the :exc:`ZeroDivisionError` |
| 1599 |
exception. |
| 1600 |
|
| 1601 |
The division operation can be customized using the special :meth:`~object.__truediv__` |
| 1602 |
and :meth:`~object.__rtruediv__` methods. |
| 1603 |
The floor division operation can be customized using the special |
| 1604 |
:meth:`~object.__floordiv__` and :meth:`~object.__rfloordiv__` methods. |
| 1605 |
|
| 1606 |
.. index:: |
| 1607 |
single: modulo |
| 1608 |
pair: operator; % (percent) |
| 1609 |
|
| 1610 |
The ``%`` (modulo) operator yields the remainder from the division of the first |
| 1611 |
argument by the second. The numeric arguments are first |
| 1612 |
:ref:`converted to a common type <stdtypes-mixed-arithmetic>`. |
| 1613 |
A zero right argument raises the :exc:`ZeroDivisionError` exception. The |
| 1614 |
arguments may be floating-point numbers, e.g., ``3.14%0.7`` equals ``0.34`` |
| 1615 |
(since ``3.14`` equals ``4*0.7 + 0.34``.) The modulo operator always yields a |
| 1616 |
result with the same sign as its second operand (or zero); the absolute value of |
| 1617 |
the result is strictly smaller than the absolute value of the second operand |
| 1618 |
[#]_. |
| 1619 |
|
| 1620 |
The floor division and modulo operators are connected by the following |
| 1621 |
identity: ``x == (x//y)*y + (x%y)``. Floor division and modulo are also |
| 1622 |
connected with the built-in function :func:`divmod`: ``divmod(x, y) == (x//y, |
| 1623 |
x%y)``. [#]_. |
| 1624 |
|
| 1625 |
In addition to performing the modulo operation on numbers, the ``%`` operator is |
| 1626 |
also overloaded by string objects to perform old-style string formatting (also |
| 1627 |
known as interpolation). The syntax for string formatting is described in the |
| 1628 |
Python Library Reference, section :ref:`old-string-formatting`. |
| 1629 |
|
| 1630 |
The *modulo* operation can be customized using the special :meth:`~object.__mod__` |
| 1631 |
and :meth:`~object.__rmod__` methods. |
| 1632 |
|
| 1633 |
The floor division operator, the modulo operator, and the :func:`divmod` |
| 1634 |
function are not defined for complex numbers. Instead, convert to a |
| 1635 |
floating-point number using the :func:`abs` function if appropriate. |
| 1636 |
|
| 1637 |
.. index:: |
| 1638 |
single: addition |
| 1639 |
single: operator; + (plus) |
| 1640 |
single: + (plus); binary operator |
| 1641 |
|
| 1642 |
The ``+`` (addition) operator yields the sum of its arguments. The arguments |
| 1643 |
must either both be numbers or both be sequences of the same type. In the |
| 1644 |
former case, the numbers are |
| 1645 |
:ref:`converted to a common real type <stdtypes-mixed-arithmetic>` and then |
| 1646 |
added together. |
| 1647 |
In the latter case, the sequences are concatenated. |
| 1648 |
|
| 1649 |
This operation can be customized using the special :meth:`~object.__add__` and |
| 1650 |
:meth:`~object.__radd__` methods. |
| 1651 |
|
| 1652 |
.. versionchanged:: 3.14 |
| 1653 |
If only one operand is a complex number, the other operand is converted |
| 1654 |
to a floating-point number. |
| 1655 |
|
| 1656 |
.. index:: |
| 1657 |
single: subtraction |
| 1658 |
single: operator; - (minus) |
| 1659 |
single: - (minus); binary operator |
| 1660 |
|
| 1661 |
The ``-`` (subtraction) operator yields the difference of its arguments. |
| 1662 |
The numeric arguments are first |
| 1663 |
:ref:`converted to a common real type <stdtypes-mixed-arithmetic>`. |
| 1664 |
|
| 1665 |
This operation can be customized using the special :meth:`~object.__sub__` and |
| 1666 |
:meth:`~object.__rsub__` methods. |
| 1667 |
|
| 1668 |
.. versionchanged:: 3.14 |
| 1669 |
If only one operand is a complex number, the other operand is converted |
| 1670 |
to a floating-point number. |
| 1671 |
|
| 1672 |
|
| 1673 |
.. _shifting: |
| 1674 |
|
| 1675 |
Shifting operations |
| 1676 |
=================== |
| 1677 |
|
| 1678 |
.. index:: |
| 1679 |
pair: shifting; operation |
| 1680 |
pair: operator; << |
| 1681 |
pair: operator; >> |
| 1682 |
|
| 1683 |
The shifting operations have lower priority than the arithmetic operations: |
| 1684 |
|
| 1685 |
.. productionlist:: python-grammar |
| 1686 |
shift_expr: `a_expr` | `shift_expr` ("<<" | ">>") `a_expr` |
| 1687 |
|
| 1688 |
These operators accept integers as arguments. They shift the first argument to |
| 1689 |
the left or right by the number of bits given by the second argument. |
| 1690 |
|
| 1691 |
The left shift operation can be customized using the special :meth:`~object.__lshift__` |
| 1692 |
and :meth:`~object.__rlshift__` methods. |
| 1693 |
The right shift operation can be customized using the special :meth:`~object.__rshift__` |
| 1694 |
and :meth:`~object.__rrshift__` methods. |
| 1695 |
|
| 1696 |
.. index:: pair: exception; ValueError |
| 1697 |
|
| 1698 |
A right shift by *n* bits is defined as floor division by ``pow(2,n)``. A left |
| 1699 |
shift by *n* bits is defined as multiplication with ``pow(2,n)``. |
| 1700 |
|
| 1701 |
|
| 1702 |
.. _bitwise: |
| 1703 |
|
| 1704 |
Binary bitwise operations |
| 1705 |
========================= |
| 1706 |
|
| 1707 |
.. index:: triple: binary; bitwise; operation |
| 1708 |
|
| 1709 |
Each of the three bitwise operations has a different priority level: |
| 1710 |
|
| 1711 |
.. productionlist:: python-grammar |
| 1712 |
and_expr: `shift_expr` | `and_expr` "&" `shift_expr` |
| 1713 |
xor_expr: `and_expr` | `xor_expr` "^" `and_expr` |
| 1714 |
or_expr: `xor_expr` | `or_expr` "|" `xor_expr` |
| 1715 |
|
| 1716 |
.. index:: |
| 1717 |
pair: bitwise; and |
| 1718 |
pair: operator; & (ampersand) |
| 1719 |
|
| 1720 |
The ``&`` operator yields the bitwise AND of its arguments, which must be |
| 1721 |
integers or one of them must be a custom object overriding :meth:`~object.__and__` or |
| 1722 |
:meth:`~object.__rand__` special methods. |
| 1723 |
|
| 1724 |
.. index:: |
| 1725 |
pair: bitwise; xor |
| 1726 |
pair: exclusive; or |
| 1727 |
pair: operator; ^ (caret) |
| 1728 |
|
| 1729 |
The ``^`` operator yields the bitwise XOR (exclusive OR) of its arguments, which |
| 1730 |
must be integers or one of them must be a custom object overriding :meth:`~object.__xor__` or |
| 1731 |
:meth:`~object.__rxor__` special methods. |
| 1732 |
|
| 1733 |
.. index:: |
| 1734 |
pair: bitwise; or |
| 1735 |
pair: inclusive; or |
| 1736 |
pair: operator; | (vertical bar) |
| 1737 |
|
| 1738 |
The ``|`` operator yields the bitwise (inclusive) OR of its arguments, which |
| 1739 |
must be integers or one of them must be a custom object overriding :meth:`~object.__or__` or |
| 1740 |
:meth:`~object.__ror__` special methods. |
| 1741 |
|
| 1742 |
|
| 1743 |
.. _comparisons: |
| 1744 |
|
| 1745 |
Comparisons |
| 1746 |
=========== |
| 1747 |
|
| 1748 |
.. index:: |
| 1749 |
single: comparison |
| 1750 |
pair: C; language |
| 1751 |
pair: operator; < (less) |
| 1752 |
pair: operator; > (greater) |
| 1753 |
pair: operator; <= |
| 1754 |
pair: operator; >= |
| 1755 |
pair: operator; == |
| 1756 |
pair: operator; != |
| 1757 |
|
| 1758 |
Unlike C, all comparison operations in Python have the same priority, which is |
| 1759 |
lower than that of any arithmetic, shifting or bitwise operation. Also unlike |
| 1760 |
C, expressions like ``a < b < c`` have the interpretation that is conventional |
| 1761 |
in mathematics: |
| 1762 |
|
| 1763 |
.. productionlist:: python-grammar |
| 1764 |
comparison: `or_expr` (`comp_operator` `or_expr`)* |
| 1765 |
comp_operator: "<" | ">" | "==" | ">=" | "<=" | "!=" |
| 1766 |
: | "is" ["not"] | ["not"] "in" |
| 1767 |
|
| 1768 |
Comparisons yield boolean values: ``True`` or ``False``. Custom |
| 1769 |
:dfn:`rich comparison methods` may return non-boolean values. In this case |
| 1770 |
Python will call :func:`bool` on such value in boolean contexts. |
| 1771 |
|
| 1772 |
.. index:: pair: chaining; comparisons |
| 1773 |
|
| 1774 |
Comparisons can be chained arbitrarily, e.g., ``x < y <= z`` is equivalent to |
| 1775 |
``x < y and y <= z``, except that ``y`` is evaluated only once (but in both |
| 1776 |
cases ``z`` is not evaluated at all when ``x < y`` is found to be false). |
| 1777 |
|
| 1778 |
Formally, if *a*, *b*, *c*, ..., *y*, *z* are expressions and *op1*, *op2*, ..., |
| 1779 |
*opN* are comparison operators, then ``a op1 b op2 c ... y opN z`` is equivalent |
| 1780 |
to ``a op1 b and b op2 c and ... y opN z``, except that each expression is |
| 1781 |
evaluated at most once. |
| 1782 |
|
| 1783 |
Note that ``a op1 b op2 c`` doesn't imply any kind of comparison between *a* and |
| 1784 |
*c*, so that, e.g., ``x < y > z`` is perfectly legal (though perhaps not |
| 1785 |
pretty). |
| 1786 |
|
| 1787 |
.. _expressions-value-comparisons: |
| 1788 |
|
| 1789 |
Value comparisons |
| 1790 |
----------------- |
| 1791 |
|
| 1792 |
The operators ``<``, ``>``, ``==``, ``>=``, ``<=``, and ``!=`` compare the |
| 1793 |
values of two objects. The objects do not need to have the same type. |
| 1794 |
|
| 1795 |
Chapter :ref:`objects` states that objects have a value (in addition to type |
| 1796 |
and identity). The value of an object is a rather abstract notion in Python: |
| 1797 |
For example, there is no canonical access method for an object's value. Also, |
| 1798 |
there is no requirement that the value of an object should be constructed in a |
| 1799 |
particular way, e.g. comprised of all its data attributes. Comparison operators |
| 1800 |
implement a particular notion of what the value of an object is. One can think |
| 1801 |
of them as defining the value of an object indirectly, by means of their |
| 1802 |
comparison implementation. |
| 1803 |
|
| 1804 |
Because all types are (direct or indirect) subtypes of :class:`object`, they |
| 1805 |
inherit the default comparison behavior from :class:`object`. Types can |
| 1806 |
customize their comparison behavior by implementing |
| 1807 |
:dfn:`rich comparison methods` like :meth:`~object.__lt__`, described in |
| 1808 |
:ref:`customization`. |
| 1809 |
|
| 1810 |
The default behavior for equality comparison (``==`` and ``!=``) is based on |
| 1811 |
the identity of the objects. Hence, equality comparison of instances with the |
| 1812 |
same identity results in equality, and equality comparison of instances with |
| 1813 |
different identities results in inequality. A motivation for this default |
| 1814 |
behavior is the desire that all objects should be reflexive (i.e. ``x is y`` |
| 1815 |
implies ``x == y``). |
| 1816 |
|
| 1817 |
A default order comparison (``<``, ``>``, ``<=``, and ``>=``) is not provided; |
| 1818 |
an attempt raises :exc:`TypeError`. A motivation for this default behavior is |
| 1819 |
the lack of a similar invariant as for equality. |
| 1820 |
|
| 1821 |
The behavior of the default equality comparison, that instances with different |
| 1822 |
identities are always unequal, may be in contrast to what types will need that |
| 1823 |
have a sensible definition of object value and value-based equality. Such |
| 1824 |
types will need to customize their comparison behavior, and in fact, a number |
| 1825 |
of built-in types have done that. |
| 1826 |
|
| 1827 |
The following list describes the comparison behavior of the most important |
| 1828 |
built-in types. |
| 1829 |
|
| 1830 |
* Numbers of built-in numeric types (:ref:`typesnumeric`) and of the standard |
| 1831 |
library types :class:`fractions.Fraction` and :class:`decimal.Decimal` can be |
| 1832 |
compared within and across their types, with the restriction that complex |
| 1833 |
numbers do not support order comparison. Within the limits of the types |
| 1834 |
involved, they compare mathematically (algorithmically) correct without loss |
| 1835 |
of precision. |
| 1836 |
|
| 1837 |
The not-a-number values ``float('NaN')`` and ``decimal.Decimal('NaN')`` are |
| 1838 |
special. Any ordered comparison of a number to a not-a-number value is false. |
| 1839 |
A counter-intuitive implication is that not-a-number values are not equal to |
| 1840 |
themselves. For example, if ``x = float('NaN')``, ``3 < x``, ``x < 3`` and |
| 1841 |
``x == x`` are all false, while ``x != x`` is true. This behavior is |
| 1842 |
compliant with IEEE 754. |
| 1843 |
|
| 1844 |
* ``None`` and :data:`NotImplemented` are singletons. :PEP:`8` advises that |
| 1845 |
comparisons for singletons should always be done with ``is`` or ``is not``, |
| 1846 |
never the equality operators. |
| 1847 |
|
| 1848 |
* Binary sequences (instances of :class:`bytes` or :class:`bytearray`) can be |
| 1849 |
compared within and across their types. They compare lexicographically using |
| 1850 |
the numeric values of their elements. |
| 1851 |
|
| 1852 |
* Strings (instances of :class:`str`) compare lexicographically using the |
| 1853 |
numerical Unicode code points (the result of the built-in function |
| 1854 |
:func:`ord`) of their characters. [#]_ |
| 1855 |
|
| 1856 |
Strings and binary sequences cannot be directly compared. |
| 1857 |
|
| 1858 |
* Sequences (instances of :class:`tuple`, :class:`list`, or :class:`range`) can |
| 1859 |
be compared only within each of their types, with the restriction that ranges |
| 1860 |
do not support order comparison. Equality comparison across these types |
| 1861 |
results in inequality, and ordering comparison across these types raises |
| 1862 |
:exc:`TypeError`. |
| 1863 |
|
| 1864 |
Sequences compare lexicographically using comparison of corresponding |
| 1865 |
elements. The built-in containers typically assume identical objects are |
| 1866 |
equal to themselves. That lets them bypass equality tests for identical |
| 1867 |
objects to improve performance and to maintain their internal invariants. |
| 1868 |
|
| 1869 |
Lexicographical comparison between built-in collections works as follows: |
| 1870 |
|
| 1871 |
- For two collections to compare equal, they must be of the same type, have |
| 1872 |
the same length, and each pair of corresponding elements must compare |
| 1873 |
equal (for example, ``[1,2] == (1,2)`` is false because the type is not the |
| 1874 |
same). |
| 1875 |
|
| 1876 |
- Collections that support order comparison are ordered the same as their |
| 1877 |
first unequal elements (for example, ``[1,2,x] <= [1,2,y]`` has the same |
| 1878 |
value as ``x <= y``). If a corresponding element does not exist, the |
| 1879 |
shorter collection is ordered first (for example, ``[1,2] < [1,2,3]`` is |
| 1880 |
true). |
| 1881 |
|
| 1882 |
* Mappings (instances of :class:`dict`) compare equal if and only if they have |
| 1883 |
equal ``(key, value)`` pairs. Equality comparison of the keys and values |
| 1884 |
enforces reflexivity. |
| 1885 |
|
| 1886 |
Order comparisons (``<``, ``>``, ``<=``, and ``>=``) raise :exc:`TypeError`. |
| 1887 |
|
| 1888 |
* Sets (instances of :class:`set` or :class:`frozenset`) can be compared within |
| 1889 |
and across their types. |
| 1890 |
|
| 1891 |
They define order |
| 1892 |
comparison operators to mean subset and superset tests. Those relations do |
| 1893 |
not define total orderings (for example, the two sets ``{1,2}`` and ``{2,3}`` |
| 1894 |
are not equal, nor subsets of one another, nor supersets of one |
| 1895 |
another). Accordingly, sets are not appropriate arguments for functions |
| 1896 |
which depend on total ordering (for example, :func:`min`, :func:`max`, and |
| 1897 |
:func:`sorted` produce undefined results given a list of sets as inputs). |
| 1898 |
|
| 1899 |
Comparison of sets enforces reflexivity of its elements. |
| 1900 |
|
| 1901 |
* Most other built-in types have no comparison methods implemented, so they |
| 1902 |
inherit the default comparison behavior. |
| 1903 |
|
| 1904 |
User-defined classes that customize their comparison behavior should follow |
| 1905 |
some consistency rules, if possible: |
| 1906 |
|
| 1907 |
* Equality comparison should be reflexive. |
| 1908 |
In other words, identical objects should compare equal: |
| 1909 |
|
| 1910 |
``x is y`` implies ``x == y`` |
| 1911 |
|
| 1912 |
* Comparison should be symmetric. |
| 1913 |
In other words, the following expressions should have the same result: |
| 1914 |
|
| 1915 |
``x == y`` and ``y == x`` |
| 1916 |
|
| 1917 |
``x != y`` and ``y != x`` |
| 1918 |
|
| 1919 |
``x < y`` and ``y > x`` |
| 1920 |
|
| 1921 |
``x <= y`` and ``y >= x`` |
| 1922 |
|
| 1923 |
* Comparison should be transitive. |
| 1924 |
The following (non-exhaustive) examples illustrate that: |
| 1925 |
|
| 1926 |
``x > y and y > z`` implies ``x > z`` |
| 1927 |
|
| 1928 |
``x < y and y <= z`` implies ``x < z`` |
| 1929 |
|
| 1930 |
* Inverse comparison should result in the boolean negation. |
| 1931 |
In other words, the following expressions should have the same result: |
| 1932 |
|
| 1933 |
``x == y`` and ``not x != y`` |
| 1934 |
|
| 1935 |
``x < y`` and ``not x >= y`` (for total ordering) |
| 1936 |
|
| 1937 |
``x > y`` and ``not x <= y`` (for total ordering) |
| 1938 |
|
| 1939 |
The last two expressions apply to totally ordered collections (e.g. to |
| 1940 |
sequences, but not to sets or mappings). See also the |
| 1941 |
:func:`~functools.total_ordering` decorator. |
| 1942 |
|
| 1943 |
* The :func:`hash` result should be consistent with equality. |
| 1944 |
Objects that are equal should either have the same hash value, |
| 1945 |
or be marked as unhashable. |
| 1946 |
|
| 1947 |
Python does not enforce these consistency rules. In fact, the not-a-number |
| 1948 |
values are an example for not following these rules. |
| 1949 |
|
| 1950 |
|
| 1951 |
.. _in: |
| 1952 |
.. _not in: |
| 1953 |
.. _membership-test-details: |
| 1954 |
|
| 1955 |
Membership test operations |
| 1956 |
-------------------------- |
| 1957 |
|
| 1958 |
The operators :keyword:`in` and :keyword:`not in` test for membership. ``x in |
| 1959 |
s`` evaluates to ``True`` if *x* is a member of *s*, and ``False`` otherwise. |
| 1960 |
``x not in s`` returns the negation of ``x in s``. All built-in sequences and |
| 1961 |
set types support this as well as dictionary, for which :keyword:`!in` tests |
| 1962 |
whether the dictionary has a given key. For container types such as list, tuple, |
| 1963 |
set, frozenset, dict, or collections.deque, the expression ``x in y`` is equivalent |
| 1964 |
to ``any(x is e or x == e for e in y)``. |
| 1965 |
|
| 1966 |
For the string and bytes types, ``x in y`` is ``True`` if and only if *x* is a |
| 1967 |
substring of *y*. An equivalent test is ``y.find(x) != -1``. Empty strings are |
| 1968 |
always considered to be a substring of any other string, so ``"" in "abc"`` will |
| 1969 |
return ``True``. |
| 1970 |
|
| 1971 |
For user-defined classes which define the :meth:`~object.__contains__` method, ``x in |
| 1972 |
y`` returns ``True`` if ``y.__contains__(x)`` returns a true value, and |
| 1973 |
``False`` otherwise. |
| 1974 |
|
| 1975 |
For user-defined classes which do not define :meth:`~object.__contains__` but do define |
| 1976 |
:meth:`~object.__iter__`, ``x in y`` is ``True`` if some value ``z``, for which the |
| 1977 |
expression ``x is z or x == z`` is true, is produced while iterating over ``y``. |
| 1978 |
If an exception is raised during the iteration, it is as if :keyword:`in` raised |
| 1979 |
that exception. |
| 1980 |
|
| 1981 |
Lastly, the old-style iteration protocol is tried: if a class defines |
| 1982 |
:meth:`~object.__getitem__`, ``x in y`` is ``True`` if and only if there is a non-negative |
| 1983 |
integer index *i* such that ``x is y[i] or x == y[i]``, and no lower integer index |
| 1984 |
raises the :exc:`IndexError` exception. (If any other exception is raised, it is as |
| 1985 |
if :keyword:`in` raised that exception). |
| 1986 |
|
| 1987 |
.. index:: |
| 1988 |
pair: operator; in |
| 1989 |
pair: operator; not in |
| 1990 |
pair: membership; test |
| 1991 |
pair: object; sequence |
| 1992 |
|
| 1993 |
The operator :keyword:`not in` is defined to have the inverse truth value of |
| 1994 |
:keyword:`in`. |
| 1995 |
|
| 1996 |
.. index:: |
| 1997 |
pair: operator; is |
| 1998 |
pair: operator; is not |
| 1999 |
pair: identity; test |
| 2000 |
|
| 2001 |
|
| 2002 |
.. _is: |
| 2003 |
.. _is not: |
| 2004 |
|
| 2005 |
Identity comparisons |
| 2006 |
-------------------- |
| 2007 |
|
| 2008 |
The operators :keyword:`is` and :keyword:`is not` test for an object's identity: ``x |
| 2009 |
is y`` is true if and only if *x* and *y* are the same object. An Object's identity |
| 2010 |
is determined using the :meth:`id` function. ``x is not y`` yields the inverse |
| 2011 |
truth value. [#]_ |
| 2012 |
|
| 2013 |
|
| 2014 |
.. _booleans: |
| 2015 |
.. _and: |
| 2016 |
.. _or: |
| 2017 |
.. _not: |
| 2018 |
|
| 2019 |
Boolean operations |
| 2020 |
================== |
| 2021 |
|
| 2022 |
.. index:: |
| 2023 |
pair: Conditional; expression |
| 2024 |
pair: Boolean; operation |
| 2025 |
|
| 2026 |
.. productionlist:: python-grammar |
| 2027 |
or_test: `and_test` | `or_test` "or" `and_test` |
| 2028 |
and_test: `not_test` | `and_test` "and" `not_test` |
| 2029 |
not_test: `comparison` | "not" `not_test` |
| 2030 |
|
| 2031 |
In the context of Boolean operations, and also when expressions are used by |
| 2032 |
control flow statements, the following values are interpreted as false: |
| 2033 |
``False``, ``None``, numeric zero of all types, and empty strings and containers |
| 2034 |
(including strings, tuples, lists, dictionaries, sets and frozensets). All |
| 2035 |
other values are interpreted as true. User-defined objects can customize their |
| 2036 |
truth value by providing a :meth:`~object.__bool__` method. |
| 2037 |
|
| 2038 |
.. index:: pair: operator; not |
| 2039 |
|
| 2040 |
The operator :keyword:`not` yields ``True`` if its argument is false, ``False`` |
| 2041 |
otherwise. |
| 2042 |
|
| 2043 |
.. index:: pair: operator; and |
| 2044 |
|
| 2045 |
The expression ``x and y`` first evaluates *x*; if *x* is false, its value is |
| 2046 |
returned; otherwise, *y* is evaluated and the resulting value is returned. |
| 2047 |
|
| 2048 |
.. index:: pair: operator; or |
| 2049 |
|
| 2050 |
The expression ``x or y`` first evaluates *x*; if *x* is true, its value is |
| 2051 |
returned; otherwise, *y* is evaluated and the resulting value is returned. |
| 2052 |
|
| 2053 |
Note that neither :keyword:`and` nor :keyword:`or` restrict the value and type |
| 2054 |
they return to ``False`` and ``True``, but rather return the last evaluated |
| 2055 |
argument. This is sometimes useful, e.g., if ``s`` is a string that should be |
| 2056 |
replaced by a default value if it is empty, the expression ``s or 'foo'`` yields |
| 2057 |
the desired value. Because :keyword:`not` has to create a new value, it |
| 2058 |
returns a boolean value regardless of the type of its argument |
| 2059 |
(for example, ``not 'foo'`` produces ``False`` rather than ``''``.) |
| 2060 |
|
| 2061 |
|
| 2062 |
.. index:: |
| 2063 |
single: := (colon equals) |
| 2064 |
single: assignment expression |
| 2065 |
single: walrus operator |
| 2066 |
single: named expression |
| 2067 |
pair: assignment; expression |
| 2068 |
|
| 2069 |
.. _assignment-expressions: |
| 2070 |
|
| 2071 |
Assignment expressions |
| 2072 |
====================== |
| 2073 |
|
| 2074 |
.. productionlist:: python-grammar |
| 2075 |
assignment_expression: [`identifier` ":="] `expression` |
| 2076 |
|
| 2077 |
An assignment expression (sometimes also called a "named expression" or |
| 2078 |
"walrus") assigns an :token:`~python-grammar:expression` to an |
| 2079 |
:token:`~python-grammar:identifier`, while also returning the value of the |
| 2080 |
:token:`~python-grammar:expression`. |
| 2081 |
|
| 2082 |
One common use case is when handling matched regular expressions: |
| 2083 |
|
| 2084 |
.. code-block:: python |
| 2085 |
|
| 2086 |
if matching := pattern.search(data): |
| 2087 |
do_something(matching) |
| 2088 |
|
| 2089 |
Or, when processing a file stream in chunks: |
| 2090 |
|
| 2091 |
.. code-block:: python |
| 2092 |
|
| 2093 |
while chunk := file.read(9000): |
| 2094 |
process(chunk) |
| 2095 |
|
| 2096 |
Assignment expressions must be surrounded by parentheses when |
| 2097 |
used as expression statements and when used as sub-expressions in |
| 2098 |
slicing, conditional, lambda, |
| 2099 |
keyword-argument, and comprehension-if expressions and |
| 2100 |
in ``assert``, ``with``, and ``assignment`` statements. |
| 2101 |
In all other places where they can be used, parentheses are not required, |
| 2102 |
including in ``if`` and ``while`` statements. |
| 2103 |
|
| 2104 |
.. versionadded:: 3.8 |
| 2105 |
See :pep:`572` for more details about assignment expressions. |
| 2106 |
|
| 2107 |
|
| 2108 |
.. _if_expr: |
| 2109 |
|
| 2110 |
Conditional expressions |
| 2111 |
======================= |
| 2112 |
|
| 2113 |
.. index:: |
| 2114 |
pair: conditional; expression |
| 2115 |
pair: ternary; operator |
| 2116 |
single: if; conditional expression |
| 2117 |
single: else; conditional expression |
| 2118 |
|
| 2119 |
.. productionlist:: python-grammar |
| 2120 |
conditional_expression: `or_test` ["if" `or_test` "else" `expression`] |
| 2121 |
expression: `conditional_expression` | `lambda_expr` |
| 2122 |
|
| 2123 |
A conditional expression (sometimes called a "ternary operator") is an |
| 2124 |
alternative to the if-else statement. As it is an expression, it returns a value |
| 2125 |
and can appear as a sub-expression. |
| 2126 |
|
| 2127 |
The expression ``x if C else y`` first evaluates the condition, *C* rather than *x*. |
| 2128 |
If *C* is true, *x* is evaluated and its value is returned; otherwise, *y* is |
| 2129 |
evaluated and its value is returned. |
| 2130 |
|
| 2131 |
See :pep:`308` for more details about conditional expressions. |
| 2132 |
|
| 2133 |
|
| 2134 |
.. _lambdas: |
| 2135 |
.. _lambda: |
| 2136 |
|
| 2137 |
Lambdas |
| 2138 |
======= |
| 2139 |
|
| 2140 |
.. index:: |
| 2141 |
pair: lambda; expression |
| 2142 |
pair: lambda; form |
| 2143 |
pair: anonymous; function |
| 2144 |
single: : (colon); lambda expression |
| 2145 |
|
| 2146 |
.. productionlist:: python-grammar |
| 2147 |
lambda_expr: "lambda" [`parameter_list`] ":" `expression` |
| 2148 |
|
| 2149 |
Lambda expressions (sometimes called lambda forms) are used to create anonymous |
| 2150 |
functions. The expression ``lambda parameters: expression`` yields a function |
| 2151 |
object. The unnamed object behaves like a function object defined with: |
| 2152 |
|
| 2153 |
.. code-block:: none |
| 2154 |
|
| 2155 |
def <lambda>(parameters): |
| 2156 |
return expression |
| 2157 |
|
| 2158 |
See section :ref:`function` for the syntax of parameter lists. Note that |
| 2159 |
functions created with lambda expressions cannot contain statements or |
| 2160 |
annotations. |
| 2161 |
|
| 2162 |
|
| 2163 |
.. _exprlists: |
| 2164 |
|
| 2165 |
Expression lists |
| 2166 |
================ |
| 2167 |
|
| 2168 |
.. index:: |
| 2169 |
pair: expression; list |
| 2170 |
single: , (comma); expression list |
| 2171 |
|
| 2172 |
.. productionlist:: python-grammar |
| 2173 |
starred_expression: "*" `or_expr` | `expression` |
| 2174 |
flexible_expression: `assignment_expression` | `starred_expression` |
| 2175 |
flexible_expression_list: `flexible_expression` ("," `flexible_expression`)* [","] |
| 2176 |
starred_expression_list: `starred_expression` ("," `starred_expression`)* [","] |
| 2177 |
expression_list: `expression` ("," `expression`)* [","] |
| 2178 |
yield_list: `expression_list` | `starred_expression` "," [`starred_expression_list`] |
| 2179 |
|
| 2180 |
.. index:: pair: object; tuple |
| 2181 |
|
| 2182 |
Except when part of a list or set display, an expression list |
| 2183 |
containing at least one comma yields a tuple. The length of |
| 2184 |
the tuple is the number of expressions in the list. The expressions are |
| 2185 |
evaluated from left to right. |
| 2186 |
|
| 2187 |
.. index:: |
| 2188 |
pair: iterable; unpacking |
| 2189 |
single: * (asterisk); in expression lists |
| 2190 |
|
| 2191 |
An asterisk ``*`` denotes :dfn:`iterable unpacking`. Its operand must be |
| 2192 |
an :term:`iterable`. The iterable is expanded into a sequence of items, |
| 2193 |
which are included in the new tuple, list, or set, at the site of |
| 2194 |
the unpacking. |
| 2195 |
|
| 2196 |
.. versionadded:: 3.5 |
| 2197 |
Iterable unpacking in expression lists, originally proposed by :pep:`448`. |
| 2198 |
|
| 2199 |
.. versionadded:: 3.11 |
| 2200 |
Any item in an expression list may be starred. See :pep:`646`. |
| 2201 |
|
| 2202 |
.. index:: pair: trailing; comma |
| 2203 |
|
| 2204 |
A trailing comma is required only to create a one-item tuple, |
| 2205 |
such as ``1,``; it is optional in all other cases. |
| 2206 |
A single expression without a |
| 2207 |
trailing comma doesn't create a tuple, but rather yields the value of that |
| 2208 |
expression. (To create an empty tuple, use an empty pair of parentheses: |
| 2209 |
``()``.) |
| 2210 |
|
| 2211 |
|
| 2212 |
.. _evalorder: |
| 2213 |
|
| 2214 |
Evaluation order |
| 2215 |
================ |
| 2216 |
|
| 2217 |
.. index:: pair: evaluation; order |
| 2218 |
|
| 2219 |
Python evaluates expressions from left to right. Notice that while evaluating |
| 2220 |
an assignment, the right-hand side is evaluated before the left-hand side. |
| 2221 |
|
| 2222 |
In the following lines, expressions will be evaluated in the arithmetic order of |
| 2223 |
their suffixes:: |
| 2224 |
|
| 2225 |
expr1, expr2, expr3, expr4 |
| 2226 |
(expr1, expr2, expr3, expr4) |
| 2227 |
{expr1: expr2, expr3: expr4} |
| 2228 |
expr1 + expr2 * (expr3 - expr4) |
| 2229 |
expr1(expr2, expr3, *expr4, **expr5) |
| 2230 |
expr3, expr4 = expr1, expr2 |
| 2231 |
|
| 2232 |
|
| 2233 |
.. _operator-summary: |
| 2234 |
|
| 2235 |
Operator precedence |
| 2236 |
=================== |
| 2237 |
|
| 2238 |
.. index:: |
| 2239 |
pair: operator; precedence |
| 2240 |
|
| 2241 |
The following table summarizes the operator precedence in Python, from highest |
| 2242 |
precedence (most binding) to lowest precedence (least binding). Operators in |
| 2243 |
the same box have the same precedence. Unless the syntax is explicitly given, |
| 2244 |
operators are binary. Operators in the same box group left to right (except for |
| 2245 |
exponentiation and conditional expressions, which group from right to left). |
| 2246 |
|
| 2247 |
Note that comparisons, membership tests, and identity tests, all have the same |
| 2248 |
precedence and have a left-to-right chaining feature as described in the |
| 2249 |
:ref:`comparisons` section. |
| 2250 |
|
| 2251 |
|
| 2252 |
+-----------------------------------------------+-------------------------------------+ |
| 2253 |
| Operator | Description | |
| 2254 |
+===============================================+=====================================+ |
| 2255 |
| ``(expressions...)``, | Binding or parenthesized | |
| 2256 |
| | expression, | |
| 2257 |
| ``[expressions...]``, | list display, | |
| 2258 |
| ``{key: value...}``, | dictionary display, | |
| 2259 |
| ``{expressions...}`` | set display | |
| 2260 |
+-----------------------------------------------+-------------------------------------+ |
| 2261 |
| ``x[index]``, ``x[index:index]`` | Subscription (including slicing), | |
| 2262 |
| ``x(arguments...)``, ``x.attribute`` | call, attribute reference | |
| 2263 |
+-----------------------------------------------+-------------------------------------+ |
| 2264 |
| :keyword:`await x <await>` | Await expression | |
| 2265 |
+-----------------------------------------------+-------------------------------------+ |
| 2266 |
| ``**`` | Exponentiation [#]_ | |
| 2267 |
+-----------------------------------------------+-------------------------------------+ |
| 2268 |
| ``+x``, ``-x``, ``~x`` | Positive, negative, bitwise NOT | |
| 2269 |
+-----------------------------------------------+-------------------------------------+ |
| 2270 |
| ``*``, ``@``, ``/``, ``//``, ``%`` | Multiplication, matrix | |
| 2271 |
| | multiplication, division, floor | |
| 2272 |
| | division, remainder [#]_ | |
| 2273 |
+-----------------------------------------------+-------------------------------------+ |
| 2274 |
| ``+``, ``-`` | Addition and subtraction | |
| 2275 |
+-----------------------------------------------+-------------------------------------+ |
| 2276 |
| ``<<``, ``>>`` | Shifts | |
| 2277 |
+-----------------------------------------------+-------------------------------------+ |
| 2278 |
| ``&`` | Bitwise AND | |
| 2279 |
+-----------------------------------------------+-------------------------------------+ |
| 2280 |
| ``^`` | Bitwise XOR | |
| 2281 |
+-----------------------------------------------+-------------------------------------+ |
| 2282 |
| ``|`` | Bitwise OR | |
| 2283 |
+-----------------------------------------------+-------------------------------------+ |
| 2284 |
| :keyword:`in`, :keyword:`not in`, | Comparisons, including membership | |
| 2285 |
| :keyword:`is`, :keyword:`is not`, ``<``, | tests and identity tests | |
| 2286 |
| ``<=``, ``>``, ``>=``, ``!=``, ``==`` | | |
| 2287 |
+-----------------------------------------------+-------------------------------------+ |
| 2288 |
| :keyword:`not x <not>` | Boolean NOT | |
| 2289 |
+-----------------------------------------------+-------------------------------------+ |
| 2290 |
| :keyword:`and` | Boolean AND | |
| 2291 |
+-----------------------------------------------+-------------------------------------+ |
| 2292 |
| :keyword:`or` | Boolean OR | |
| 2293 |
+-----------------------------------------------+-------------------------------------+ |
| 2294 |
| :keyword:`if <if_expr>` -- :keyword:`!else` | Conditional expression | |
| 2295 |
+-----------------------------------------------+-------------------------------------+ |
| 2296 |
| :keyword:`lambda` | Lambda expression | |
| 2297 |
+-----------------------------------------------+-------------------------------------+ |
| 2298 |
| ``:=`` | Assignment expression | |
| 2299 |
+-----------------------------------------------+-------------------------------------+ |
| 2300 |
|
| 2301 |
|
| 2302 |
.. rubric:: Footnotes |
| 2303 |
|
| 2304 |
.. [#] While ``abs(x%y) < abs(y)`` is true mathematically, for floats it may not be |
| 2305 |
true numerically due to roundoff. For example, and assuming a platform on which |
| 2306 |
a Python float is an IEEE 754 double-precision number, in order that ``-1e-100 % |
| 2307 |
1e100`` have the same sign as ``1e100``, the computed result is ``-1e-100 + |
| 2308 |
1e100``, which is numerically exactly equal to ``1e100``. The function |
| 2309 |
:func:`math.fmod` returns a result whose sign matches the sign of the |
| 2310 |
first argument instead, and so returns ``-1e-100`` in this case. Which approach |
| 2311 |
is more appropriate depends on the application. |
| 2312 |
|
| 2313 |
.. [#] If x is very close to an exact integer multiple of y, it's possible for |
| 2314 |
``x//y`` to be one larger than ``(x-x%y)//y`` due to rounding. In such |
| 2315 |
cases, Python returns the latter result, in order to preserve that |
| 2316 |
``divmod(x,y)[0] * y + x % y`` be very close to ``x``. |
| 2317 |
|
| 2318 |
.. [#] The Unicode standard distinguishes between :dfn:`code points` |
| 2319 |
(e.g. U+0041) and :dfn:`abstract characters` (e.g. "LATIN CAPITAL LETTER A"). |
| 2320 |
While most abstract characters in Unicode are only represented using one |
| 2321 |
code point, there is a number of abstract characters that can in addition be |
| 2322 |
represented using a sequence of more than one code point. For example, the |
| 2323 |
abstract character "LATIN CAPITAL LETTER C WITH CEDILLA" can be represented |
| 2324 |
as a single :dfn:`precomposed character` at code position U+00C7, or as a |
| 2325 |
sequence of a :dfn:`base character` at code position U+0043 (LATIN CAPITAL |
| 2326 |
LETTER C), followed by a :dfn:`combining character` at code position U+0327 |
| 2327 |
(COMBINING CEDILLA). |
| 2328 |
|
| 2329 |
The comparison operators on strings compare at the level of Unicode code |
| 2330 |
points. This may be counter-intuitive to humans. For example, |
| 2331 |
``"\u00C7" == "\u0043\u0327"`` is ``False``, even though both strings |
| 2332 |
represent the same abstract character "LATIN CAPITAL LETTER C WITH CEDILLA". |
| 2333 |
|
| 2334 |
To compare strings at the level of abstract characters (that is, in a way |
| 2335 |
intuitive to humans), use :func:`unicodedata.normalize`. |
| 2336 |
|
| 2337 |
.. [#] Due to automatic garbage-collection, free lists, and the dynamic nature of |
| 2338 |
descriptors, you may notice seemingly unusual behaviour in certain uses of |
| 2339 |
the :keyword:`is` operator, like those involving comparisons between instance |
| 2340 |
methods, or constants. Check their documentation for more info. |
| 2341 |
|
| 2342 |
.. [#] The power operator ``**`` binds less tightly than an arithmetic or |
| 2343 |
bitwise unary operator on its right, that is, ``2**-1`` is ``0.5``. |
| 2344 |
|
| 2345 |
.. [#] The ``%`` operator is also used for string formatting; the same |
| 2346 |
precedence applies. |