Debian Codegraph @

Doc/reference/compound_stmts.rst

raw
1 .. _compound:
2
3 *******************
4 Compound statements
5 *******************
6
7 .. index:: pair: compound; statement
8
9 Compound statements contain (groups of) other statements; they affect or control
10 the execution of those other statements in some way. In general, compound
11 statements span multiple lines, although in simple incarnations a whole compound
12 statement may be contained in one line.
13
14 The :keyword:`if`, :keyword:`while` and :keyword:`for` statements implement
15 traditional control flow constructs. :keyword:`try` specifies exception
16 handlers and/or cleanup code for a group of statements, while the
17 :keyword:`with` statement allows the execution of initialization and
18 finalization code around a block of code. Function and class definitions are
19 also syntactically compound statements.
20
21 .. index::
22 single: clause
23 single: suite
24 single: ; (semicolon)
25
26 A compound statement consists of one or more 'clauses.' A clause consists of a
27 header and a 'suite.' The clause headers of a particular compound statement are
28 all at the same indentation level. Each clause header begins with a uniquely
29 identifying keyword and ends with a colon. A suite is a group of statements
30 controlled by a clause. A suite can be one or more semicolon-separated simple
31 statements on the same line as the header, following the header's colon, or it
32 can be one or more indented statements on subsequent lines. Only the latter
33 form of a suite can contain nested compound statements; the following is illegal,
34 mostly because it wouldn't be clear to which :keyword:`if` clause a following
35 :keyword:`else` clause would belong::
36
37 if test1: if test2: print(x)
38
39 Also note that the semicolon binds tighter than the colon in this context, so
40 that in the following example, either all or none of the :func:`print` calls are
41 executed::
42
43 if x < y < z: print(x); print(y); print(z)
44
45 Summarizing:
46
47
48 .. productionlist:: python-grammar
49 compound_stmt: `if_stmt`
50 : | `while_stmt`
51 : | `for_stmt`
52 : | `try_stmt`
53 : | `with_stmt`
54 : | `match_stmt`
55 : | `funcdef`
56 : | `classdef`
57 : | `async_with_stmt`
58 : | `async_for_stmt`
59 : | `async_funcdef`
60 suite: `stmt_list` NEWLINE | NEWLINE INDENT `statement`+ DEDENT
61 statement: `stmt_list` NEWLINE | `compound_stmt`
62 stmt_list: `simple_stmt` (";" `simple_stmt`)* [";"]
63
64 .. index::
65 single: NEWLINE token
66 single: DEDENT token
67 pair: dangling; else
68
69 Note that statements always end in a ``NEWLINE`` possibly followed by a
70 ``DEDENT``. Also note that optional continuation clauses always begin with a
71 keyword that cannot start a statement, thus there are no ambiguities (the
72 'dangling :keyword:`else`' problem is solved in Python by requiring nested
73 :keyword:`if` statements to be indented).
74
75 The formatting of the grammar rules in the following sections places each clause
76 on a separate line for clarity.
77
78
79 .. _if:
80 .. _elif:
81 .. _else:
82
83 The :keyword:`!if` statement
84 ============================
85
86 .. index::
87 ! pair: statement; if
88 pair: keyword; elif
89 pair: keyword; else
90 single: : (colon); compound statement
91
92 The :keyword:`if` statement is used for conditional execution:
93
94 .. productionlist:: python-grammar
95 if_stmt: "if" `assignment_expression` ":" `suite`
96 : ("elif" `assignment_expression` ":" `suite`)*
97 : ["else" ":" `suite`]
98
99 It selects exactly one of the suites by evaluating the expressions one by one
100 until one is found to be true (see section :ref:`booleans` for the definition of
101 true and false); then that suite is executed (and no other part of the
102 :keyword:`if` statement is executed or evaluated). If all expressions are
103 false, the suite of the :keyword:`else` clause, if present, is executed.
104
105
106 .. _while:
107
108 The :keyword:`!while` statement
109 ===============================
110
111 .. index::
112 ! pair: statement; while
113 pair: keyword; else
114 pair: loop; statement
115 single: : (colon); compound statement
116
117 The :keyword:`while` statement is used for repeated execution as long as an
118 expression is true:
119
120 .. productionlist:: python-grammar
121 while_stmt: "while" `assignment_expression` ":" `suite`
122 : ["else" ":" `suite`]
123
124 This repeatedly tests the expression and, if it is true, executes the first
125 suite; if the expression is false (which may be the first time it is tested) the
126 suite of the :keyword:`!else` clause, if present, is executed and the loop
127 terminates.
128
129 .. index::
130 pair: statement; break
131 pair: statement; continue
132
133 A :keyword:`break` statement executed in the first suite terminates the loop
134 without executing the :keyword:`!else` clause's suite. A :keyword:`continue`
135 statement executed in the first suite skips the rest of the suite and goes back
136 to testing the expression.
137
138
139 .. _for:
140
141 The :keyword:`!for` statement
142 =============================
143
144 .. index::
145 ! pair: statement; for
146 pair: keyword; in
147 pair: keyword; else
148 pair: target; list
149 pair: loop; statement
150 pair: object; sequence
151 single: : (colon); compound statement
152
153 The :keyword:`for` statement is used to iterate over the elements of a sequence
154 (such as a string, tuple or list) or other iterable object:
155
156 .. productionlist:: python-grammar
157 for_stmt: "for" `target_list` "in" `!starred_list` ":" `suite`
158 : ["else" ":" `suite`]
159
160 The ``starred_list`` expression is evaluated once; it should yield an
161 :term:`iterable` object. An :term:`iterator` is created for that iterable.
162 The first item provided
163 by the iterator is then assigned to the target list using the standard
164 rules for assignments (see :ref:`assignment`), and the suite is executed. This
165 repeats for each item provided by the iterator. When the iterator is exhausted,
166 the suite in the :keyword:`!else` clause,
167 if present, is executed, and the loop terminates.
168
169 .. index::
170 pair: statement; break
171 pair: statement; continue
172
173 A :keyword:`break` statement executed in the first suite terminates the loop
174 without executing the :keyword:`!else` clause's suite. A :keyword:`continue`
175 statement executed in the first suite skips the rest of the suite and continues
176 with the next item, or with the :keyword:`!else` clause if there is no next
177 item.
178
179 The for-loop makes assignments to the variables in the target list.
180 This overwrites all previous assignments to those variables including
181 those made in the suite of the for-loop::
182
183 for i in range(10):
184 print(i)
185 i = 5 # this will not affect the for-loop
186 # because i will be overwritten with the next
187 # index in the range
188
189
190 .. index::
191 pair: built-in function; range
192
193 Names in the target list are not deleted when the loop is finished, but if the
194 sequence is empty, they will not have been assigned to at all by the loop. Hint:
195 the built-in type :func:`range` represents immutable arithmetic sequences of integers.
196 For instance, iterating ``range(3)`` successively yields 0, 1, and then 2.
197
198 .. versionchanged:: 3.11
199 Starred elements are now allowed in the expression list.
200
201
202 .. _try:
203
204 The :keyword:`!try` statement
205 =============================
206
207 .. index::
208 ! pair: statement; try
209 pair: keyword; except
210 pair: keyword; finally
211 pair: keyword; else
212 pair: keyword; as
213 single: : (colon); compound statement
214
215 The :keyword:`!try` statement specifies exception handlers and/or cleanup code
216 for a group of statements:
217
218 .. productionlist:: python-grammar
219 try_stmt: `try1_stmt` | `try2_stmt` | `try3_stmt`
220 try1_stmt: "try" ":" `suite`
221 : ("except" [`expression` ["as" `identifier`]] ":" `suite`)+
222 : ["else" ":" `suite`]
223 : ["finally" ":" `suite`]
224 try2_stmt: "try" ":" `suite`
225 : ("except" "*" `expression` ["as" `identifier`] ":" `suite`)+
226 : ["else" ":" `suite`]
227 : ["finally" ":" `suite`]
228 try3_stmt: "try" ":" `suite`
229 : "finally" ":" `suite`
230
231 Additional information on exceptions can be found in section :ref:`exceptions`,
232 and information on using the :keyword:`raise` statement to generate exceptions
233 may be found in section :ref:`raise`.
234
235
236 .. _except:
237
238 :keyword:`!except` clause
239 -------------------------
240
241 The :keyword:`!except` clause(s) specify one or more exception handlers. When no
242 exception occurs in the :keyword:`try` clause, no exception handler is executed.
243 When an exception occurs in the :keyword:`!try` suite, a search for an exception
244 handler is started. This search inspects the :keyword:`!except` clauses in turn
245 until one is found that matches the exception.
246 An expression-less :keyword:`!except` clause, if present, must be last;
247 it matches any exception.
248
249 For an :keyword:`!except` clause with an expression, the
250 expression must evaluate to an exception type or a tuple of exception types.
251 The raised exception matches an :keyword:`!except` clause whose expression evaluates
252 to the class or a :term:`non-virtual base class <abstract base class>` of the exception object,
253 or to a tuple that contains such a class.
254
255 If no :keyword:`!except` clause matches the exception,
256 the search for an exception handler
257 continues in the surrounding code and on the invocation stack. [#]_
258
259 If the evaluation of an expression
260 in the header of an :keyword:`!except` clause raises an exception,
261 the original search for a handler is canceled and a search starts for
262 the new exception in the surrounding code and on the call stack (it is treated
263 as if the entire :keyword:`try` statement raised the exception).
264
265 .. index:: single: as; except clause
266
267 When a matching :keyword:`!except` clause is found,
268 the exception is assigned to the target
269 specified after the :keyword:`!as` keyword in that :keyword:`!except` clause,
270 if present, and the :keyword:`!except` clause's suite is executed.
271 All :keyword:`!except` clauses must have an executable block.
272 When the end of this block is reached, execution continues
273 normally after the entire :keyword:`try` statement.
274 (This means that if two nested handlers exist for the same exception,
275 and the exception occurs in the :keyword:`!try` clause of the inner handler,
276 the outer handler will not handle the exception.)
277
278 When an exception has been assigned using ``as target``, it is cleared at the
279 end of the :keyword:`!except` clause. This is as if::
280
281 except E as N:
282 foo
283
284 was translated to::
285
286 except E as N:
287 try:
288 foo
289 finally:
290 del N
291
292 This means the exception must be assigned to a different name to be able to
293 refer to it after the :keyword:`!except` clause.
294 Exceptions are cleared because with the
295 traceback attached to them, they form a reference cycle with the stack frame,
296 keeping all locals in that frame alive until the next garbage collection occurs.
297
298 .. index::
299 pair: module; sys
300 pair: object; traceback
301
302 Before an :keyword:`!except` clause's suite is executed,
303 the exception is stored in the :mod:`sys` module, where it can be accessed
304 from within the body of the :keyword:`!except` clause by calling
305 :func:`sys.exception`. When leaving an exception handler, the exception
306 stored in the :mod:`sys` module is reset to its previous value::
307
308 >>> print(sys.exception())
309 None
310 >>> try:
311 ... raise TypeError
312 ... except:
313 ... print(repr(sys.exception()))
314 ... try:
315 ... raise ValueError
316 ... except:
317 ... print(repr(sys.exception()))
318 ... print(repr(sys.exception()))
319 ...
320 TypeError()
321 ValueError()
322 TypeError()
323 >>> print(sys.exception())
324 None
325
326
327 .. index::
328 pair: keyword; except_star
329
330 .. _except_star:
331
332 :keyword:`!except*` clause
333 --------------------------
334
335 The :keyword:`!except*` clause(s) specify one or more handlers for groups of
336 exceptions (:exc:`BaseExceptionGroup` instances). A :keyword:`try` statement
337 can have either :keyword:`except` or :keyword:`!except*` clauses, but not both.
338 The exception type for matching is mandatory in the case of :keyword:`!except*`,
339 so ``except*:`` is a syntax error. The type is interpreted as in the case of
340 :keyword:`!except`, but matching is performed on the exceptions contained in the
341 group that is being handled. A :exc:`TypeError` is raised if a matching
342 type is a subclass of :exc:`!BaseExceptionGroup`, because that would have
343 ambiguous semantics.
344
345 When an exception group is raised in the try block, each :keyword:`!except*`
346 clause splits (see :meth:`~BaseExceptionGroup.split`) it into the subgroups
347 of matching and non-matching exceptions. If the matching subgroup is not empty,
348 it becomes the handled exception (the value returned from :func:`sys.exception`)
349 and assigned to the target of the :keyword:`!except*` clause (if there is one).
350 Then, the body of the :keyword:`!except*` clause executes. If the non-matching
351 subgroup is not empty, it is processed by the next :keyword:`!except*` in the
352 same manner. This continues until all exceptions in the group have been matched,
353 or the last :keyword:`!except*` clause has run.
354
355 After all :keyword:`!except*` clauses execute, the group of unhandled exceptions
356 is merged with any exceptions that were raised or re-raised from within
357 :keyword:`!except*` clauses. This merged exception group propagates on::
358
359 >>> try:
360 ... raise ExceptionGroup("eg",
361 ... [ValueError(1), TypeError(2), OSError(3), OSError(4)])
362 ... except* TypeError as e:
363 ... print(f'caught {type(e)} with nested {e.exceptions}')
364 ... except* OSError as e:
365 ... print(f'caught {type(e)} with nested {e.exceptions}')
366 ...
367 caught <class 'ExceptionGroup'> with nested (TypeError(2),)
368 caught <class 'ExceptionGroup'> with nested (OSError(3), OSError(4))
369 + Exception Group Traceback (most recent call last):
370 | File "<doctest default[0]>", line 2, in <module>
371 | raise ExceptionGroup("eg",
372 | [ValueError(1), TypeError(2), OSError(3), OSError(4)])
373 | ExceptionGroup: eg (1 sub-exception)
374 +-+---------------- 1 ----------------
375 | ValueError: 1
376 +------------------------------------
377
378 If the exception raised from the :keyword:`try` block is not an exception group
379 and its type matches one of the :keyword:`!except*` clauses, it is caught and
380 wrapped by an exception group with an empty message string. This ensures that the
381 type of the target ``e`` is consistently :exc:`BaseExceptionGroup`::
382
383 >>> try:
384 ... raise BlockingIOError
385 ... except* BlockingIOError as e:
386 ... print(repr(e))
387 ...
388 ExceptionGroup('', (BlockingIOError(),))
389
390 :keyword:`break`, :keyword:`continue` and :keyword:`return`
391 cannot appear in an :keyword:`!except*` clause.
392
393
394 .. index::
395 pair: keyword; else
396 pair: statement; return
397 pair: statement; break
398 pair: statement; continue
399
400 .. _except_else:
401
402 :keyword:`!else` clause
403 -----------------------
404
405 The optional :keyword:`!else` clause is executed if the control flow leaves the
406 :keyword:`try` suite, no exception was raised, and no :keyword:`return`,
407 :keyword:`continue`, or :keyword:`break` statement was executed. Exceptions in
408 the :keyword:`!else` clause are not handled by the preceding :keyword:`except`
409 clauses.
410
411
412 .. index:: pair: keyword; finally
413
414 .. _finally:
415
416 :keyword:`!finally` clause
417 --------------------------
418
419 If :keyword:`!finally` is present, it specifies a 'cleanup' handler. The
420 :keyword:`try` clause is executed, including any :keyword:`except`
421 and :keyword:`else <except_else>` clauses.
422 If an exception occurs in any of the clauses and is not handled,
423 the exception is temporarily saved.
424 The :keyword:`!finally` clause is executed. If there is a saved exception
425 it is re-raised at the end of the :keyword:`!finally` clause.
426 If the :keyword:`!finally` clause raises another exception, the saved exception
427 is set as the context of the new exception.
428 If the :keyword:`!finally` clause executes a :keyword:`return`, :keyword:`break`
429 or :keyword:`continue` statement, the saved exception is discarded::
430
431 >>> def f():
432 ... try:
433 ... 1/0
434 ... finally:
435 ... return 42
436 ...
437 >>> f()
438 42
439
440 The exception information is not available to the program during execution of
441 the :keyword:`!finally` clause.
442
443 .. index::
444 pair: statement; return
445 pair: statement; break
446 pair: statement; continue
447
448 When a :keyword:`return`, :keyword:`break` or :keyword:`continue` statement is
449 executed in the :keyword:`try` suite of a :keyword:`!try`...\ :keyword:`!finally`
450 statement, the :keyword:`!finally` clause is also executed 'on the way out.'
451
452 The return value of a function is determined by the last :keyword:`return`
453 statement executed. Since the :keyword:`!finally` clause always executes, a
454 :keyword:`!return` statement executed in the :keyword:`!finally` clause will
455 always be the last one executed::
456
457 >>> def foo():
458 ... try:
459 ... return 'try'
460 ... finally:
461 ... return 'finally'
462 ...
463 >>> foo()
464 'finally'
465
466 .. versionchanged:: 3.8
467 Prior to Python 3.8, a :keyword:`continue` statement was illegal in the
468 :keyword:`!finally` clause due to a problem with the implementation.
469
470
471 .. _with:
472 .. _as:
473
474 The :keyword:`!with` statement
475 ==============================
476
477 .. index::
478 ! pair: statement; with
479 pair: keyword; as
480 single: as; with statement
481 single: , (comma); with statement
482 single: : (colon); compound statement
483
484 The :keyword:`with` statement is used to wrap the execution of a block with
485 methods defined by a context manager (see section :ref:`context-managers`).
486 This allows common :keyword:`try`...\ :keyword:`except`...\ :keyword:`finally`
487 usage patterns to be encapsulated for convenient reuse.
488
489 .. productionlist:: python-grammar
490 with_stmt: "with" ( "(" `with_stmt_contents` ","? ")" | `with_stmt_contents` ) ":" `suite`
491 with_stmt_contents: `with_item` ("," `with_item`)*
492 with_item: `expression` ["as" `target`]
493
494 The execution of the :keyword:`with` statement with one "item" proceeds as follows:
495
496 #. The context expression (the expression given in the
497 :token:`~python-grammar:with_item`) is evaluated to obtain a context manager.
498
499 #. The context manager's :meth:`~object.__enter__` is loaded for later use.
500
501 #. The context manager's :meth:`~object.__exit__` is loaded for later use.
502
503 #. The context manager's :meth:`~object.__enter__` method is invoked.
504
505 #. If a target was included in the :keyword:`with` statement, the return value
506 from :meth:`~object.__enter__` is assigned to it.
507
508 .. note::
509
510 The :keyword:`with` statement guarantees that if the :meth:`~object.__enter__`
511 method returns without an error, then :meth:`~object.__exit__` will always be
512 called. Thus, if an error occurs during the assignment to the target list,
513 it will be treated the same as an error occurring within the suite would
514 be. See step 7 below.
515
516 #. The suite is executed.
517
518 #. The context manager's :meth:`~object.__exit__` method is invoked. If an exception
519 caused the suite to be exited, its type, value, and traceback are passed as
520 arguments to :meth:`~object.__exit__`. Otherwise, three :const:`None` arguments are
521 supplied.
522
523 If the suite was exited due to an exception, and the return value from the
524 :meth:`~object.__exit__` method was false, the exception is reraised. If the return
525 value was true, the exception is suppressed, and execution continues with the
526 statement following the :keyword:`with` statement.
527
528 If the suite was exited for any reason other than an exception, the return
529 value from :meth:`~object.__exit__` is ignored, and execution proceeds at the normal
530 location for the kind of exit that was taken.
531
532 The following code::
533
534 with EXPRESSION as TARGET:
535 SUITE
536
537 is semantically equivalent to::
538
539 manager = (EXPRESSION)
540 enter = manager.__enter__
541 exit = manager.__exit__
542 value = enter()
543 hit_except = False
544
545 try:
546 TARGET = value
547 SUITE
548 except:
549 hit_except = True
550 if not exit(*sys.exc_info()):
551 raise
552 finally:
553 if not hit_except:
554 exit(None, None, None)
555
556 except that implicit :ref:`special method lookup <special-lookup>` is used
557 for :meth:`~object.__enter__` and :meth:`~object.__exit__`.
558
559 With more than one item, the context managers are processed as if multiple
560 :keyword:`with` statements were nested::
561
562 with A() as a, B() as b:
563 SUITE
564
565 is semantically equivalent to::
566
567 with A() as a:
568 with B() as b:
569 SUITE
570
571 You can also write multi-item context managers in multiple lines if
572 the items are surrounded by parentheses. For example::
573
574 with (
575 A() as a,
576 B() as b,
577 ):
578 SUITE
579
580 .. versionchanged:: 3.1
581 Support for multiple context expressions.
582
583 .. versionchanged:: 3.10
584 Support for using grouping parentheses to break the statement in multiple lines.
585
586 .. seealso::
587
588 :pep:`343` - The "with" statement
589 The specification, background, and examples for the Python :keyword:`with`
590 statement.
591
592 .. _match:
593 .. _case:
594
595 The :keyword:`!match` statement
596 ===============================
597
598 .. index::
599 ! pair: statement; match
600 ! pair: keyword; case
601 ! single: pattern matching
602 pair: keyword; if
603 pair: keyword; as
604 pair: match; case
605 single: as; match statement
606 single: : (colon); compound statement
607
608 .. versionadded:: 3.10
609
610 The match statement is used for pattern matching. Syntax:
611
612 .. productionlist:: python-grammar
613 match_stmt: 'match' `subject_expr` ":" NEWLINE INDENT `case_block`+ DEDENT
614 subject_expr: `flexible_expression` "," [`flexible_expression_list` [',']]
615 : | `assignment_expression`
616 case_block: 'case' `patterns` [`guard`] ":" `suite`
617
618 .. note::
619 This section uses single quotes to denote
620 :ref:`soft keywords <soft-keywords>`.
621
622 Pattern matching takes a pattern as input (following ``case``) and a subject
623 value (following ``match``). The pattern (which may contain subpatterns) is
624 matched against the subject value. The outcomes are:
625
626 * A match success or failure (also termed a pattern success or failure).
627
628 * Possible binding of matched values to a name. The prerequisites for this are
629 further discussed below.
630
631 The ``match`` and ``case`` keywords are :ref:`soft keywords <soft-keywords>`.
632
633 .. seealso::
634
635 * :pep:`634` -- Structural Pattern Matching: Specification
636 * :pep:`636` -- Structural Pattern Matching: Tutorial
637
638
639 Overview
640 --------
641
642 Here's an overview of the logical flow of a match statement:
643
644
645 #. The subject expression ``subject_expr`` is evaluated and a resulting subject
646 value obtained. If the subject expression contains a comma, a tuple is
647 constructed using :ref:`the standard rules <typesseq-tuple>`.
648
649 #. Each pattern in a ``case_block`` is attempted to match with the subject value. The
650 specific rules for success or failure are described below. The match attempt can also
651 bind some or all of the standalone names within the pattern. The precise
652 pattern binding rules vary per pattern type and are
653 specified below. **Name bindings made during a successful pattern match
654 outlive the executed block and can be used after the match statement**.
655
656 .. note::
657
658 During failed pattern matches, some subpatterns may succeed. Do not
659 rely on bindings being made for a failed match. Conversely, do not
660 rely on variables remaining unchanged after a failed match. The exact
661 behavior is dependent on implementation and may vary. This is an
662 intentional decision made to allow different implementations to add
663 optimizations.
664
665 #. If the pattern succeeds, the corresponding guard (if present) is evaluated. In
666 this case all name bindings are guaranteed to have happened.
667
668 * If the guard evaluates as true or is missing, the ``block`` inside
669 ``case_block`` is executed.
670
671 * Otherwise, the next ``case_block`` is attempted as described above.
672
673 * If there are no further case blocks, the match statement is completed.
674
675 .. note::
676
677 Users should generally never rely on a pattern being evaluated. Depending on
678 implementation, the interpreter may cache values or use other optimizations
679 which skip repeated evaluations.
680
681 A sample match statement::
682
683 >>> flag = False
684 >>> match (100, 200):
685 ... case (100, 300): # Mismatch: 200 != 300
686 ... print('Case 1')
687 ... case (100, 200) if flag: # Successful match, but guard fails
688 ... print('Case 2')
689 ... case (100, y): # Matches and binds y to 200
690 ... print(f'Case 3, y: {y}')
691 ... case _: # Pattern not attempted
692 ... print('Case 4, I match anything!')
693 ...
694 Case 3, y: 200
695
696
697 In this case, ``if flag`` is a guard. Read more about that in the next section.
698
699 Guards
700 ------
701
702 .. index:: ! guard
703
704 .. productionlist:: python-grammar
705 guard: "if" `assignment_expression`
706
707 A ``guard`` (which is part of the ``case``) must succeed for code inside
708 the ``case`` block to execute. It takes the form: :keyword:`if` followed by an
709 expression.
710
711
712 The logical flow of a ``case`` block with a ``guard`` follows:
713
714 #. Check that the pattern in the ``case`` block succeeded. If the pattern
715 failed, the ``guard`` is not evaluated and the next ``case`` block is
716 checked.
717
718 #. If the pattern succeeded, evaluate the ``guard``.
719
720 * If the ``guard`` condition evaluates as true, the case block is
721 selected.
722
723 * If the ``guard`` condition evaluates as false, the case block is not
724 selected.
725
726 * If the ``guard`` raises an exception during evaluation, the exception
727 bubbles up.
728
729 Guards are allowed to have side effects as they are expressions. Guard
730 evaluation must proceed from the first to the last case block, one at a time,
731 skipping case blocks whose pattern(s) don't all succeed. (I.e.,
732 guard evaluation must happen in order.) Guard evaluation must stop once a case
733 block is selected.
734
735
736 .. _irrefutable_case:
737
738 Irrefutable Case Blocks
739 -----------------------
740
741 .. index:: irrefutable case block, case block
742
743 An irrefutable case block is a match-all case block. A match statement may have
744 at most one irrefutable case block, and it must be last.
745
746 A case block is considered irrefutable if it has no guard and its pattern is
747 irrefutable. A pattern is considered irrefutable if we can prove from its
748 syntax alone that it will always succeed. Only the following patterns are
749 irrefutable:
750
751 * :ref:`as-patterns` whose left-hand side is irrefutable
752
753 * :ref:`or-patterns` containing at least one irrefutable pattern
754
755 * :ref:`capture-patterns`
756
757 * :ref:`wildcard-patterns`
758
759 * parenthesized irrefutable patterns
760
761
762 Patterns
763 --------
764
765 .. index::
766 single: ! patterns
767 single: AS pattern, OR pattern, capture pattern, wildcard pattern
768
769 .. note::
770 This section uses grammar notations beyond standard EBNF:
771
772 * the notation ``SEP.RULE+`` is shorthand for ``RULE (SEP RULE)*``
773
774 * the notation ``!RULE`` is shorthand for a negative lookahead assertion
775
776
777 The top-level syntax for ``patterns`` is:
778
779 .. productionlist:: python-grammar
780 patterns: `open_sequence_pattern` | `pattern`
781 pattern: `as_pattern` | `or_pattern`
782 closed_pattern: | `literal_pattern`
783 : | `capture_pattern`
784 : | `wildcard_pattern`
785 : | `value_pattern`
786 : | `group_pattern`
787 : | `sequence_pattern`
788 : | `mapping_pattern`
789 : | `class_pattern`
790
791 The descriptions below will include a description "in simple terms" of what a pattern
792 does for illustration purposes (credits to Raymond Hettinger for a document that
793 inspired most of the descriptions). Note that these descriptions are purely for
794 illustration purposes and **may not** reflect
795 the underlying implementation. Furthermore, they do not cover all valid forms.
796
797
798 .. _or-patterns:
799
800 OR Patterns
801 ^^^^^^^^^^^
802
803 An OR pattern is two or more patterns separated by vertical
804 bars ``|``. Syntax:
805
806 .. productionlist:: python-grammar
807 or_pattern: "|".`closed_pattern`+
808
809 Only the final subpattern may be :ref:`irrefutable <irrefutable_case>`, and each
810 subpattern must bind the same set of names to avoid ambiguity.
811
812 An OR pattern matches each of its subpatterns in turn to the subject value,
813 until one succeeds. The OR pattern is then considered successful. Otherwise,
814 if none of the subpatterns succeed, the OR pattern fails.
815
816 In simple terms, ``P1 | P2 | ...`` will try to match ``P1``, if it fails it will try to
817 match ``P2``, succeeding immediately if any succeeds, failing otherwise.
818
819 .. _as-patterns:
820
821 AS Patterns
822 ^^^^^^^^^^^
823
824 An AS pattern matches an OR pattern on the left of the :keyword:`as`
825 keyword against a subject. Syntax:
826
827 .. productionlist:: python-grammar
828 as_pattern: `or_pattern` "as" `capture_pattern`
829
830 If the OR pattern fails, the AS pattern fails. Otherwise, the AS pattern binds
831 the subject to the name on the right of the as keyword and succeeds.
832 ``capture_pattern`` cannot be a ``_``.
833
834 In simple terms ``P as NAME`` will match with ``P``, and on success it will
835 set ``NAME = <subject>``.
836
837
838 .. _literal-patterns:
839
840 Literal Patterns
841 ^^^^^^^^^^^^^^^^
842
843 A literal pattern corresponds to most
844 :ref:`literals <literals>` in Python. Syntax:
845
846 .. productionlist:: python-grammar
847 literal_pattern: `signed_number`
848 : | `signed_number` "+" NUMBER
849 : | `signed_number` "-" NUMBER
850 : | `!strings`
851 : | "None"
852 : | "True"
853 : | "False"
854 signed_number: ["-"] NUMBER
855
856 The rule ``strings`` and the token ``NUMBER`` are defined in the
857 :doc:`standard Python grammar <./grammar>`. Triple-quoted strings are
858 supported. Raw strings and byte strings are supported. :ref:`f-strings` are
859 not supported.
860
861 The forms ``signed_number '+' NUMBER`` and ``signed_number '-' NUMBER`` are
862 for expressing :ref:`complex numbers <imaginary>`; they require a real number
863 on the left and an imaginary number on the right. E.g. ``3 + 4j``.
864
865 In simple terms, ``LITERAL`` will succeed only if ``<subject> == LITERAL``. For
866 the singletons ``None``, ``True`` and ``False``, the :keyword:`is` operator is used.
867
868 .. _capture-patterns:
869
870 Capture Patterns
871 ^^^^^^^^^^^^^^^^
872
873 A capture pattern binds the subject value to a name.
874 Syntax:
875
876 .. productionlist:: python-grammar
877 capture_pattern: !'_' NAME
878
879 A single underscore ``_`` is not a capture pattern (this is what ``!'_'``
880 expresses). It is instead treated as a
881 :token:`~python-grammar:wildcard_pattern`.
882
883 In a given pattern, a given name can only be bound once. E.g.
884 ``case x, x: ...`` is invalid while ``case [x] | x: ...`` is allowed.
885
886 Capture patterns always succeed. The binding follows scoping rules
887 established by the assignment expression operator in :pep:`572`; the
888 name becomes a local variable in the closest containing function scope unless
889 there's an applicable :keyword:`global` or :keyword:`nonlocal` statement.
890
891 In simple terms ``NAME`` will always succeed and it will set ``NAME = <subject>``.
892
893 .. _wildcard-patterns:
894
895 Wildcard Patterns
896 ^^^^^^^^^^^^^^^^^
897
898 A wildcard pattern always succeeds (matches anything)
899 and binds no name. Syntax:
900
901 .. productionlist:: python-grammar
902 wildcard_pattern: '_'
903
904 ``_`` is a :ref:`soft keyword <soft-keywords>` within any pattern,
905 but only within patterns. It is an identifier, as usual, even within
906 ``match`` subject expressions, ``guard``\ s, and ``case`` blocks.
907
908 In simple terms, ``_`` will always succeed.
909
910 .. _value-patterns:
911
912 Value Patterns
913 ^^^^^^^^^^^^^^
914
915 A value pattern represents a named value in Python.
916 Syntax:
917
918 .. productionlist:: python-grammar
919 value_pattern: `attr`
920 attr: `name_or_attr` "." NAME
921 name_or_attr: `attr` | NAME
922
923 The dotted name in the pattern is looked up using standard Python
924 :ref:`name resolution rules <resolve_names>`. The pattern succeeds if the
925 value found compares equal to the subject value (using the ``==`` equality
926 operator).
927
928 In simple terms ``NAME1.NAME2`` will succeed only if ``<subject> == NAME1.NAME2``
929
930 .. note::
931
932 If the same value occurs multiple times in the same match statement, the
933 interpreter may cache the first value found and reuse it rather than repeat
934 the same lookup. This cache is strictly tied to a given execution of a
935 given match statement.
936
937 .. _group-patterns:
938
939 Group Patterns
940 ^^^^^^^^^^^^^^
941
942 A group pattern allows users to add parentheses around patterns to
943 emphasize the intended grouping. Otherwise, it has no additional syntax.
944 Syntax:
945
946 .. productionlist:: python-grammar
947 group_pattern: "(" `pattern` ")"
948
949 In simple terms ``(P)`` has the same effect as ``P``.
950
951 .. _sequence-patterns:
952
953 Sequence Patterns
954 ^^^^^^^^^^^^^^^^^
955
956 A sequence pattern contains several subpatterns to be matched against sequence elements.
957 The syntax is similar to the unpacking of a list or tuple.
958
959 .. productionlist:: python-grammar
960 sequence_pattern: "[" [`maybe_sequence_pattern`] "]"
961 : | "(" [`open_sequence_pattern`] ")"
962 open_sequence_pattern: `maybe_star_pattern` "," [`maybe_sequence_pattern`]
963 maybe_sequence_pattern: ",".`maybe_star_pattern`+ ","?
964 maybe_star_pattern: `star_pattern` | `pattern`
965 star_pattern: "*" (`capture_pattern` | `wildcard_pattern`)
966
967 There is no difference if parentheses or square brackets
968 are used for sequence patterns (i.e. ``(...)`` vs ``[...]`` ).
969
970 .. note::
971 A single pattern enclosed in parentheses without a trailing comma
972 (e.g. ``(3 | 4)``) is a :ref:`group pattern <group-patterns>`.
973 While a single pattern enclosed in square brackets (e.g. ``[3 | 4]``) is
974 still a sequence pattern.
975
976 At most one star subpattern may be in a sequence pattern. The star subpattern
977 may occur in any position. If no star subpattern is present, the sequence
978 pattern is a fixed-length sequence pattern; otherwise it is a variable-length
979 sequence pattern.
980
981 The following is the logical flow for matching a sequence pattern against a
982 subject value:
983
984 #. If the subject value is not a sequence [#]_, the sequence pattern
985 fails.
986
987 #. If the subject value is an instance of ``str``, ``bytes`` or ``bytearray``
988 the sequence pattern fails.
989
990 #. The subsequent steps depend on whether the sequence pattern is fixed or
991 variable-length.
992
993 If the sequence pattern is fixed-length:
994
995 #. If the length of the subject sequence is not equal to the number of
996 subpatterns, the sequence pattern fails
997
998 #. Subpatterns in the sequence pattern are matched to their corresponding
999 items in the subject sequence from left to right. Matching stops as soon
1000 as a subpattern fails. If all subpatterns succeed in matching their
1001 corresponding item, the sequence pattern succeeds.
1002
1003 Otherwise, if the sequence pattern is variable-length:
1004
1005 #. If the length of the subject sequence is less than the number of non-star
1006 subpatterns, the sequence pattern fails.
1007
1008 #. The leading non-star subpatterns are matched to their corresponding items
1009 as for fixed-length sequences.
1010
1011 #. If the previous step succeeds, the star subpattern matches a list formed
1012 of the remaining subject items, excluding the remaining items
1013 corresponding to non-star subpatterns following the star subpattern.
1014
1015 #. Remaining non-star subpatterns are matched to their corresponding subject
1016 items, as for a fixed-length sequence.
1017
1018 .. note:: The length of the subject sequence is obtained via
1019 :func:`len` (i.e. via the :meth:`~object.__len__` protocol).
1020 This length may be cached by the interpreter in a similar manner as
1021 :ref:`value patterns <value-patterns>`.
1022
1023
1024 In simple terms ``[P1, P2, P3,`` ... ``, P<N>]`` matches only if all the following
1025 happens:
1026
1027 * check ``<subject>`` is a sequence
1028 * ``len(subject) == <N>``
1029 * ``P1`` matches ``<subject>[0]`` (note that this match can also bind names)
1030 * ``P2`` matches ``<subject>[1]`` (note that this match can also bind names)
1031 * ... and so on for the corresponding pattern/element.
1032
1033 .. _mapping-patterns:
1034
1035 Mapping Patterns
1036 ^^^^^^^^^^^^^^^^
1037
1038 A mapping pattern contains one or more key-value patterns. The syntax is
1039 similar to the construction of a dictionary.
1040 Syntax:
1041
1042 .. productionlist:: python-grammar
1043 mapping_pattern: "{" [`items_pattern`] "}"
1044 items_pattern: ",".`key_value_pattern`+ ","?
1045 key_value_pattern: (`literal_pattern` | `value_pattern`) ":" `pattern`
1046 : | `double_star_pattern`
1047 double_star_pattern: "**" `capture_pattern`
1048
1049 At most one double star pattern may be in a mapping pattern. The double star
1050 pattern must be the last subpattern in the mapping pattern.
1051
1052 Duplicate keys in mapping patterns are disallowed. Duplicate literal keys will
1053 raise a :exc:`SyntaxError`. Two keys that otherwise have the same value will
1054 raise a :exc:`ValueError` at runtime.
1055
1056 The following is the logical flow for matching a mapping pattern against a
1057 subject value:
1058
1059 #. If the subject value is not a mapping [#]_,the mapping pattern fails.
1060
1061 #. If every key given in the mapping pattern is present in the subject mapping,
1062 and the pattern for each key matches the corresponding item of the subject
1063 mapping, the mapping pattern succeeds.
1064
1065 #. If duplicate keys are detected in the mapping pattern, the pattern is
1066 considered invalid. A :exc:`SyntaxError` is raised for duplicate literal
1067 values; or a :exc:`ValueError` for named keys of the same value.
1068
1069 .. note:: Key-value pairs are matched using the two-argument form of the mapping
1070 subject's ``get()`` method. Matched key-value pairs must already be present
1071 in the mapping, and not created on-the-fly via :meth:`~object.__missing__`
1072 or :meth:`~object.__getitem__`.
1073
1074 In simple terms ``{KEY1: P1, KEY2: P2, ... }`` matches only if all the following
1075 happens:
1076
1077 * check ``<subject>`` is a mapping
1078 * ``KEY1 in <subject>``
1079 * ``P1`` matches ``<subject>[KEY1]``
1080 * ... and so on for the corresponding KEY/pattern pair.
1081
1082
1083 .. _class-patterns:
1084
1085 Class Patterns
1086 ^^^^^^^^^^^^^^
1087
1088 A class pattern represents a class and its positional and keyword arguments
1089 (if any). Syntax:
1090
1091 .. productionlist:: python-grammar
1092 class_pattern: `name_or_attr` "(" [`pattern_arguments` ","?] ")"
1093 pattern_arguments: `positional_patterns` ["," `keyword_patterns`]
1094 : | `keyword_patterns`
1095 positional_patterns: ",".`pattern`+
1096 keyword_patterns: ",".`keyword_pattern`+
1097 keyword_pattern: NAME "=" `pattern`
1098
1099 The same keyword should not be repeated in class patterns.
1100
1101 The following is the logical flow for matching a class pattern against a
1102 subject value:
1103
1104 #. If ``name_or_attr`` is not an instance of the builtin :class:`type` , raise
1105 :exc:`TypeError`.
1106
1107 #. If the subject value is not an instance of ``name_or_attr`` (tested via
1108 :func:`isinstance`), the class pattern fails.
1109
1110 #. If no pattern arguments are present, the pattern succeeds. Otherwise,
1111 the subsequent steps depend on whether keyword or positional argument patterns
1112 are present.
1113
1114 For a number of built-in types (specified below), a single positional
1115 subpattern is accepted which will match the entire subject; for these types
1116 keyword patterns also work as for other types.
1117
1118 If only keyword patterns are present, they are processed as follows,
1119 one by one:
1120
1121 I. The keyword is looked up as an attribute on the subject.
1122
1123 * If this raises an exception other than :exc:`AttributeError`, the
1124 exception bubbles up.
1125
1126 * If this raises :exc:`AttributeError`, the class pattern has failed.
1127
1128 * Else, the subpattern associated with the keyword pattern is matched
1129 against the subject's attribute value. If this fails, the class
1130 pattern fails; if this succeeds, the match proceeds to the next keyword.
1131
1132
1133 II. If all keyword patterns succeed, the class pattern succeeds.
1134
1135 If any positional patterns are present, they are converted to keyword
1136 patterns using the :data:`~object.__match_args__` attribute on the class
1137 ``name_or_attr`` before matching:
1138
1139 I. The equivalent of ``getattr(cls, "__match_args__", ())`` is called.
1140
1141 * If this raises an exception, the exception bubbles up.
1142
1143 * If the returned value is not a tuple, the conversion fails and
1144 :exc:`TypeError` is raised.
1145
1146 * If there are more positional patterns than ``len(cls.__match_args__)``,
1147 :exc:`TypeError` is raised.
1148
1149 * Otherwise, positional pattern ``i`` is converted to a keyword pattern
1150 using ``__match_args__[i]`` as the keyword. ``__match_args__[i]`` must
1151 be a string; if not :exc:`TypeError` is raised.
1152
1153 * If there are duplicate keywords, :exc:`TypeError` is raised.
1154
1155 .. seealso:: :ref:`class-pattern-matching`
1156
1157 II. Once all positional patterns have been converted to keyword patterns,
1158 the match proceeds as if there were only keyword patterns.
1159
1160 For the following built-in types the handling of positional subpatterns is
1161 different:
1162
1163 * :class:`bool`
1164 * :class:`bytearray`
1165 * :class:`bytes`
1166 * :class:`dict`
1167 * :class:`float`
1168 * :class:`frozenset`
1169 * :class:`int`
1170 * :class:`list`
1171 * :class:`set`
1172 * :class:`str`
1173 * :class:`tuple`
1174
1175 These classes accept a single positional argument, and the pattern there is matched
1176 against the whole object rather than an attribute. For example ``int(0|1)`` matches
1177 the value ``0``, but not the value ``0.0``.
1178
1179 In simple terms ``CLS(P1, attr=P2)`` matches only if the following happens:
1180
1181 * ``isinstance(<subject>, CLS)``
1182 * convert ``P1`` to a keyword pattern using ``CLS.__match_args__``
1183 * For each keyword argument ``attr=P2``:
1184
1185 * ``hasattr(<subject>, "attr")``
1186 * ``P2`` matches ``<subject>.attr``
1187
1188 * ... and so on for the corresponding keyword argument/pattern pair.
1189
1190 .. seealso::
1191
1192 * :pep:`634` -- Structural Pattern Matching: Specification
1193 * :pep:`636` -- Structural Pattern Matching: Tutorial
1194
1195
1196 .. index::
1197 single: parameter; function definition
1198
1199 .. _function:
1200 .. _def:
1201
1202 Function definitions
1203 ====================
1204
1205 .. index::
1206 pair: statement; def
1207 pair: function; definition
1208 pair: function; name
1209 pair: name; binding
1210 pair: object; user-defined function
1211 pair: object; function
1212 pair: function; name
1213 pair: name; binding
1214 single: () (parentheses); function definition
1215 single: , (comma); parameter list
1216 single: : (colon); compound statement
1217
1218 A function definition defines a user-defined function object (see section
1219 :ref:`types`):
1220
1221 .. productionlist:: python-grammar
1222 funcdef: [`decorators`] "def" `funcname` [`type_params`] "(" [`parameter_list`] ")"
1223 : ["->" `expression`] ":" `suite`
1224 decorators: `decorator`+
1225 decorator: "@" `assignment_expression` NEWLINE
1226 parameter_list: `defparameter` ("," `defparameter`)* "," "/" ["," [`parameter_list_no_posonly`]]
1227 : | `parameter_list_no_posonly`
1228 parameter_list_no_posonly: `defparameter` ("," `defparameter`)* ["," [`parameter_list_starargs`]]
1229 : | `parameter_list_starargs`
1230 parameter_list_starargs: "*" [`star_parameter`] ("," `defparameter`)* ["," [`parameter_star_kwargs`]]
1231 : | "*" ("," `defparameter`)+ ["," [`parameter_star_kwargs`]]
1232 : | `parameter_star_kwargs`
1233 parameter_star_kwargs: "**" `parameter` [","]
1234 parameter: `identifier` [":" `expression`]
1235 star_parameter: `identifier` [":" ["*"] `expression`]
1236 defparameter: `parameter` ["=" `expression`]
1237 funcname: `identifier`
1238
1239
1240 A function definition is an executable statement. Its execution binds the
1241 function name in the current local namespace to a function object (a wrapper
1242 around the executable code for the function). This function object contains a
1243 reference to the current global namespace as the global namespace to be used
1244 when the function is called.
1245
1246 The function definition does not execute the function body; this gets executed
1247 only when the function is called. [#]_
1248
1249 .. index::
1250 single: @ (at); function definition
1251
1252 A function definition may be wrapped by one or more :term:`decorator` expressions.
1253 Decorator expressions are evaluated when the function is defined, in the scope
1254 that contains the function definition. The result must be a callable, which is
1255 invoked with the function object as the only argument. The returned value is
1256 bound to the function name instead of the function object. Multiple decorators
1257 are applied in nested fashion. For example, the following code ::
1258
1259 @f1(arg)
1260 @f2
1261 def func(): pass
1262
1263 is roughly equivalent to ::
1264
1265 def func(): pass
1266 func = f1(arg)(f2(func))
1267
1268 except that the original function is not temporarily bound to the name ``func``.
1269
1270 .. versionchanged:: 3.9
1271 Functions may be decorated with any valid
1272 :token:`~python-grammar:assignment_expression`. Previously, the grammar was
1273 much more restrictive; see :pep:`614` for details.
1274
1275 A list of :ref:`type parameters <type-params>` may be given in square brackets
1276 between the function's name and the opening parenthesis for its parameter list.
1277 This indicates to static type checkers that the function is generic. At runtime,
1278 the type parameters can be retrieved from the function's
1279 :attr:`~function.__type_params__`
1280 attribute. See :ref:`generic-functions` for more.
1281
1282 .. versionchanged:: 3.12
1283 Type parameter lists are new in Python 3.12.
1284
1285 .. index::
1286 triple: default; parameter; value
1287 single: argument; function definition
1288 single: = (equals); function definition
1289
1290 When one or more :term:`parameters <parameter>` have the form *parameter* ``=``
1291 *expression*, the function is said to have "default parameter values." For a
1292 parameter with a default value, the corresponding :term:`argument` may be
1293 omitted from a call, in which
1294 case the parameter's default value is substituted. If a parameter has a default
1295 value, all following parameters up until the "``*``" must also have a default
1296 value --- this is a syntactic restriction that is not expressed by the grammar.
1297
1298 **Default parameter values are evaluated from left to right when the function
1299 definition is executed.** This means that the expression is evaluated once, when
1300 the function is defined, and that the same "pre-computed" value is used for each
1301 call. This is especially important to understand when a default parameter value is a
1302 mutable object, such as a list or a dictionary: if the function modifies the
1303 object (e.g. by appending an item to a list), the default parameter value is in effect
1304 modified. This is generally not what was intended. A way around this is to use
1305 ``None`` as the default, and explicitly test for it in the body of the function,
1306 for example::
1307
1308 def whats_on_the_telly(penguin=None):
1309 if penguin is None:
1310 penguin = []
1311 penguin.append("property of the zoo")
1312 return penguin
1313
1314 .. index::
1315 single: / (slash); function definition
1316 single: * (asterisk); function definition
1317 single: **; function definition
1318
1319 Function call semantics are described in more detail in section :ref:`calls`. A
1320 function call always assigns values to all parameters mentioned in the parameter
1321 list, either from positional arguments, from keyword arguments, or from default
1322 values. If the form "``*identifier``" is present, it is initialized to a tuple
1323 receiving any excess positional parameters, defaulting to the empty tuple.
1324 If the form "``**identifier``" is present, it is initialized to a new
1325 ordered mapping receiving any excess keyword arguments, defaulting to a
1326 new empty mapping of the same type. Parameters after "``*``" or
1327 "``*identifier``" are keyword-only parameters and may only be passed
1328 by keyword arguments. Parameters before "``/``" are positional-only parameters
1329 and may only be passed by positional arguments.
1330
1331 .. versionchanged:: 3.8
1332 The ``/`` function parameter syntax may be used to indicate positional-only
1333 parameters. See :pep:`570` for details.
1334
1335 .. index::
1336 pair: function; annotations
1337 single: ->; function annotations
1338 single: : (colon); function annotations
1339
1340 Parameters may have an :term:`annotation <function annotation>` of the form "``: expression``"
1341 following the parameter name. Any parameter may have an annotation, even those of the form
1342 ``*identifier`` or ``**identifier``. (As a special case, parameters of the form
1343 ``*identifier`` may have an annotation "``: *expression``".) Functions may have "return" annotation of
1344 the form "``-> expression``" after the parameter list. These annotations can be
1345 any valid Python expression. The presence of annotations does not change the
1346 semantics of a function. The annotation values are available as values of
1347 a dictionary keyed by the parameters' names in the :attr:`__annotations__`
1348 attribute of the function object. If the ``annotations`` import from
1349 :mod:`__future__` is used, annotations are preserved as strings at runtime which
1350 enables postponed evaluation. Otherwise, they are evaluated when the function
1351 definition is executed. In this case annotations may be evaluated in
1352 a different order than they appear in the source code.
1353
1354 .. versionchanged:: 3.11
1355 Parameters of the form "``*identifier``" may have an annotation
1356 "``: *expression``". See :pep:`646`.
1357
1358 .. index:: pair: lambda; expression
1359
1360 It is also possible to create anonymous functions (functions not bound to a
1361 name), for immediate use in expressions. This uses lambda expressions, described in
1362 section :ref:`lambda`. Note that the lambda expression is merely a shorthand for a
1363 simplified function definition; a function defined in a ":keyword:`def`"
1364 statement can be passed around or assigned to another name just like a function
1365 defined by a lambda expression. The ":keyword:`!def`" form is actually more powerful
1366 since it allows the execution of multiple statements and annotations.
1367
1368 **Programmer's note:** Functions are first-class objects. A "``def``" statement
1369 executed inside a function definition defines a local function that can be
1370 returned or passed around. Free variables used in the nested function can
1371 access the local variables of the function containing the def. See section
1372 :ref:`naming` for details.
1373
1374 .. seealso::
1375
1376 :pep:`3107` - Function Annotations
1377 The original specification for function annotations.
1378
1379 :pep:`484` - Type Hints
1380 Definition of a standard meaning for annotations: type hints.
1381
1382 :pep:`526` - Syntax for Variable Annotations
1383 Ability to type hint variable declarations, including class
1384 variables and instance variables.
1385
1386 :pep:`563` - Postponed Evaluation of Annotations
1387 Support for forward references within annotations by preserving
1388 annotations in a string form at runtime instead of eager evaluation.
1389
1390 :pep:`318` - Decorators for Functions and Methods
1391 Function and method decorators were introduced.
1392 Class decorators were introduced in :pep:`3129`.
1393
1394 .. _class:
1395
1396 Class definitions
1397 =================
1398
1399 .. index::
1400 pair: object; class
1401 pair: statement; class
1402 pair: class; definition
1403 pair: class; name
1404 pair: name; binding
1405 pair: execution; frame
1406 single: inheritance
1407 single: docstring
1408 single: () (parentheses); class definition
1409 single: , (comma); expression list
1410 single: : (colon); compound statement
1411
1412 A class definition defines a class object (see section :ref:`types`):
1413
1414 .. productionlist:: python-grammar
1415 classdef: [`decorators`] "class" `classname` [`type_params`] [`inheritance`] ":" `suite`
1416 inheritance: "(" [`argument_list`] ")"
1417 classname: `identifier`
1418
1419 A class definition is an executable statement. The inheritance list usually
1420 gives a list of base classes (see :ref:`metaclasses` for more advanced uses), so
1421 each item in the list should evaluate to a class object which allows
1422 subclassing. Classes without an inheritance list inherit, by default, from the
1423 base class :class:`object`; hence, ::
1424
1425 class Foo:
1426 pass
1427
1428 is equivalent to ::
1429
1430 class Foo(object):
1431 pass
1432
1433 The class's suite is then executed in a new execution frame (see :ref:`naming`),
1434 using a newly created local namespace and the original global namespace.
1435 (Usually, the suite contains mostly function definitions.) When the class's
1436 suite finishes execution, its execution frame is discarded but its local
1437 namespace is saved. [#]_ A class object is then created using the inheritance
1438 list for the base classes and the saved local namespace for the attribute
1439 dictionary. The class name is bound to this class object in the original local
1440 namespace.
1441
1442 The order in which attributes are defined in the class body is preserved
1443 in the new class's :attr:`~type.__dict__`. Note that this is reliable only right
1444 after the class is created and only for classes that were defined using
1445 the definition syntax.
1446
1447 Class creation can be customized heavily using :ref:`metaclasses <metaclasses>`.
1448
1449 .. index::
1450 single: @ (at); class definition
1451
1452 Classes can also be decorated: just like when decorating functions, ::
1453
1454 @f1(arg)
1455 @f2
1456 class Foo: pass
1457
1458 is roughly equivalent to ::
1459
1460 class Foo: pass
1461 Foo = f1(arg)(f2(Foo))
1462
1463 The evaluation rules for the decorator expressions are the same as for function
1464 decorators. The result is then bound to the class name.
1465
1466 .. versionchanged:: 3.9
1467 Classes may be decorated with any valid
1468 :token:`~python-grammar:assignment_expression`. Previously, the grammar was
1469 much more restrictive; see :pep:`614` for details.
1470
1471 A list of :ref:`type parameters <type-params>` may be given in square brackets
1472 immediately after the class's name.
1473 This indicates to static type checkers that the class is generic. At runtime,
1474 the type parameters can be retrieved from the class's
1475 :attr:`~type.__type_params__` attribute. See :ref:`generic-classes` for more.
1476
1477 .. versionchanged:: 3.12
1478 Type parameter lists are new in Python 3.12.
1479
1480 **Programmer's note:** Variables defined in the class definition are class
1481 attributes; they are shared by instances. Instance attributes can be set in a
1482 method with ``self.name = value``. Both class and instance attributes are
1483 accessible through the notation "``self.name``", and an instance attribute hides
1484 a class attribute with the same name when accessed in this way. Class
1485 attributes can be used as defaults for instance attributes, but using mutable
1486 values there can lead to unexpected results. :ref:`Descriptors <descriptors>`
1487 can be used to create instance variables with different implementation details.
1488
1489
1490 .. seealso::
1491
1492 :pep:`3115` - Metaclasses in Python 3000
1493 The proposal that changed the declaration of metaclasses to the current
1494 syntax, and the semantics for how classes with metaclasses are
1495 constructed.
1496
1497 :pep:`3129` - Class Decorators
1498 The proposal that added class decorators. Function and method decorators
1499 were introduced in :pep:`318`.
1500
1501
1502 .. _async:
1503
1504 Coroutines
1505 ==========
1506
1507 .. versionadded:: 3.5
1508
1509 .. index:: pair: statement; async def
1510 .. _`async def`:
1511
1512 Coroutine function definition
1513 -----------------------------
1514
1515 .. productionlist:: python-grammar
1516 async_funcdef: [`decorators`] "async" "def" `funcname` "(" [`parameter_list`] ")"
1517 : ["->" `expression`] ":" `suite`
1518
1519 .. index::
1520 pair: keyword; async
1521 pair: keyword; await
1522
1523 Execution of Python coroutines can be suspended and resumed at many points
1524 (see :term:`coroutine`). :keyword:`await` expressions, :keyword:`async for` and
1525 :keyword:`async with` can only be used in the body of a coroutine function.
1526
1527 Functions defined with ``async def`` syntax are always coroutine functions,
1528 even if they do not contain ``await`` or ``async`` keywords.
1529
1530 It is a :exc:`SyntaxError` to use a ``yield from`` expression inside the body
1531 of a coroutine function.
1532
1533 An example of a coroutine function::
1534
1535 async def func(param1, param2):
1536 do_stuff()
1537 await some_coroutine()
1538
1539 .. versionchanged:: 3.7
1540 ``await`` and ``async`` are now keywords; previously they were only
1541 treated as such inside the body of a coroutine function.
1542
1543 .. index:: pair: statement; async for
1544 .. _`async for`:
1545
1546 The :keyword:`!async for` statement
1547 -----------------------------------
1548
1549 .. productionlist:: python-grammar
1550 async_for_stmt: "async" `for_stmt`
1551
1552 An :term:`asynchronous iterable` provides an ``__aiter__`` method that directly
1553 returns an :term:`asynchronous iterator`, which can call asynchronous code in
1554 its ``__anext__`` method.
1555
1556 The ``async for`` statement allows convenient iteration over asynchronous
1557 iterables.
1558
1559 The following code::
1560
1561 async for TARGET in ITER:
1562 SUITE
1563 else:
1564 SUITE2
1565
1566 Is semantically equivalent to::
1567
1568 iter = (ITER).__aiter__()
1569 running = True
1570
1571 while running:
1572 try:
1573 TARGET = await iter.__anext__()
1574 except StopAsyncIteration:
1575 running = False
1576 else:
1577 SUITE
1578 else:
1579 SUITE2
1580
1581 except that implicit :ref:`special method lookup <special-lookup>` is used
1582 for :meth:`~object.__aiter__` and :meth:`~object.__anext__`.
1583
1584 It is a :exc:`SyntaxError` to use an ``async for`` statement outside the
1585 body of a coroutine function.
1586
1587
1588 .. index:: pair: statement; async with
1589 .. _`async with`:
1590
1591 The :keyword:`!async with` statement
1592 ------------------------------------
1593
1594 .. productionlist:: python-grammar
1595 async_with_stmt: "async" `with_stmt`
1596
1597 An :term:`asynchronous context manager` is a :term:`context manager` that is
1598 able to suspend execution in its *enter* and *exit* methods.
1599
1600 The following code::
1601
1602 async with EXPRESSION as TARGET:
1603 SUITE
1604
1605 is semantically equivalent to::
1606
1607 manager = (EXPRESSION)
1608 aenter = manager.__aenter__
1609 aexit = manager.__aexit__
1610 value = await aenter()
1611 hit_except = False
1612
1613 try:
1614 TARGET = value
1615 SUITE
1616 except:
1617 hit_except = True
1618 if not await aexit(*sys.exc_info()):
1619 raise
1620 finally:
1621 if not hit_except:
1622 await aexit(None, None, None)
1623
1624 except that implicit :ref:`special method lookup <special-lookup>` is used
1625 for :meth:`~object.__aenter__` and :meth:`~object.__aexit__`.
1626
1627 It is a :exc:`SyntaxError` to use an ``async with`` statement outside the
1628 body of a coroutine function.
1629
1630 .. seealso::
1631
1632 :pep:`492` - Coroutines with async and await syntax
1633 The proposal that made coroutines a proper standalone concept in Python,
1634 and added supporting syntax.
1635
1636 .. _type-params:
1637
1638 Type parameter lists
1639 ====================
1640
1641 .. versionadded:: 3.12
1642
1643 .. versionchanged:: 3.13
1644 Support for default values was added (see :pep:`696`).
1645
1646 .. index::
1647 single: type parameters
1648
1649 .. productionlist:: python-grammar
1650 type_params: "[" `type_param` ("," `type_param`)* "]"
1651 type_param: `typevar` | `typevartuple` | `paramspec`
1652 typevar: `identifier` (":" `expression`)? ("=" `expression`)?
1653 typevartuple: "*" `identifier` ("=" `expression`)?
1654 paramspec: "**" `identifier` ("=" `expression`)?
1655
1656 :ref:`Functions <def>` (including :ref:`coroutines <async def>`),
1657 :ref:`classes <class>` and :ref:`type aliases <type>` may
1658 contain a type parameter list::
1659
1660 def max[T](args: list[T]) -> T:
1661 ...
1662
1663 async def amax[T](args: list[T]) -> T:
1664 ...
1665
1666 class Bag[T]:
1667 def __iter__(self) -> Iterator[T]:
1668 ...
1669
1670 def add(self, arg: T) -> None:
1671 ...
1672
1673 type ListOrSet[T] = list[T] | set[T]
1674
1675 Semantically, this indicates that the function, class, or type alias is
1676 generic over a type variable. This information is primarily used by static
1677 type checkers, and at runtime, generic objects behave much like their
1678 non-generic counterparts.
1679
1680 Type parameters are declared in square brackets (``[]``) immediately
1681 after the name of the function, class, or type alias. The type parameters
1682 are accessible within the scope of the generic object, but not elsewhere.
1683 Thus, after a declaration ``def func[T](): pass``, the name ``T`` is not available in
1684 the module scope. Below, the semantics of generic objects are described
1685 with more precision. The scope of type parameters is modeled with a special
1686 function (technically, an :ref:`annotation scope <annotation-scopes>`) that
1687 wraps the creation of the generic object.
1688
1689 Generic functions, classes, and type aliases have a
1690 :attr:`~definition.__type_params__` attribute listing their type parameters.
1691
1692 Type parameters come in three kinds:
1693
1694 * :data:`typing.TypeVar`, introduced by a plain name (e.g., ``T``). Semantically, this
1695 represents a single type to a type checker.
1696 * :data:`typing.TypeVarTuple`, introduced by a name prefixed with a single
1697 asterisk (e.g., ``*Ts``). Semantically, this stands for a tuple of any
1698 number of types.
1699 * :data:`typing.ParamSpec`, introduced by a name prefixed with two asterisks
1700 (e.g., ``**P``). Semantically, this stands for the parameters of a callable.
1701
1702 :data:`typing.TypeVar` declarations can define *bounds* and *constraints* with
1703 a colon (``:``) followed by an expression. A single expression after the colon
1704 indicates a bound (e.g. ``T: int``). Semantically, this means
1705 that the :data:`!typing.TypeVar` can only represent types that are a subtype of
1706 this bound. A parenthesized tuple of expressions after the colon indicates a
1707 set of constraints (e.g. ``T: (str, bytes)``). Each member of the tuple should be a
1708 type (again, this is not enforced at runtime). Constrained type variables can only
1709 take on one of the types in the list of constraints.
1710
1711 For :data:`!typing.TypeVar`\ s declared using the type parameter list syntax,
1712 the bound and constraints are not evaluated when the generic object is created,
1713 but only when the value is explicitly accessed through the attributes ``__bound__``
1714 and ``__constraints__``. To accomplish this, the bounds or constraints are
1715 evaluated in a separate :ref:`annotation scope <annotation-scopes>`.
1716
1717 :data:`typing.TypeVarTuple`\ s and :data:`typing.ParamSpec`\ s cannot have bounds
1718 or constraints.
1719
1720 All three flavors of type parameters can also have a *default value*, which is used
1721 when the type parameter is not explicitly provided. This is added by appending
1722 a single equals sign (``=``) followed by an expression. Like the bounds and
1723 constraints of type variables, the default value is not evaluated when the
1724 object is created, but only when the type parameter's ``__default__`` attribute
1725 is accessed. To this end, the default value is evaluated in a separate
1726 :ref:`annotation scope <annotation-scopes>`. If no default value is specified
1727 for a type parameter, the ``__default__`` attribute is set to the special
1728 sentinel object :data:`typing.NoDefault`.
1729
1730 The following example indicates the full set of allowed type parameter declarations::
1731
1732 def overly_generic[
1733 SimpleTypeVar,
1734 TypeVarWithDefault = int,
1735 TypeVarWithBound: int,
1736 TypeVarWithConstraints: (str, bytes),
1737 *SimpleTypeVarTuple = (int, float),
1738 **SimpleParamSpec = (str, bytearray),
1739 ](
1740 a: SimpleTypeVar,
1741 b: TypeVarWithDefault,
1742 c: TypeVarWithBound,
1743 d: Callable[SimpleParamSpec, TypeVarWithConstraints],
1744 *e: SimpleTypeVarTuple,
1745 ): ...
1746
1747 .. _generic-functions:
1748
1749 Generic functions
1750 -----------------
1751
1752 Generic functions are declared as follows::
1753
1754 def func[T](arg: T): ...
1755
1756 This syntax is equivalent to::
1757
1758 annotation-def TYPE_PARAMS_OF_func():
1759 T = typing.TypeVar("T")
1760 def func(arg: T): ...
1761 func.__type_params__ = (T,)
1762 return func
1763 func = TYPE_PARAMS_OF_func()
1764
1765 Here ``annotation-def`` indicates an :ref:`annotation scope <annotation-scopes>`,
1766 which is not actually bound to any name at runtime. (One
1767 other liberty is taken in the translation: the syntax does not go through
1768 attribute access on the :mod:`typing` module, but creates an instance of
1769 :data:`typing.TypeVar` directly.)
1770
1771 The annotations of generic functions are evaluated within the annotation scope
1772 used for declaring the type parameters, but the function's defaults and
1773 decorators are not.
1774
1775 The following example illustrates the scoping rules for these cases,
1776 as well as for additional flavors of type parameters::
1777
1778 @decorator
1779 def func[T: int, *Ts, **P](*args: *Ts, arg: Callable[P, T] = some_default):
1780 ...
1781
1782 Except for the :ref:`lazy evaluation <lazy-evaluation>` of the
1783 :class:`~typing.TypeVar` bound, this is equivalent to::
1784
1785 DEFAULT_OF_arg = some_default
1786
1787 annotation-def TYPE_PARAMS_OF_func():
1788
1789 annotation-def BOUND_OF_T():
1790 return int
1791 # In reality, BOUND_OF_T() is evaluated only on demand.
1792 T = typing.TypeVar("T", bound=BOUND_OF_T())
1793
1794 Ts = typing.TypeVarTuple("Ts")
1795 P = typing.ParamSpec("P")
1796
1797 def func(*args: *Ts, arg: Callable[P, T] = DEFAULT_OF_arg):
1798 ...
1799
1800 func.__type_params__ = (T, Ts, P)
1801 return func
1802 func = decorator(TYPE_PARAMS_OF_func())
1803
1804 The capitalized names like ``DEFAULT_OF_arg`` are not actually
1805 bound at runtime.
1806
1807 .. _generic-classes:
1808
1809 Generic classes
1810 ---------------
1811
1812 Generic classes are declared as follows::
1813
1814 class Bag[T]: ...
1815
1816 This syntax is equivalent to::
1817
1818 annotation-def TYPE_PARAMS_OF_Bag():
1819 T = typing.TypeVar("T")
1820 class Bag(typing.Generic[T]):
1821 __type_params__ = (T,)
1822 ...
1823 return Bag
1824 Bag = TYPE_PARAMS_OF_Bag()
1825
1826 Here again ``annotation-def`` (not a real keyword) indicates an
1827 :ref:`annotation scope <annotation-scopes>`, and the name
1828 ``TYPE_PARAMS_OF_Bag`` is not actually bound at runtime.
1829
1830 Generic classes implicitly inherit from :data:`typing.Generic`.
1831 The base classes and keyword arguments of generic classes are
1832 evaluated within the type scope for the type parameters,
1833 and decorators are evaluated outside that scope. This is illustrated
1834 by this example::
1835
1836 @decorator
1837 class Bag(Base[T], arg=T): ...
1838
1839 This is equivalent to::
1840
1841 annotation-def TYPE_PARAMS_OF_Bag():
1842 T = typing.TypeVar("T")
1843 class Bag(Base[T], typing.Generic[T], arg=T):
1844 __type_params__ = (T,)
1845 ...
1846 return Bag
1847 Bag = decorator(TYPE_PARAMS_OF_Bag())
1848
1849 .. _generic-type-aliases:
1850
1851 Generic type aliases
1852 --------------------
1853
1854 The :keyword:`type` statement can also be used to create a generic type alias::
1855
1856 type ListOrSet[T] = list[T] | set[T]
1857
1858 Except for the :ref:`lazy evaluation <lazy-evaluation>` of the value,
1859 this is equivalent to::
1860
1861 annotation-def TYPE_PARAMS_OF_ListOrSet():
1862 T = typing.TypeVar("T")
1863
1864 annotation-def VALUE_OF_ListOrSet():
1865 return list[T] | set[T]
1866 # In reality, the value is lazily evaluated
1867 return typing.TypeAliasType("ListOrSet", VALUE_OF_ListOrSet(), type_params=(T,))
1868 ListOrSet = TYPE_PARAMS_OF_ListOrSet()
1869
1870 Here, ``annotation-def`` (not a real keyword) indicates an
1871 :ref:`annotation scope <annotation-scopes>`. The capitalized names
1872 like ``TYPE_PARAMS_OF_ListOrSet`` are not actually bound at runtime.
1873
1874 .. rubric:: Footnotes
1875
1876 .. [#] The exception is propagated to the invocation stack unless
1877 there is a :keyword:`finally` clause which happens to raise another
1878 exception. That new exception causes the old one to be lost.
1879
1880 .. [#] In pattern matching, a sequence is defined as one of the following:
1881
1882 * a class that inherits from :class:`collections.abc.Sequence`
1883 * a Python class that has been registered as :class:`collections.abc.Sequence`
1884 * a builtin class that has its (CPython) :c:macro:`Py_TPFLAGS_SEQUENCE` bit set
1885 * a class that inherits from any of the above
1886
1887 The following standard library classes are sequences:
1888
1889 * :class:`array.array`
1890 * :class:`collections.deque`
1891 * :class:`list`
1892 * :class:`memoryview`
1893 * :class:`range`
1894 * :class:`tuple`
1895
1896 .. note:: Subject values of type ``str``, ``bytes``, and ``bytearray``
1897 do not match sequence patterns.
1898
1899 .. [#] In pattern matching, a mapping is defined as one of the following:
1900
1901 * a class that inherits from :class:`collections.abc.Mapping`
1902 * a Python class that has been registered as :class:`collections.abc.Mapping`
1903 * a builtin class that has its (CPython) :c:macro:`Py_TPFLAGS_MAPPING` bit set
1904 * a class that inherits from any of the above
1905
1906 The standard library classes :class:`dict` and :class:`types.MappingProxyType`
1907 are mappings.
1908
1909 .. [#] A string literal appearing as the first statement in the function body is
1910 transformed into the function's :attr:`~function.__doc__` attribute and
1911 therefore the function's :term:`docstring`.
1912
1913 .. [#] A string literal appearing as the first statement in the class body is
1914 transformed into the namespace's :attr:`~type.__doc__` item and therefore
1915 the class's :term:`docstring`.