Debian Codegraph @

Doc/reference/expressions.rst

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