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