8.Compound statements

Compound statements contain (groups of) other statements; they affect or controlthe execution of those other statements in some way. In general, compoundstatements span multiple lines, although in simple incarnations a whole compoundstatement may be contained in one line.

Theif,while andfor statements implementtraditional control flow constructs.try specifies exceptionhandlers and/or cleanup code for a group of statements, while thewith statement allows the execution of initialization andfinalization code around a block of code. Function and class definitions arealso syntactically compound statements.

A compound statement consists of one or more ‘clauses.’ A clause consists of aheader and a ‘suite.’ The clause headers of a particular compound statement areall at the same indentation level. Each clause header begins with a uniquelyidentifying keyword and ends with a colon. A suite is a group of statementscontrolled by a clause. A suite can be one or more semicolon-separated simplestatements on the same line as the header, following the header’s colon, or itcan be one or more indented statements on subsequent lines. Only the latterform of a suite can contain nested compound statements; the following is illegal,mostly because it wouldn’t be clear to whichif clause a followingelse clause would belong:

iftest1:iftest2:print(x)

Also note that the semicolon binds tighter than the colon in this context, sothat in the following example, either all or none of theprint() calls areexecuted:

ifx<y<z:print(x);print(y);print(z)

Summarizing:

compound_stmt ::=if_stmt                  |while_stmt                  |for_stmt                  |try_stmt                  |with_stmt                  |match_stmt                  |funcdef                  |classdef                  |async_with_stmt                  |async_for_stmt                  |async_funcdefsuite         ::=stmt_list NEWLINE | NEWLINE INDENTstatement+ DEDENTstatement     ::=stmt_list NEWLINE |compound_stmtstmt_list     ::=simple_stmt (";"simple_stmt)* [";"]

Note that statements always end in aNEWLINE possibly followed by aDEDENT. Also note that optional continuation clauses always begin with akeyword that cannot start a statement, thus there are no ambiguities (the‘danglingelse’ problem is solved in Python by requiring nestedif statements to be indented).

The formatting of the grammar rules in the following sections places each clauseon a separate line for clarity.

8.1.Theif statement

Theif statement is used for conditional execution:

if_stmt ::= "if"assignment_expression ":"suite            ("elif"assignment_expression ":"suite)*            ["else" ":"suite]

It selects exactly one of the suites by evaluating the expressions one by oneuntil one is found to be true (see sectionBoolean operations for the definition oftrue and false); then that suite is executed (and no other part of theif statement is executed or evaluated). If all expressions arefalse, the suite of theelse clause, if present, is executed.

8.2.Thewhile statement

Thewhile statement is used for repeated execution as long as anexpression is true:

while_stmt ::= "while"assignment_expression ":"suite               ["else" ":"suite]

This repeatedly tests the expression and, if it is true, executes the firstsuite; if the expression is false (which may be the first time it is tested) thesuite of theelse clause, if present, is executed and the loopterminates.

Abreak statement executed in the first suite terminates the loopwithout executing theelse clause’s suite. Acontinuestatement executed in the first suite skips the rest of the suite and goes backto testing the expression.

8.3.Thefor statement

Thefor statement is used to iterate over the elements of a sequence(such as a string, tuple or list) or other iterable object:

for_stmt ::= "for"target_list "in"starred_list ":"suite             ["else" ":"suite]

Thestarred_list expression is evaluated once; it should yield aniterable object. Aniterator is created for that iterable.The first item providedby the iterator is then assigned to the target list using the standardrules for assignments (seeAssignment statements), and the suite is executed. Thisrepeats for each item provided by the iterator. When the iterator is exhausted,the suite in theelse clause,if present, is executed, and the loop terminates.

Abreak statement executed in the first suite terminates the loopwithout executing theelse clause’s suite. Acontinuestatement executed in the first suite skips the rest of the suite and continueswith the next item, or with theelse clause if there is no nextitem.

The for-loop makes assignments to the variables in the target list.This overwrites all previous assignments to those variables includingthose made in the suite of the for-loop:

foriinrange(10):print(i)i=5# this will not affect the for-loop# because i will be overwritten with the next# index in the range

Names in the target list are not deleted when the loop is finished, but if thesequence is empty, they will not have been assigned to at all by the loop. Hint:the built-in typerange() represents immutable arithmetic sequences of integers.For instance, iteratingrange(3) successively yields 0, 1, and then 2.

Changed in version 3.11:Starred elements are now allowed in the expression list.

8.4.Thetry statement

Thetry statement specifies exception handlers and/or cleanup codefor a group of statements:

try_stmt  ::=try1_stmt |try2_stmt |try3_stmttry1_stmt ::= "try" ":"suite              ("except" [expression ["as"identifier]] ":"suite)+              ["else" ":"suite]              ["finally" ":"suite]try2_stmt ::= "try" ":"suite              ("except" "*"expression ["as"identifier] ":"suite)+              ["else" ":"suite]              ["finally" ":"suite]try3_stmt ::= "try" ":"suite              "finally" ":"suite

Additional information on exceptions can be found in sectionExceptions,and information on using theraise statement to generate exceptionsmay be found in sectionThe raise statement.

8.4.1.except clause

Theexcept clause(s) specify one or more exception handlers. When noexception occurs in thetry clause, no exception handler is executed.When an exception occurs in thetry suite, a search for an exceptionhandler is started. This search inspects theexcept clauses in turnuntil one is found that matches the exception.An expression-lessexcept clause, if present, must be last;it matches any exception.

For anexcept clause with an expression, theexpression must evaluate to an exception type or a tuple of exception types.The raised exception matches anexcept clause whose expression evaluatesto the class or anon-virtual base class of the exception object,or to a tuple that contains such a class.

If noexcept clause matches the exception,the search for an exception handlercontinues in the surrounding code and on the invocation stack.[1]

If the evaluation of an expressionin the header of anexcept clause raises an exception,the original search for a handler is canceled and a search starts forthe new exception in the surrounding code and on the call stack (it is treatedas if the entiretry statement raised the exception).

When a matchingexcept clause is found,the exception is assigned to the targetspecified after theas keyword in thatexcept clause,if present, and theexcept clause’s suite is executed.Allexcept clauses must have an executable block.When the end of this block is reached, execution continuesnormally after the entiretry statement.(This means that if two nested handlers exist for the same exception,and the exception occurs in thetry clause of the inner handler,the outer handler will not handle the exception.)

When an exception has been assigned usingastarget, it is cleared at theend of theexcept clause. This is as if

exceptEasN:foo

was translated to

exceptEasN:try:foofinally:delN

This means the exception must be assigned to a different name to be able torefer to it after theexcept clause.Exceptions are cleared because with thetraceback attached to them, they form a reference cycle with the stack frame,keeping all locals in that frame alive until the next garbage collection occurs.

Before anexcept clause’s suite is executed,the exception is stored in thesys module, where it can be accessedfrom within the body of theexcept clause by callingsys.exception(). When leaving an exception handler, the exceptionstored in thesys module is reset to its previous value:

>>>print(sys.exception())None>>>try:...raiseTypeError...except:...print(repr(sys.exception()))...try:...raiseValueError...except:...print(repr(sys.exception()))...print(repr(sys.exception()))...TypeError()ValueError()TypeError()>>>print(sys.exception())None

8.4.2.except* clause

Theexcept* clause(s) are used for handlingExceptionGroups. The exception type for matching is interpreted as inthe case ofexcept, but in the case of exception groups we can havepartial matches when the type matches some of the exceptions in the group.This means that multipleexcept* clauses can execute,each handling part of the exception group.Each clause executes at most once and handles an exception groupof all matching exceptions. Each exception in the group is handled by at mostoneexcept* clause, the first that matches it.

>>>try:...raiseExceptionGroup("eg",...[ValueError(1),TypeError(2),OSError(3),OSError(4)])...except*TypeErrorase:...print(f'caught{type(e)} with nested{e.exceptions}')...except*OSErrorase:...print(f'caught{type(e)} with nested{e.exceptions}')...caught <class 'ExceptionGroup'> with nested (TypeError(2),)caught <class 'ExceptionGroup'> with nested (OSError(3), OSError(4))  + Exception Group Traceback (most recent call last):  |   File "<stdin>", line 2, in <module>  | ExceptionGroup: eg  +-+---------------- 1 ----------------    | ValueError: 1    +------------------------------------

Any remaining exceptions that were not handled by anyexcept*clause are re-raised at the end, along with all exceptions that wereraised from within theexcept* clauses. If this list containsmore than one exception to reraise, they are combined into an exceptiongroup.

If the raised exception is not an exception group and its type matchesone of theexcept* clauses, it is caught and wrapped by anexception group with an empty message string.

>>>try:...raiseBlockingIOError...except*BlockingIOErrorase:...print(repr(e))...ExceptionGroup('', (BlockingIOError()))

Anexcept* clause must have a matching expression; it cannot beexcept*:.Furthermore, this expression cannot contain exception group types, because that wouldhave ambiguous semantics.

It is not possible to mixexcept andexcept*in the sametry.break,continue andreturncannot appear in anexcept* clause.

8.4.3.else clause

The optionalelse clause is executed if the control flow leaves thetry suite, no exception was raised, and noreturn,continue, orbreak statement was executed. Exceptions intheelse clause are not handled by the precedingexceptclauses.

8.4.4.finally clause

Iffinally is present, it specifies a ‘cleanup’ handler. Thetry clause is executed, including anyexcept andelse clauses. If an exception occurs in any of the clauses and isnot handled, the exception is temporarily saved. Thefinally clauseis executed. If there is a saved exception it is re-raised at the end of thefinally clause. If thefinally clause raises anotherexception, the saved exception is set as the context of the new exception.If thefinally clause executes areturn,breakorcontinue statement, the saved exception is discarded:

>>>deff():...try:...1/0...finally:...return42...>>>f()42

The exception information is not available to the program during execution ofthefinally clause.

When areturn,break orcontinue statement isexecuted in thetry suite of atry…finallystatement, thefinally clause is also executed ‘on the way out.’

The return value of a function is determined by the lastreturnstatement executed. Since thefinally clause always executes, areturn statement executed in thefinally clause willalways be the last one executed:

>>>deffoo():...try:...return'try'...finally:...return'finally'...>>>foo()'finally'

Changed in version 3.8:Prior to Python 3.8, acontinue statement was illegal in thefinally clause due to a problem with the implementation.

8.5.Thewith statement

Thewith statement is used to wrap the execution of a block withmethods defined by a context manager (see sectionWith Statement Context Managers).This allows commontry…except…finallyusage patterns to be encapsulated for convenient reuse.

with_stmt          ::= "with" ( "("with_stmt_contents ","? ")" |with_stmt_contents ) ":"suitewith_stmt_contents ::=with_item (","with_item)*with_item          ::=expression ["as"target]

The execution of thewith statement with one “item” proceeds as follows:

  1. The context expression (the expression given in thewith_item) is evaluated to obtain a context manager.

  2. The context manager’s__enter__() is loaded for later use.

  3. The context manager’s__exit__() is loaded for later use.

  4. The context manager’s__enter__() method is invoked.

  5. If a target was included in thewith statement, the return valuefrom__enter__() is assigned to it.

    Note

    Thewith statement guarantees that if the__enter__()method returns without an error, then__exit__() will always becalled. Thus, if an error occurs during the assignment to the target list,it will be treated the same as an error occurring within the suite wouldbe. See step 7 below.

  6. The suite is executed.

  7. The context manager’s__exit__() method is invoked. If an exceptioncaused the suite to be exited, its type, value, and traceback are passed asarguments to__exit__(). Otherwise, threeNone arguments aresupplied.

    If the suite was exited due to an exception, and the return value from the__exit__() method was false, the exception is reraised. If the returnvalue was true, the exception is suppressed, and execution continues with thestatement following thewith statement.

    If the suite was exited for any reason other than an exception, the returnvalue from__exit__() is ignored, and execution proceeds at the normallocation for the kind of exit that was taken.

The following code:

withEXPRESSIONasTARGET:SUITE

is semantically equivalent to:

manager=(EXPRESSION)enter=type(manager).__enter__exit=type(manager).__exit__value=enter(manager)hit_except=Falsetry:TARGET=valueSUITEexcept:hit_except=Trueifnotexit(manager,*sys.exc_info()):raisefinally:ifnothit_except:exit(manager,None,None,None)

With more than one item, the context managers are processed as if multiplewith statements were nested:

withA()asa,B()asb:SUITE

is semantically equivalent to:

withA()asa:withB()asb:SUITE

You can also write multi-item context managers in multiple lines ifthe items are surrounded by parentheses. For example:

with(A()asa,B()asb,):SUITE

Changed in version 3.1:Support for multiple context expressions.

Changed in version 3.10:Support for using grouping parentheses to break the statement in multiple lines.

See also

PEP 343 - The “with” statement

The specification, background, and examples for the Pythonwithstatement.

8.6.Thematch statement

Added in version 3.10.

The match statement is used for pattern matching. Syntax:

match_stmt   ::= 'match'subject_expr ":" NEWLINE INDENTcase_block+ DEDENTsubject_expr ::=star_named_expression ","star_named_expressions?                 |named_expressioncase_block   ::= 'case'patterns [guard] ":"block

Note

This section uses single quotes to denotesoft keywords.

Pattern matching takes a pattern as input (followingcase) and a subjectvalue (followingmatch). The pattern (which may contain subpatterns) ismatched against the subject value. The outcomes are:

  • A match success or failure (also termed a pattern success or failure).

  • Possible binding of matched values to a name. The prerequisites for this arefurther discussed below.

Thematch andcase keywords aresoft keywords.

See also

  • PEP 634 – Structural Pattern Matching: Specification

  • PEP 636 – Structural Pattern Matching: Tutorial

8.6.1.Overview

Here’s an overview of the logical flow of a match statement:

  1. The subject expressionsubject_expr is evaluated and a resulting subjectvalue obtained. If the subject expression contains a comma, a tuple isconstructed usingthe standard rules.

  2. Each pattern in acase_block is attempted to match with the subject value. Thespecific rules for success or failure are described below. The match attempt can alsobind some or all of the standalone names within the pattern. The precisepattern binding rules vary per pattern type and arespecified below.Name bindings made during a successful pattern matchoutlive the executed block and can be used after the match statement.

    Note

    During failed pattern matches, some subpatterns may succeed. Do notrely on bindings being made for a failed match. Conversely, do notrely on variables remaining unchanged after a failed match. The exactbehavior is dependent on implementation and may vary. This is anintentional decision made to allow different implementations to addoptimizations.

  3. If the pattern succeeds, the corresponding guard (if present) is evaluated. Inthis case all name bindings are guaranteed to have happened.

    • If the guard evaluates as true or is missing, theblock insidecase_block is executed.

    • Otherwise, the nextcase_block is attempted as described above.

    • If there are no further case blocks, the match statement is completed.

Note

Users should generally never rely on a pattern being evaluated. Depending onimplementation, the interpreter may cache values or use other optimizationswhich skip repeated evaluations.

A sample match statement:

>>>flag=False>>>match(100,200):...case(100,300):# Mismatch: 200 != 300...print('Case 1')...case(100,200)ifflag:# Successful match, but guard fails...print('Case 2')...case(100,y):# Matches and binds y to 200...print(f'Case 3, y:{y}')...case_:# Pattern not attempted...print('Case 4, I match anything!')...Case 3, y: 200

In this case,ifflag is a guard. Read more about that in the next section.

8.6.2.Guards

guard ::= "if"named_expression

Aguard (which is part of thecase) must succeed for code insidethecase block to execute. It takes the form:if followed by anexpression.

The logical flow of acase block with aguard follows:

  1. Check that the pattern in thecase block succeeded. If the patternfailed, theguard is not evaluated and the nextcase block ischecked.

  2. If the pattern succeeded, evaluate theguard.

    • If theguard condition evaluates as true, the case block isselected.

    • If theguard condition evaluates as false, the case block is notselected.

    • If theguard raises an exception during evaluation, the exceptionbubbles up.

Guards are allowed to have side effects as they are expressions. Guardevaluation must proceed from the first to the last case block, one at a time,skipping case blocks whose pattern(s) don’t all succeed. (I.e.,guard evaluation must happen in order.) Guard evaluation must stop once a caseblock is selected.

8.6.3.Irrefutable Case Blocks

An irrefutable case block is a match-all case block. A match statement may haveat most one irrefutable case block, and it must be last.

A case block is considered irrefutable if it has no guard and its pattern isirrefutable. A pattern is considered irrefutable if we can prove from itssyntax alone that it will always succeed. Only the following patterns areirrefutable:

8.6.4.Patterns

Note

This section uses grammar notations beyond standard EBNF:

  • the notationSEP.RULE+ is shorthand forRULE(SEPRULE)*

  • the notation!RULE is shorthand for a negative lookahead assertion

The top-level syntax forpatterns is:

patterns       ::=open_sequence_pattern |patternpattern        ::=as_pattern |or_patternclosed_pattern ::= |literal_pattern                   |capture_pattern                   |wildcard_pattern                   |value_pattern                   |group_pattern                   |sequence_pattern                   |mapping_pattern                   |class_pattern

The descriptions below will include a description “in simple terms” of what a patterndoes for illustration purposes (credits to Raymond Hettinger for a document thatinspired most of the descriptions). Note that these descriptions are purely forillustration purposes andmay not reflectthe underlying implementation. Furthermore, they do not cover all valid forms.

8.6.4.1.OR Patterns

An OR pattern is two or more patterns separated by verticalbars|. Syntax:

or_pattern ::= "|".closed_pattern+

Only the final subpattern may beirrefutable, and eachsubpattern must bind the same set of names to avoid ambiguity.

An OR pattern matches each of its subpatterns in turn to the subject value,until one succeeds. The OR pattern is then considered successful. Otherwise,if none of the subpatterns succeed, the OR pattern fails.

In simple terms,P1|P2|... will try to matchP1, if it fails it will try tomatchP2, succeeding immediately if any succeeds, failing otherwise.

8.6.4.2.AS Patterns

An AS pattern matches an OR pattern on the left of theaskeyword against a subject. Syntax:

as_pattern ::=or_pattern "as"capture_pattern

If the OR pattern fails, the AS pattern fails. Otherwise, the AS pattern bindsthe subject to the name on the right of the as keyword and succeeds.capture_pattern cannot be a_.

In simple termsPasNAME will match withP, and on success it willsetNAME=<subject>.

8.6.4.3.Literal Patterns

A literal pattern corresponds to mostliterals in Python. Syntax:

literal_pattern ::=signed_number                    |signed_number "+" NUMBER                    |signed_number "-" NUMBER                    |strings                    | "None"                    | "True"                    | "False"signed_number   ::= ["-"] NUMBER

The rulestrings and the tokenNUMBER are defined in thestandard Python grammar. Triple-quoted strings aresupported. Raw strings and byte strings are supported.f-strings arenot supported.

The formssigned_number'+'NUMBER andsigned_number'-'NUMBER arefor expressingcomplex numbers; they require a real numberon the left and an imaginary number on the right. E.g.3+4j.

In simple terms,LITERAL will succeed only if<subject>==LITERAL. Forthe singletonsNone,True andFalse, theis operator is used.

8.6.4.4.Capture Patterns

A capture pattern binds the subject value to a name.Syntax:

capture_pattern ::= !'_' NAME

A single underscore_ is not a capture pattern (this is what!'_'expresses). It is instead treated as awildcard_pattern.

In a given pattern, a given name can only be bound once. E.g.casex,x:... is invalid whilecase[x]|x:... is allowed.

Capture patterns always succeed. The binding follows scoping rulesestablished by the assignment expression operator inPEP 572; thename becomes a local variable in the closest containing function scope unlessthere’s an applicableglobal ornonlocal statement.

In simple termsNAME will always succeed and it will setNAME=<subject>.

8.6.4.5.Wildcard Patterns

A wildcard pattern always succeeds (matches anything)and binds no name. Syntax:

wildcard_pattern ::= '_'

_ is asoft keyword within any pattern,but only within patterns. It is an identifier, as usual, even withinmatch subject expressions,guards, andcase blocks.

In simple terms,_ will always succeed.

8.6.4.6.Value Patterns

A value pattern represents a named value in Python.Syntax:

value_pattern ::=attrattr          ::=name_or_attr "." NAMEname_or_attr  ::=attr | NAME

The dotted name in the pattern is looked up using standard Pythonname resolution rules. The pattern succeeds if thevalue found compares equal to the subject value (using the== equalityoperator).

In simple termsNAME1.NAME2 will succeed only if<subject>==NAME1.NAME2

Note

If the same value occurs multiple times in the same match statement, theinterpreter may cache the first value found and reuse it rather than repeatthe same lookup. This cache is strictly tied to a given execution of agiven match statement.

8.6.4.7.Group Patterns

A group pattern allows users to add parentheses around patterns toemphasize the intended grouping. Otherwise, it has no additional syntax.Syntax:

group_pattern ::= "("pattern ")"

In simple terms(P) has the same effect asP.

8.6.4.8.Sequence Patterns

A sequence pattern contains several subpatterns to be matched against sequence elements.The syntax is similar to the unpacking of a list or tuple.

sequence_pattern       ::= "[" [maybe_sequence_pattern] "]"                           | "(" [open_sequence_pattern] ")"open_sequence_pattern  ::=maybe_star_pattern "," [maybe_sequence_pattern]maybe_sequence_pattern ::= ",".maybe_star_pattern+ ","?maybe_star_pattern     ::=star_pattern |patternstar_pattern           ::= "*" (capture_pattern |wildcard_pattern)

There is no difference if parentheses or square bracketsare used for sequence patterns (i.e.(...) vs[...] ).

Note

A single pattern enclosed in parentheses without a trailing comma(e.g.(3|4)) is agroup pattern.While a single pattern enclosed in square brackets (e.g.[3|4]) isstill a sequence pattern.

At most one star subpattern may be in a sequence pattern. The star subpatternmay occur in any position. If no star subpattern is present, the sequencepattern is a fixed-length sequence pattern; otherwise it is a variable-lengthsequence pattern.

The following is the logical flow for matching a sequence pattern against asubject value:

  1. If the subject value is not a sequence[2], the sequence patternfails.

  2. If the subject value is an instance ofstr,bytes orbytearraythe sequence pattern fails.

  3. The subsequent steps depend on whether the sequence pattern is fixed orvariable-length.

    If the sequence pattern is fixed-length:

    1. If the length of the subject sequence is not equal to the number ofsubpatterns, the sequence pattern fails

    2. Subpatterns in the sequence pattern are matched to their correspondingitems in the subject sequence from left to right. Matching stops as soonas a subpattern fails. If all subpatterns succeed in matching theircorresponding item, the sequence pattern succeeds.

    Otherwise, if the sequence pattern is variable-length:

    1. If the length of the subject sequence is less than the number of non-starsubpatterns, the sequence pattern fails.

    2. The leading non-star subpatterns are matched to their corresponding itemsas for fixed-length sequences.

    3. If the previous step succeeds, the star subpattern matches a list formedof the remaining subject items, excluding the remaining itemscorresponding to non-star subpatterns following the star subpattern.

    4. Remaining non-star subpatterns are matched to their corresponding subjectitems, as for a fixed-length sequence.

    Note

    The length of the subject sequence is obtained vialen() (i.e. via the__len__() protocol). This length may becached by the interpreter in a similar manner asvalue patterns.

In simple terms[P1,P2,P3, …,P<N>] matches only if all the followinghappens:

  • check<subject> is a sequence

  • len(subject)==<N>

  • P1 matches<subject>[0] (note that this match can also bind names)

  • P2 matches<subject>[1] (note that this match can also bind names)

  • … and so on for the corresponding pattern/element.

8.6.4.9.Mapping Patterns

A mapping pattern contains one or more key-value patterns. The syntax issimilar to the construction of a dictionary.Syntax:

mapping_pattern     ::= "{" [items_pattern] "}"items_pattern       ::= ",".key_value_pattern+ ","?key_value_pattern   ::= (literal_pattern |value_pattern) ":"pattern                        |double_star_patterndouble_star_pattern ::= "**"capture_pattern

At most one double star pattern may be in a mapping pattern. The double starpattern must be the last subpattern in the mapping pattern.

Duplicate keys in mapping patterns are disallowed. Duplicate literal keys willraise aSyntaxError. Two keys that otherwise have the same value willraise aValueError at runtime.

The following is the logical flow for matching a mapping pattern against asubject value:

  1. If the subject value is not a mapping[3],the mapping pattern fails.

  2. If every key given in the mapping pattern is present in the subject mapping,and the pattern for each key matches the corresponding item of the subjectmapping, the mapping pattern succeeds.

  3. If duplicate keys are detected in the mapping pattern, the pattern isconsidered invalid. ASyntaxError is raised for duplicate literalvalues; or aValueError for named keys of the same value.

Note

Key-value pairs are matched using the two-argument form of the mappingsubject’sget() method. Matched key-value pairs must already be presentin the mapping, and not created on-the-fly via__missing__() or__getitem__().

In simple terms{KEY1:P1,KEY2:P2,...} matches only if all the followinghappens:

  • check<subject> is a mapping

  • KEY1in<subject>

  • P1 matches<subject>[KEY1]

  • … and so on for the corresponding KEY/pattern pair.

8.6.4.10.Class Patterns

A class pattern represents a class and its positional and keyword arguments(if any). Syntax:

class_pattern       ::=name_or_attr "(" [pattern_arguments ","?] ")"pattern_arguments   ::=positional_patterns [","keyword_patterns]                        |keyword_patternspositional_patterns ::= ",".pattern+keyword_patterns    ::= ",".keyword_pattern+keyword_pattern     ::= NAME "="pattern

The same keyword should not be repeated in class patterns.

The following is the logical flow for matching a class pattern against asubject value:

  1. Ifname_or_attr is not an instance of the builtintype , raiseTypeError.

  2. If the subject value is not an instance ofname_or_attr (tested viaisinstance()), the class pattern fails.

  3. If no pattern arguments are present, the pattern succeeds. Otherwise,the subsequent steps depend on whether keyword or positional argument patternsare present.

    For a number of built-in types (specified below), a single positionalsubpattern is accepted which will match the entire subject; for these typeskeyword patterns also work as for other types.

    If only keyword patterns are present, they are processed as follows,one by one:

    I. The keyword is looked up as an attribute on the subject.

    • If this raises an exception other thanAttributeError, theexception bubbles up.

    • If this raisesAttributeError, the class pattern has failed.

    • Else, the subpattern associated with the keyword pattern is matchedagainst the subject’s attribute value. If this fails, the classpattern fails; if this succeeds, the match proceeds to the next keyword.

    II. If all keyword patterns succeed, the class pattern succeeds.

    If any positional patterns are present, they are converted to keywordpatterns using the__match_args__ attribute on the classname_or_attr before matching:

    I. The equivalent ofgetattr(cls,"__match_args__",()) is called.

    • If this raises an exception, the exception bubbles up.

    • If the returned value is not a tuple, the conversion fails andTypeError is raised.

    • If there are more positional patterns thanlen(cls.__match_args__),TypeError is raised.

    • Otherwise, positional patterni is converted to a keyword patternusing__match_args__[i] as the keyword.__match_args__[i] mustbe a string; if notTypeError is raised.

    • If there are duplicate keywords,TypeError is raised.

    II. Once all positional patterns have been converted to keyword patterns,

    the match proceeds as if there were only keyword patterns.

    For the following built-in types the handling of positional subpatterns isdifferent:

    These classes accept a single positional argument, and the pattern there is matchedagainst the whole object rather than an attribute. For exampleint(0|1) matchesthe value0, but not the value0.0.

In simple termsCLS(P1,attr=P2) matches only if the following happens:

  • isinstance(<subject>,CLS)

  • convertP1 to a keyword pattern usingCLS.__match_args__

  • For each keyword argumentattr=P2:

    • hasattr(<subject>,"attr")

    • P2 matches<subject>.attr

  • … and so on for the corresponding keyword argument/pattern pair.

See also

  • PEP 634 – Structural Pattern Matching: Specification

  • PEP 636 – Structural Pattern Matching: Tutorial

8.7.Function definitions

A function definition defines a user-defined function object (see sectionThe standard type hierarchy):

funcdef                   ::= [decorators] "def"funcname [type_params] "(" [parameter_list] ")"                              ["->"expression] ":"suitedecorators                ::=decorator+decorator                 ::= "@"assignment_expression NEWLINEparameter_list            ::=defparameter (","defparameter)* "," "/" ["," [parameter_list_no_posonly]]                              |parameter_list_no_posonlyparameter_list_no_posonly ::=defparameter (","defparameter)* ["," [parameter_list_starargs]]                              |parameter_list_starargsparameter_list_starargs   ::= "*" [star_parameter] (","defparameter)* ["," [parameter_star_kwargs]]                              | "*" (","defparameter)+ ["," [parameter_star_kwargs]]                              |parameter_star_kwargsparameter_star_kwargs     ::= "**"parameter [","]parameter                 ::=identifier [":"expression]star_parameter            ::=identifier [":" ["*"]expression]defparameter              ::=parameter ["="expression]funcname                  ::=identifier

A function definition is an executable statement. Its execution binds thefunction name in the current local namespace to a function object (a wrapperaround the executable code for the function). This function object contains areference to the current global namespace as the global namespace to be usedwhen the function is called.

The function definition does not execute the function body; this gets executedonly when the function is called.[4]

A function definition may be wrapped by one or moredecorator expressions.Decorator expressions are evaluated when the function is defined, in the scopethat contains the function definition. The result must be a callable, which isinvoked with the function object as the only argument. The returned value isbound to the function name instead of the function object. Multiple decoratorsare applied in nested fashion. For example, the following code

@f1(arg)@f2deffunc():pass

is roughly equivalent to

deffunc():passfunc=f1(arg)(f2(func))

except that the original function is not temporarily bound to the namefunc.

Changed in version 3.9:Functions may be decorated with any validassignment_expression. Previously, the grammar wasmuch more restrictive; seePEP 614 for details.

A list oftype parameters may be given in square bracketsbetween the function’s name and the opening parenthesis for its parameter list.This indicates to static type checkers that the function is generic. At runtime,the type parameters can be retrieved from the function’s__type_params__attribute. SeeGeneric functions for more.

Changed in version 3.12:Type parameter lists are new in Python 3.12.

When one or moreparameters have the formparameter=expression, the function is said to have “default parameter values.” For aparameter with a default value, the correspondingargument may beomitted from a call, in whichcase the parameter’s default value is substituted. If a parameter has a defaultvalue, all following parameters up until the “*” must also have a defaultvalue — this is a syntactic restriction that is not expressed by the grammar.

Default parameter values are evaluated from left to right when the functiondefinition is executed. This means that the expression is evaluated once, whenthe function is defined, and that the same “pre-computed” value is used for eachcall. This is especially important to understand when a default parameter value is amutable object, such as a list or a dictionary: if the function modifies theobject (e.g. by appending an item to a list), the default parameter value is in effectmodified. This is generally not what was intended. A way around this is to useNone as the default, and explicitly test for it in the body of the function,e.g.:

defwhats_on_the_telly(penguin=None):ifpenguinisNone:penguin=[]penguin.append("property of the zoo")returnpenguin

Function call semantics are described in more detail in sectionCalls. Afunction call always assigns values to all parameters mentioned in the parameterlist, either from positional arguments, from keyword arguments, or from defaultvalues. If the form “*identifier” is present, it is initialized to a tuplereceiving any excess positional parameters, defaulting to the empty tuple.If the form “**identifier” is present, it is initialized to a newordered mapping receiving any excess keyword arguments, defaulting to anew empty mapping of the same type. Parameters after “*” or“*identifier” are keyword-only parameters and may only be passedby keyword arguments. Parameters before “/” are positional-only parametersand may only be passed by positional arguments.

Changed in version 3.8:The/ function parameter syntax may be used to indicate positional-onlyparameters. SeePEP 570 for details.

Parameters may have anannotation of the form “:expression”following the parameter name. Any parameter may have an annotation, even those of the form*identifier or**identifier. (As a special case, parameters of the form*identifier may have an annotation “:*expression”.) Functions may have “return” annotation ofthe form “->expression” after the parameter list. These annotations can beany valid Python expression. The presence of annotations does not change thesemantics of a function. The annotation values are available as values ofa dictionary keyed by the parameters’ names in the__annotations__attribute of the function object. If theannotations import from__future__ is used, annotations are preserved as strings at runtime whichenables postponed evaluation. Otherwise, they are evaluated when the functiondefinition is executed. In this case annotations may be evaluated ina different order than they appear in the source code.

Changed in version 3.11:Parameters of the form “*identifier” may have an annotation“:*expression”. SeePEP 646.

It is also possible to create anonymous functions (functions not bound to aname), for immediate use in expressions. This uses lambda expressions, described insectionLambdas. Note that the lambda expression is merely a shorthand for asimplified function definition; a function defined in a “def”statement can be passed around or assigned to another name just like a functiondefined by a lambda expression. The “def” form is actually more powerfulsince it allows the execution of multiple statements and annotations.

Programmer’s note: Functions are first-class objects. A “def” statementexecuted inside a function definition defines a local function that can bereturned or passed around. Free variables used in the nested function canaccess the local variables of the function containing the def. See sectionNaming and binding for details.

See also

PEP 3107 - Function Annotations

The original specification for function annotations.

PEP 484 - Type Hints

Definition of a standard meaning for annotations: type hints.

PEP 526 - Syntax for Variable Annotations

Ability to type hint variable declarations, including classvariables and instance variables.

PEP 563 - Postponed Evaluation of Annotations

Support for forward references within annotations by preservingannotations in a string form at runtime instead of eager evaluation.

PEP 318 - Decorators for Functions and Methods

Function and method decorators were introduced.Class decorators were introduced inPEP 3129.

8.8.Class definitions

A class definition defines a class object (see sectionThe standard type hierarchy):

classdef    ::= [decorators] "class"classname [type_params] [inheritance] ":"suiteinheritance ::= "(" [argument_list] ")"classname   ::=identifier

A class definition is an executable statement. The inheritance list usuallygives a list of base classes (seeMetaclasses for more advanced uses), soeach item in the list should evaluate to a class object which allowssubclassing. Classes without an inheritance list inherit, by default, from thebase classobject; hence,

classFoo:pass

is equivalent to

classFoo(object):pass

The class’s suite is then executed in a new execution frame (seeNaming and binding),using a newly created local namespace and the original global namespace.(Usually, the suite contains mostly function definitions.) When the class’ssuite finishes execution, its execution frame is discarded but its localnamespace is saved.[5] A class object is then created using the inheritancelist for the base classes and the saved local namespace for the attributedictionary. The class name is bound to this class object in the original localnamespace.

The order in which attributes are defined in the class body is preservedin the new class’s__dict__. Note that this is reliable only rightafter the class is created and only for classes that were defined usingthe definition syntax.

Class creation can be customized heavily usingmetaclasses.

Classes can also be decorated: just like when decorating functions,

@f1(arg)@f2classFoo:pass

is roughly equivalent to

classFoo:passFoo=f1(arg)(f2(Foo))

The evaluation rules for the decorator expressions are the same as for functiondecorators. The result is then bound to the class name.

Changed in version 3.9:Classes may be decorated with any validassignment_expression. Previously, the grammar wasmuch more restrictive; seePEP 614 for details.

A list oftype parameters may be given in square bracketsimmediately after the class’s name.This indicates to static type checkers that the class is generic. At runtime,the type parameters can be retrieved from the class’s__type_params__ attribute. SeeGeneric classes for more.

Changed in version 3.12:Type parameter lists are new in Python 3.12.

Programmer’s note: Variables defined in the class definition are classattributes; they are shared by instances. Instance attributes can be set in amethod withself.name=value. Both class and instance attributes areaccessible through the notation “self.name”, and an instance attribute hidesa class attribute with the same name when accessed in this way. Classattributes can be used as defaults for instance attributes, but using mutablevalues there can lead to unexpected results.Descriptorscan be used to create instance variables with different implementation details.

See also

PEP 3115 - Metaclasses in Python 3000

The proposal that changed the declaration of metaclasses to the currentsyntax, and the semantics for how classes with metaclasses areconstructed.

PEP 3129 - Class Decorators

The proposal that added class decorators. Function and method decoratorswere introduced inPEP 318.

8.9.Coroutines

Added in version 3.5.

8.9.1.Coroutine function definition

async_funcdef ::= [decorators] "async" "def"funcname "(" [parameter_list] ")"                  ["->"expression] ":"suite

Execution of Python coroutines can be suspended and resumed at many points(seecoroutine).await expressions,asyncfor andasyncwith can only be used in the body of a coroutine function.

Functions defined withasyncdef syntax are always coroutine functions,even if they do not containawait orasync keywords.

It is aSyntaxError to use ayieldfrom expression inside the bodyof a coroutine function.

An example of a coroutine function:

asyncdeffunc(param1,param2):do_stuff()awaitsome_coroutine()

Changed in version 3.7:await andasync are now keywords; previously they were onlytreated as such inside the body of a coroutine function.

8.9.2.Theasyncfor statement

async_for_stmt ::= "async"for_stmt

Anasynchronous iterable provides an__aiter__ method that directlyreturns anasynchronous iterator, which can call asynchronous code inits__anext__ method.

Theasyncfor statement allows convenient iteration over asynchronousiterables.

The following code:

asyncforTARGETinITER:SUITEelse:SUITE2

Is semantically equivalent to:

iter=(ITER)iter=type(iter).__aiter__(iter)running=Truewhilerunning:try:TARGET=awaittype(iter).__anext__(iter)exceptStopAsyncIteration:running=Falseelse:SUITEelse:SUITE2

See also__aiter__() and__anext__() for details.

It is aSyntaxError to use anasyncfor statement outside thebody of a coroutine function.

8.9.3.Theasyncwith statement

async_with_stmt ::= "async"with_stmt

Anasynchronous context manager is acontext manager that isable to suspend execution in itsenter andexit methods.

The following code:

asyncwithEXPRESSIONasTARGET:SUITE

is semantically equivalent to:

manager=(EXPRESSION)aenter=type(manager).__aenter__aexit=type(manager).__aexit__value=awaitaenter(manager)hit_except=Falsetry:TARGET=valueSUITEexcept:hit_except=Trueifnotawaitaexit(manager,*sys.exc_info()):raisefinally:ifnothit_except:awaitaexit(manager,None,None,None)

See also__aenter__() and__aexit__() for details.

It is aSyntaxError to use anasyncwith statement outside thebody of a coroutine function.

See also

PEP 492 - Coroutines with async and await syntax

The proposal that made coroutines a proper standalone concept in Python,and added supporting syntax.

8.10.Type parameter lists

Added in version 3.12.

Changed in version 3.13:Support for default values was added (seePEP 696).

type_params  ::= "["type_param (","type_param)* "]"type_param   ::=typevar |typevartuple |paramspectypevar      ::=identifier (":"expression)? ("="expression)?typevartuple ::= "*"identifier ("="expression)?paramspec    ::= "**"identifier ("="expression)?

Functions (includingcoroutines),classes andtype aliases maycontain a type parameter list:

defmax[T](args:list[T])->T:...asyncdefamax[T](args:list[T])->T:...classBag[T]:def__iter__(self)->Iterator[T]:...defadd(self,arg:T)->None:...typeListOrSet[T]=list[T]|set[T]

Semantically, this indicates that the function, class, or type alias isgeneric over a type variable. This information is primarily used by statictype checkers, and at runtime, generic objects behave much like theirnon-generic counterparts.

Type parameters are declared in square brackets ([]) immediatelyafter the name of the function, class, or type alias. The type parametersare accessible within the scope of the generic object, but not elsewhere.Thus, after a declarationdeffunc[T]():pass, the nameT is not available inthe module scope. Below, the semantics of generic objects are describedwith more precision. The scope of type parameters is modeled with a specialfunction (technically, anannotation scope) thatwraps the creation of the generic object.

Generic functions, classes, and type aliases have a__type_params__ attribute listing their type parameters.

Type parameters come in three kinds:

  • typing.TypeVar, introduced by a plain name (e.g.,T). Semantically, thisrepresents a single type to a type checker.

  • typing.TypeVarTuple, introduced by a name prefixed with a singleasterisk (e.g.,*Ts). Semantically, this stands for a tuple of anynumber of types.

  • typing.ParamSpec, introduced by a name prefixed with two asterisks(e.g.,**P). Semantically, this stands for the parameters of a callable.

typing.TypeVar declarations can definebounds andconstraints witha colon (:) followed by an expression. A single expression after the colonindicates a bound (e.g.T:int). Semantically, this meansthat thetyping.TypeVar can only represent types that are a subtype ofthis bound. A parenthesized tuple of expressions after the colon indicates aset of constraints (e.g.T:(str,bytes)). Each member of the tuple should be atype (again, this is not enforced at runtime). Constrained type variables can onlytake on one of the types in the list of constraints.

Fortyping.TypeVars declared using the type parameter list syntax,the bound and constraints are not evaluated when the generic object is created,but only when the value is explicitly accessed through the attributes__bound__and__constraints__. To accomplish this, the bounds or constraints areevaluated in a separateannotation scope.

typing.TypeVarTuples andtyping.ParamSpecs cannot have boundsor constraints.

All three flavors of type parameters can also have adefault value, which is usedwhen the type parameter is not explicitly provided. This is added by appendinga single equals sign (=) followed by an expression. Like the bounds andconstraints of type variables, the default value is not evaluated when theobject is created, but only when the type parameter’s__default__ attributeis accessed. To this end, the default value is evaluated in a separateannotation scope. If no default value is specifiedfor a type parameter, the__default__ attribute is set to the specialsentinel objecttyping.NoDefault.

The following example indicates the full set of allowed type parameter declarations:

defoverly_generic[SimpleTypeVar,TypeVarWithDefault=int,TypeVarWithBound:int,TypeVarWithConstraints:(str,bytes),*SimpleTypeVarTuple=(int,float),**SimpleParamSpec=(str,bytearray),](a:SimpleTypeVar,b:TypeVarWithDefault,c:TypeVarWithBound,d:Callable[SimpleParamSpec,TypeVarWithConstraints],*e:SimpleTypeVarTuple,):...

8.10.1.Generic functions

Generic functions are declared as follows:

deffunc[T](arg:T):...

This syntax is equivalent to:

annotation-defTYPE_PARAMS_OF_func():T=typing.TypeVar("T")deffunc(arg:T):...func.__type_params__=(T,)returnfuncfunc=TYPE_PARAMS_OF_func()

Hereannotation-def indicates anannotation scope,which is not actually bound to any name at runtime. (Oneother liberty is taken in the translation: the syntax does not go throughattribute access on thetyping module, but creates an instance oftyping.TypeVar directly.)

The annotations of generic functions are evaluated within the annotation scopeused for declaring the type parameters, but the function’s defaults anddecorators are not.

The following example illustrates the scoping rules for these cases,as well as for additional flavors of type parameters:

@decoratordeffunc[T:int,*Ts,**P](*args:*Ts,arg:Callable[P,T]=some_default):...

Except for thelazy evaluation of theTypeVar bound, this is equivalent to:

DEFAULT_OF_arg=some_defaultannotation-defTYPE_PARAMS_OF_func():annotation-defBOUND_OF_T():returnint# In reality, BOUND_OF_T() is evaluated only on demand.T=typing.TypeVar("T",bound=BOUND_OF_T())Ts=typing.TypeVarTuple("Ts")P=typing.ParamSpec("P")deffunc(*args:*Ts,arg:Callable[P,T]=DEFAULT_OF_arg):...func.__type_params__=(T,Ts,P)returnfuncfunc=decorator(TYPE_PARAMS_OF_func())

The capitalized names likeDEFAULT_OF_arg are not actuallybound at runtime.

8.10.2.Generic classes

Generic classes are declared as follows:

classBag[T]:...

This syntax is equivalent to:

annotation-defTYPE_PARAMS_OF_Bag():T=typing.TypeVar("T")classBag(typing.Generic[T]):__type_params__=(T,)...returnBagBag=TYPE_PARAMS_OF_Bag()

Here againannotation-def (not a real keyword) indicates anannotation scope, and the nameTYPE_PARAMS_OF_Bag is not actually bound at runtime.

Generic classes implicitly inherit fromtyping.Generic.The base classes and keyword arguments of generic classes areevaluated within the type scope for the type parameters,and decorators are evaluated outside that scope. This is illustratedby this example:

@decoratorclassBag(Base[T],arg=T):...

This is equivalent to:

annotation-defTYPE_PARAMS_OF_Bag():T=typing.TypeVar("T")classBag(Base[T],typing.Generic[T],arg=T):__type_params__=(T,)...returnBagBag=decorator(TYPE_PARAMS_OF_Bag())

8.10.3.Generic type aliases

Thetype statement can also be used to create a generic type alias:

typeListOrSet[T]=list[T]|set[T]

Except for thelazy evaluation of the value,this is equivalent to:

annotation-defTYPE_PARAMS_OF_ListOrSet():T=typing.TypeVar("T")annotation-defVALUE_OF_ListOrSet():returnlist[T]|set[T]# In reality, the value is lazily evaluatedreturntyping.TypeAliasType("ListOrSet",VALUE_OF_ListOrSet(),type_params=(T,))ListOrSet=TYPE_PARAMS_OF_ListOrSet()

Here,annotation-def (not a real keyword) indicates anannotation scope. The capitalized nameslikeTYPE_PARAMS_OF_ListOrSet are not actually bound at runtime.

Footnotes

[1]

The exception is propagated to the invocation stack unlessthere is afinally clause which happens to raise anotherexception. That new exception causes the old one to be lost.

[2]

In pattern matching, a sequence is defined as one of the following:

The following standard library classes are sequences:

Note

Subject values of typestr,bytes, andbytearraydo not match sequence patterns.

[3]

In pattern matching, a mapping is defined as one of the following:

The standard library classesdict andtypes.MappingProxyTypeare mappings.

[4]

A string literal appearing as the first statement in the function body istransformed into the function’s__doc__ attribute andtherefore the function’sdocstring.

[5]

A string literal appearing as the first statement in the class body istransformed into the namespace’s__doc__ item and thereforethe class’sdocstring.