Newer
Older
' Lexicographical comparison between built-in collections '
'works as\n'
' follows:\n'
'\n'
' * For two collections to compare equal, they must be of the '
'same\n'
' type, have the same length, and each pair of '
'corresponding\n'
' elements must compare equal (for example, "[1,2] == '
'(1,2)" is\n'
' false because the type is not the same).\n'
'\n'
' * Collections that support order comparison are ordered the '
'same as\n'
' their first unequal elements (for example, "[1,2,x] <= '
'[1,2,y]"\n'
' has the same value as "x <= y"). If a corresponding '
'element does\n'
' not exist, the shorter collection is ordered first (for '
'example,\n'
' "[1,2] < [1,2,3]" is true).\n'
'\n'
'* Mappings (instances of "dict") compare equal if and only if '
'they\n'
' have equal *(key, value)* pairs. Equality comparison of the '
'keys and\n'
' values enforces reflexivity.\n'
'\n'
' Order comparisons ("<", ">", "<=", and ">=") raise '
'"TypeError".\n'
'\n'
'* Sets (instances of "set" or "frozenset") can be compared '
'\n'
' They define order comparison operators to mean subset and '
'superset\n'
' tests. Those relations do not define total orderings (for '
'example,\n'
' the two sets "{1,2}" and "{2,3}" are not equal, nor subsets '
'of one\n'
' another, nor supersets of one another). Accordingly, sets '
'are not\n'
' appropriate arguments for functions which depend on total '
'ordering\n'
' (for example, "min()", "max()", and "sorted()" produce '
'undefined\n'
' results given a list of sets as inputs).\n'
'\n'
' Comparison of sets enforces reflexivity of its elements.\n'
'\n'
'* Most other built-in types have no comparison methods '
'implemented, so\n'
' they inherit the default comparison behavior.\n'
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
'\n'
'User-defined classes that customize their comparison behavior '
'should\n'
'follow some consistency rules, if possible:\n'
'\n'
'* Equality comparison should be reflexive. In other words, '
'identical\n'
' objects should compare equal:\n'
'\n'
' "x is y" implies "x == y"\n'
'\n'
'* Comparison should be symmetric. In other words, the '
'following\n'
' expressions should have the same result:\n'
'\n'
' "x == y" and "y == x"\n'
'\n'
' "x != y" and "y != x"\n'
'\n'
' "x < y" and "y > x"\n'
'\n'
' "x <= y" and "y >= x"\n'
'\n'
'* Comparison should be transitive. The following '
'(non-exhaustive)\n'
' examples illustrate that:\n'
'\n'
' "x > y and y > z" implies "x > z"\n'
'\n'
' "x < y and y <= z" implies "x < z"\n'
'\n'
'* Inverse comparison should result in the boolean negation. '
'In other\n'
' words, the following expressions should have the same '
'result:\n'
'\n'
' "x == y" and "not x != y"\n'
'\n'
' "x < y" and "not x >= y" (for total ordering)\n'
'\n'
' "x > y" and "not x <= y" (for total ordering)\n'
'\n'
' The last two expressions apply to totally ordered '
'collections (e.g.\n'
' to sequences, but not to sets or mappings). See also the\n'
' "total_ordering()" decorator.\n'
'\n'
'* The "hash()" result should be consistent with equality. '
'Objects that\n'
' are equal should either have the same hash value, or be '
'marked as\n'
' unhashable.\n'
'Python does not enforce these consistency rules. In fact, '
'the\n'
'not-a-number values are an example for not following these '
'rules.\n'
'\n'
'\n'
'Membership test operations\n'
'==========================\n'
'\n'
'The operators "in" and "not in" test for membership. "x in '
's"\n'
'evaluates to "True" if *x* is a member of *s*, and "False" '
'otherwise.\n'
'"x not in s" returns the negation of "x in s". All built-in '
'sequences\n'
'and set types support this as well as dictionary, for which '
'"in" tests\n'
'whether the dictionary has a given key. For container types '
'such as\n'
'list, tuple, set, frozenset, dict, or collections.deque, the\n'
'expression "x in y" is equivalent to "any(x is e or x == e '
'for e in\n'
'y)".\n'
'\n'
'For the string and bytes types, "x in y" is "True" if and '
'only if *x*\n'
'is a substring of *y*. An equivalent test is "y.find(x) != '
'-1".\n'
'Empty strings are always considered to be a substring of any '
'other\n'
'string, so """ in "abc"" will return "True".\n'
'\n'
'For user-defined classes which define the "__contains__()" '
'method, "x\n'
'in y" returns "True" if "y.__contains__(x)" returns a true '
'value, and\n'
'"False" otherwise.\n'
'\n'
'For user-defined classes which do not define "__contains__()" '
'but do\n'
'define "__iter__()", "x in y" is "True" if some value "z", '
'for which\n'
'the expression "x is z or x == z" is true, is produced while '
'iterating\n'
'over "y". If an exception is raised during the iteration, it '
'is as if\n'
'"in" raised that exception.\n'
'\n'
'Lastly, the old-style iteration protocol is tried: if a class '
'defines\n'
'"__getitem__()", "x in y" is "True" if and only if there is a '
'negative integer index *i* such that "x is y[i] or x == '
'y[i]", and no\n'
'lower integer index raises the "IndexError" exception. (If '
'any other\n'
'exception is raised, it is as if "in" raised that '
'exception).\n'
'\n'
'The operator "not in" is defined to have the inverse truth '
'value of\n'
'"in".\n'
'\n'
'\n'
'Identity comparisons\n'
'====================\n'
'\n'
'The operators "is" and "is not" test for an object’s '
'identity: "x is\n'
'y" is true if and only if *x* and *y* are the same object. '
'An\n'
'Object’s identity is determined using the "id()" function. '
'"x is not\n'
'y" yields the inverse truth value. [4]\n',
'compound': 'Compound statements\n'
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
'*******************\n'
'\n'
'Compound statements contain (groups of) other statements; they '
'affect\n'
'or control the execution of those other statements in some way. '
'In\n'
'general, compound statements span multiple lines, although in '
'simple\n'
'incarnations a whole compound statement may be contained in one '
'line.\n'
'\n'
'The "if", "while" and "for" statements implement traditional '
'control\n'
'flow constructs. "try" specifies exception handlers and/or '
'cleanup\n'
'code for a group of statements, while the "with" statement '
'allows the\n'
'execution of initialization and finalization code around a block '
'of\n'
'code. Function and class definitions are also syntactically '
'compound\n'
'statements.\n'
'\n'
'A compound statement consists of one or more ‘clauses.’ A '
'consists of a header and a ‘suite.’ The clause headers of a\n'
'particular compound statement are all at the same indentation '
'level.\n'
'Each clause header begins with a uniquely identifying keyword '
'and ends\n'
'with a colon. A suite is a group of statements controlled by a\n'
'clause. A suite can be one or more semicolon-separated simple\n'
'statements on the same line as the header, following the '
'colon, or it can be one or more indented statements on '
'subsequent\n'
'lines. Only the latter form of a suite can contain nested '
'compound\n'
'statements; the following is illegal, mostly because it wouldn’t '
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
'be\n'
'clear to which "if" clause a following "else" clause would '
'belong:\n'
'\n'
' if test1: if test2: print(x)\n'
'\n'
'Also note that the semicolon binds tighter than the colon in '
'this\n'
'context, so that in the following example, either all or none of '
'the\n'
'"print()" calls are executed:\n'
'\n'
' if x < y < z: print(x); print(y); print(z)\n'
'\n'
'Summarizing:\n'
'\n'
' compound_stmt ::= if_stmt\n'
' | while_stmt\n'
' | for_stmt\n'
' | try_stmt\n'
' | with_stmt\n'
' | funcdef\n'
' | classdef\n'
' | async_with_stmt\n'
' | async_for_stmt\n'
' | async_funcdef\n'
' suite ::= stmt_list NEWLINE | NEWLINE INDENT '
'statement+ DEDENT\n'
' statement ::= stmt_list NEWLINE | compound_stmt\n'
' stmt_list ::= simple_stmt (";" simple_stmt)* [";"]\n'
'\n'
'Note that statements always end in a "NEWLINE" possibly followed '
'by a\n'
'"DEDENT". Also note that optional continuation clauses always '
'begin\n'
'with a keyword that cannot start a statement, thus there are no\n'
'ambiguities (the ‘dangling "else"’ problem is solved in Python '
'by\n'
'requiring nested "if" statements to be indented).\n'
'\n'
'The formatting of the grammar rules in the following sections '
'places\n'
'each clause on a separate line for clarity.\n'
'\n'
'\n'
'The "if" statement\n'
'==================\n'
'\n'
'The "if" statement is used for conditional execution:\n'
'\n'
' if_stmt ::= "if" assignment_expression ":" suite\n'
' ("elif" assignment_expression ":" suite)*\n'
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
' ["else" ":" suite]\n'
'\n'
'It selects exactly one of the suites by evaluating the '
'expressions one\n'
'by one until one is found to be true (see section Boolean '
'operations\n'
'for the definition of true and false); then that suite is '
'executed\n'
'(and no other part of the "if" statement is executed or '
'evaluated).\n'
'If all expressions are false, the suite of the "else" clause, '
'if\n'
'present, is executed.\n'
'\n'
'\n'
'The "while" statement\n'
'=====================\n'
'\n'
'The "while" statement is used for repeated execution as long as '
'an\n'
'expression is true:\n'
'\n'
' while_stmt ::= "while" assignment_expression ":" suite\n'
' ["else" ":" suite]\n'
'\n'
'This repeatedly tests the expression and, if it is true, '
'executes the\n'
'first suite; if the expression is false (which may be the first '
'time\n'
'it is tested) the suite of the "else" clause, if present, is '
'executed\n'
'and the loop terminates.\n'
'\n'
'A "break" statement executed in the first suite terminates the '
'loop\n'
'without executing the "else" clause’s suite. A "continue" '
'statement\n'
'executed in the first suite skips the rest of the suite and goes '
'back\n'
'to testing the expression.\n'
'\n'
'\n'
'The "for" statement\n'
'===================\n'
'\n'
'The "for" statement is used to iterate over the elements of a '
'sequence\n'
'(such as a string, tuple or list) or other iterable object:\n'
'\n'
' for_stmt ::= "for" target_list "in" starred_list ":" suite\n'
'The "starred_list" expression is evaluated once; it should yield '
'an\n'
'*iterable* object. An *iterator* is created for that iterable. '
'The\n'
'first item provided by the iterator is then assigned to the '
'target\n'
'list using the standard rules for assignments (see Assignment\n'
'statements), and the suite is executed. This repeats for each '
'item\n'
'provided by the iterator. When the iterator is exhausted, the '
'suite\n'
'in the "else" clause, if present, is executed, and the loop\n'
'terminates.\n'
'\n'
'A "break" statement executed in the first suite terminates the '
'loop\n'
'without executing the "else" clause’s suite. A "continue" '
'statement\n'
'executed in the first suite skips the rest of the suite and '
'continues\n'
'with the next item, or with the "else" clause if there is no '
'next\n'
'item.\n'
'\n'
'The for-loop makes assignments to the variables in the target '
'list.\n'
'This overwrites all previous assignments to those variables '
'including\n'
'those made in the suite of the for-loop:\n'
'\n'
' for i in range(10):\n'
' print(i)\n'
' i = 5 # this will not affect the for-loop\n'
' # because i will be overwritten with '
'the next\n'
' # index in the range\n'
'\n'
'Names in the target list are not deleted when the loop is '
'finished,\n'
'but if the sequence is empty, they will not have been assigned '
'to at\n'
'all by the loop. Hint: the built-in function "range()" returns '
'an\n'
'iterator of integers suitable to emulate the effect of Pascal’s '
'"for i\n'
':= a to b do"; e.g., "list(range(3))" returns the list "[0, 1, '
'2]".\n'
'\n'
'Changed in version 3.11: Starred elements are now allowed in '
'the\n'
'expression list.\n'
'\n'
'\n'
'The "try" statement\n'
'===================\n'
'\n'
'The "try" statement specifies exception handlers and/or cleanup '
'code\n'
'for a group of statements:\n'
'\n'
' try1_stmt ::= "try" ":" suite\n'
' ("except" [expression ["as" identifier]] ":" '
'suite)+\n'
' ["else" ":" suite]\n'
' ["finally" ":" suite]\n'
' try2_stmt ::= "try" ":" suite\n'
' ("except" "*" expression ["as" identifier] ":" '
'suite)+\n'
' ["else" ":" suite]\n'
' ["finally" ":" suite]\n'
' try3_stmt ::= "try" ":" suite\n'
' "finally" ":" suite\n'
'\n'
'The "except" clause(s) specify one or more exception handlers. '
'When no\n'
'exception occurs in the "try" clause, no exception handler is\n'
'executed. When an exception occurs in the "try" suite, a search '
'for an\n'
'exception handler is started. This search inspects the except '
'clauses\n'
'in turn until one is found that matches the exception. An '
'expression-\n'
'less except clause, if present, must be last; it matches any\n'
'exception. For an except clause with an expression, that '
'expression\n'
'is evaluated, and the clause matches the exception if the '
'resulting\n'
'object is “compatible” with the exception. An object is '
'with an exception if the object is the class or a *non-virtual '
'base\n'
'class* of the exception object, or a tuple containing an item '
'that is\n'
'the class or a non-virtual base class of the exception object.\n'
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
'\n'
'If no except clause matches the exception, the search for an '
'exception\n'
'handler continues in the surrounding code and on the invocation '
'stack.\n'
'[1]\n'
'\n'
'If the evaluation of an expression in the header of an except '
'clause\n'
'raises an exception, the original search for a handler is '
'canceled and\n'
'a search starts for the new exception in the surrounding code '
'and on\n'
'the call stack (it is treated as if the entire "try" statement '
'raised\n'
'the exception).\n'
'\n'
'When a matching except clause is found, the exception is '
'assigned to\n'
'the target specified after the "as" keyword in that except '
'clause, if\n'
'present, and the except clause’s suite is executed. All except\n'
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
'clauses must have an executable block. When the end of this '
'block is\n'
'reached, execution continues normally after the entire try '
'statement.\n'
'(This means that if two nested handlers exist for the same '
'exception,\n'
'and the exception occurs in the try clause of the inner handler, '
'the\n'
'outer handler will not handle the exception.)\n'
'\n'
'When an exception has been assigned using "as target", it is '
'cleared\n'
'at the end of the except clause. This is as if\n'
'\n'
' except E as N:\n'
' foo\n'
'\n'
'was translated to\n'
'\n'
' except E as N:\n'
' try:\n'
' foo\n'
' finally:\n'
' del N\n'
'\n'
'This means the exception must be assigned to a different name to '
'be\n'
'able to refer to it after the except clause. Exceptions are '
'cleared\n'
'because with the traceback attached to them, they form a '
'reference\n'
'cycle with the stack frame, keeping all locals in that frame '
'alive\n'
'until the next garbage collection occurs.\n'
'\n'
'Before an except clause’s suite is executed, details about the\n'
'exception are stored in the "sys" module and can be accessed '
'via\n'
'"sys.exc_info()". "sys.exc_info()" returns a 3-tuple consisting '
'of the\n'
'exception class, the exception instance and a traceback object '
'(see\n'
'section The standard type hierarchy) identifying the point in '
'the\n'
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
'program where the exception occurred. The details about the '
'exception\n'
'accessed via "sys.exc_info()" are restored to their previous '
'values\n'
'when leaving an exception handler:\n'
'\n'
' >>> print(sys.exc_info())\n'
' (None, None, None)\n'
' >>> try:\n'
' ... raise TypeError\n'
' ... except:\n'
' ... print(sys.exc_info())\n'
' ... try:\n'
' ... raise ValueError\n'
' ... except:\n'
' ... print(sys.exc_info())\n'
' ... print(sys.exc_info())\n'
' ...\n'
" (<class 'TypeError'>, TypeError(), <traceback object at "
'0x10efad080>)\n'
" (<class 'ValueError'>, ValueError(), <traceback object at "
'0x10efad040>)\n'
" (<class 'TypeError'>, TypeError(), <traceback object at "
'0x10efad080>)\n'
' >>> print(sys.exc_info())\n'
' (None, None, None)\n'
'The "except*" clause(s) are used for handling "ExceptionGroup"s. '
'exception type for matching is interpreted as in the case of '
'"except",\n'
'but in the case of exception groups we can have partial matches '
'when\n'
'the type matches some of the exceptions in the group. This means '
'multiple except* clauses can execute, each handling part of the\n'
'exception group. Each clause executes once and handles an '
'exception\n'
'group of all matching exceptions. Each exception in the group '
'is\n'
'handled by at most one except* clause, the first that matches '
'it.\n'
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
'\n'
' >>> try:\n'
' ... raise ExceptionGroup("eg",\n'
' ... [ValueError(1), TypeError(2), OSError(3), '
'OSError(4)])\n'
' ... except* TypeError as e:\n'
" ... print(f'caught {type(e)} with nested "
"{e.exceptions}')\n"
' ... except* OSError as e:\n'
" ... print(f'caught {type(e)} with nested "
"{e.exceptions}')\n"
' ...\n'
" caught <class 'ExceptionGroup'> with nested (TypeError(2),)\n"
" caught <class 'ExceptionGroup'> with nested (OSError(3), "
'OSError(4))\n'
' + Exception Group Traceback (most recent call last):\n'
' | File "<stdin>", line 2, in <module>\n'
' | ExceptionGroup: eg\n'
' +-+---------------- 1 ----------------\n'
' | ValueError: 1\n'
' +------------------------------------\n'
' >>>\n'
'\n'
' Any remaining exceptions that were not handled by any except* '
'clause\n'
' are re-raised at the end, combined into an exception group '
'along with\n'
' all exceptions that were raised from within except* clauses.\n'
'\n'
' An except* clause must have a matching type, and this type '
'cannot be a\n'
' subclass of :exc:`BaseExceptionGroup`. It is not possible to '
'mix except\n'
' and except* in the same :keyword:`try`. :keyword:`break`,\n'
' :keyword:`continue` and :keyword:`return` cannot appear in an '
'except*\n'
' clause.\n'
'\n'
'The optional "else" clause is executed if the control flow '
'leaves the\n'
'"try" suite, no exception was raised, and no "return", '
'"continue", or\n'
'"break" statement was executed. Exceptions in the "else" clause '
'are\n'
'not handled by the preceding "except" clauses.\n'
'\n'
'If "finally" is present, it specifies a ‘cleanup’ handler. The '
'"try"\n'
'clause is executed, including any "except" and "else" clauses. '
'If an\n'
'exception occurs in any of the clauses and is not handled, the\n'
'exception is temporarily saved. The "finally" clause is '
'executed. If\n'
'there is a saved exception it is re-raised at the end of the '
'"finally"\n'
'clause. If the "finally" clause raises another exception, the '
'saved\n'
'exception is set as the context of the new exception. If the '
'"finally"\n'
'clause executes a "return", "break" or "continue" statement, the '
'saved\n'
'exception is discarded:\n'
'\n'
' >>> def f():\n'
' ... try:\n'
' ... 1/0\n'
' ... finally:\n'
' ... return 42\n'
' ...\n'
' >>> f()\n'
' 42\n'
'\n'
'The exception information is not available to the program '
'during\n'
'execution of the "finally" clause.\n'
'\n'
'When a "return", "break" or "continue" statement is executed in '
'the\n'
'"try" suite of a "try"…"finally" statement, the "finally" clause '
'is\n'
'also executed ‘on the way out.’\n'
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
'\n'
'The return value of a function is determined by the last '
'"return"\n'
'statement executed. Since the "finally" clause always executes, '
'a\n'
'"return" statement executed in the "finally" clause will always '
'be the\n'
'last one executed:\n'
'\n'
' >>> def foo():\n'
' ... try:\n'
" ... return 'try'\n"
' ... finally:\n'
" ... return 'finally'\n"
' ...\n'
' >>> foo()\n'
" 'finally'\n"
'\n'
'Additional information on exceptions can be found in section\n'
'Exceptions, and information on using the "raise" statement to '
'generate\n'
'exceptions may be found in section The raise statement.\n'
'\n'
'Changed in version 3.8: Prior to Python 3.8, a "continue" '
'statement\n'
'was illegal in the "finally" clause due to a problem with the\n'
'implementation.\n'
'\n'
'\n'
'The "with" statement\n'
'====================\n'
'\n'
'The "with" statement is used to wrap the execution of a block '
'with\n'
'methods defined by a context manager (see section With '
'Statement\n'
'Context Managers). This allows common "try"…"except"…"finally" '
'usage\n'
'patterns to be encapsulated for convenient reuse.\n'
' with_stmt ::= "with" ( "(" with_stmt_contents ","? '
'")" | with_stmt_contents ) ":" suite\n'
' with_stmt_contents ::= with_item ("," with_item)*\n'
' with_item ::= expression ["as" target]\n'
'The execution of the "with" statement with one “item” proceeds '
'as\n'
'follows:\n'
'\n'
'1. The context expression (the expression given in the '
'"with_item") is\n'
' evaluated to obtain a context manager.\n'
'2. The context manager’s "__enter__()" is loaded for later use.\n'
'3. The context manager’s "__exit__()" is loaded for later use.\n'
'4. The context manager’s "__enter__()" method is invoked.\n'
'\n'
'5. If a target was included in the "with" statement, the return '
'value\n'
' from "__enter__()" is assigned to it.\n'
'\n'
' Note:\n'
' The "with" statement guarantees that if the "__enter__()" '
'method\n'
' returns without an error, then "__exit__()" will always be\n'
' called. Thus, if an error occurs during the assignment to '
'the\n'
' target list, it will be treated the same as an error '
'occurring\n'
' within the suite would be. See step 6 below.\n'
'\n'
'7. The context manager’s "__exit__()" method is invoked. If an\n'
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
' exception caused the suite to be exited, its type, value, '
'and\n'
' traceback are passed as arguments to "__exit__()". Otherwise, '
'three\n'
' "None" arguments are supplied.\n'
'\n'
' If the suite was exited due to an exception, and the return '
'value\n'
' from the "__exit__()" method was false, the exception is '
'reraised.\n'
' If the return value was true, the exception is suppressed, '
'and\n'
' execution continues with the statement following the "with"\n'
' statement.\n'
'\n'
' If the suite was exited for any reason other than an '
'exception, the\n'
' return value from "__exit__()" is ignored, and execution '
'proceeds\n'
' at the normal location for the kind of exit that was taken.\n'
'\n'
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
'The following code:\n'
'\n'
' with EXPRESSION as TARGET:\n'
' SUITE\n'
'\n'
'is semantically equivalent to:\n'
'\n'
' manager = (EXPRESSION)\n'
' enter = type(manager).__enter__\n'
' exit = type(manager).__exit__\n'
' value = enter(manager)\n'
' hit_except = False\n'
'\n'
' try:\n'
' TARGET = value\n'
' SUITE\n'
' except:\n'
' hit_except = True\n'
' if not exit(manager, *sys.exc_info()):\n'
' raise\n'
' finally:\n'
' if not hit_except:\n'
' exit(manager, None, None, None)\n'
'\n'
'With more than one item, the context managers are processed as '
'if\n'
'multiple "with" statements were nested:\n'
'\n'
' with A() as a, B() as b:\n'
'\n'
' with A() as a:\n'
' with B() as b:\n'
'You can also write multi-item context managers in multiple lines '
'if\n'
'the items are surrounded by parentheses. For example:\n'
'\n'
' with (\n'
' A() as a,\n'
' B() as b,\n'
' ):\n'
' SUITE\n'
'\n'
'Changed in version 3.1: Support for multiple context '
'expressions.\n'
'\n'
'Changed in version 3.10: Support for using grouping parentheses '
'to\n'
'break the statement in multiple lines.\n'
'\n'
' **PEP 343** - The “with” statement\n'
' The specification, background, and examples for the Python '
'"with"\n'
' statement.\n'
'\n'
'\n'
'The "match" statement\n'
'=====================\n'
'\n'
'New in version 3.10.\n'
'\n'
'The match statement is used for pattern matching. Syntax:\n'
'\n'
' match_stmt ::= \'match\' subject_expr ":" NEWLINE INDENT '
'case_block+ DEDENT\n'
' subject_expr ::= star_named_expression "," '
'star_named_expressions?\n'
' | named_expression\n'
' case_block ::= \'case\' patterns [guard] ":" block\n'
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
'\n'
'Note:\n'
'\n'
' This section uses single quotes to denote soft keywords.\n'
'\n'
'Pattern matching takes a pattern as input (following "case") and '
'a\n'
'subject value (following "match"). The pattern (which may '
'contain\n'
'subpatterns) is matched against the subject value. The outcomes '
'are:\n'
'\n'
'* A match success or failure (also termed a pattern success or\n'
' failure).\n'
'\n'
'* Possible binding of matched values to a name. The '
'prerequisites for\n'
' this are further discussed below.\n'
'\n'
'The "match" and "case" keywords are soft keywords.\n'
'\n'
'See also:\n'
'\n'
' * **PEP 634** – Structural Pattern Matching: Specification\n'
'\n'
' * **PEP 636** – Structural Pattern Matching: Tutorial\n'
'\n'
'\n'
'Overview\n'
'--------\n'
'\n'
'Here’s an overview of the logical flow of a match statement:\n'
'\n'
'1. The subject expression "subject_expr" is evaluated and a '
'resulting\n'
' subject value obtained. If the subject expression contains a '
'comma,\n'
' a tuple is constructed using the standard rules.\n'
'\n'
'2. Each pattern in a "case_block" is attempted to match with '
'the\n'
' subject value. The specific rules for success or failure are\n'
' described below. The match attempt can also bind some or all '
'of the\n'
' standalone names within the pattern. The precise pattern '
'binding\n'
' rules vary per pattern type and are specified below. **Name\n'
' bindings made during a successful pattern match outlive the\n'
' executed block and can be used after the match statement**.\n'
'\n'
' Note:\n'
'\n'
' During failed pattern matches, some subpatterns may '
'succeed.\n'
' Do not rely on bindings being made for a failed match.\n'
' Conversely, do not rely on variables remaining unchanged '
'after\n'
' a failed match. The exact behavior is dependent on\n'
' implementation and may vary. This is an intentional '
'decision\n'
' made to allow different implementations to add '
'optimizations.\n'
'\n'
'3. If the pattern succeeds, the corresponding guard (if present) '
'is\n'
' evaluated. In this case all name bindings are guaranteed to '
'have\n'
' happened.\n'
'\n'
' * If the guard evaluates as true or is missing, the "block" '
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
'inside\n'
' "case_block" is executed.\n'
'\n'
' * Otherwise, the next "case_block" is attempted as described '
'above.\n'
'\n'
' * If there are no further case blocks, the match statement '
'is\n'
' completed.\n'
'\n'
'Note:\n'
'\n'
' Users should generally never rely on a pattern being '
'evaluated.\n'
' Depending on implementation, the interpreter may cache values '
'or use\n'
' other optimizations which skip repeated evaluations.\n'
'\n'
'A sample match statement:\n'
'\n'
' >>> flag = False\n'
' >>> match (100, 200):\n'
' ... case (100, 300): # Mismatch: 200 != 300\n'
" ... print('Case 1')\n"
' ... case (100, 200) if flag: # Successful match, but '
'guard fails\n'
" ... print('Case 2')\n"
' ... case (100, y): # Matches and binds y to 200\n'
" ... print(f'Case 3, y: {y}')\n"
' ... case _: # Pattern not attempted\n'
" ... print('Case 4, I match anything!')\n"
' ...\n'
' Case 3, y: 200\n'
'\n'
'In this case, "if flag" is a guard. Read more about that in the '
'next\n'
'section.\n'
'\n'
'\n'
'Guards\n'
'------\n'
'\n'
' guard ::= "if" named_expression\n'
'\n'
'A "guard" (which is part of the "case") must succeed for code '
'inside\n'
'the "case" block to execute. It takes the form: "if" followed '
'by an\n'
'expression.\n'
'\n'
'The logical flow of a "case" block with a "guard" follows:\n'
'\n'
'1. Check that the pattern in the "case" block succeeded. If '
'the\n'
' pattern failed, the "guard" is not evaluated and the next '
'"case"\n'
' block is checked.\n'
'\n'
'2. If the pattern succeeded, evaluate the "guard".\n'
'\n'
' * If the "guard" condition evaluates as true, the case block '
'is\n'
' * If the "guard" condition evaluates as false, the case block '
'is\n'
2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
2998
2999
3000
' not selected.\n'
'\n'
' * If the "guard" raises an exception during evaluation, the\n'
' exception bubbles up.\n'
'\n'
'Guards are allowed to have side effects as they are '
'expressions.\n'
'Guard evaluation must proceed from the first to the last case '
'block,\n'
'one at a time, skipping case blocks whose pattern(s) don’t all\n'
'succeed. (I.e., guard evaluation must happen in order.) Guard\n'
'evaluation must stop once a case block is selected.\n'
'\n'
'\n'
'Irrefutable Case Blocks\n'
'-----------------------\n'
'\n'
'An irrefutable case block is a match-all case block. A match\n'
'statement may have at most one irrefutable case block, and it '
'must be\n'
'last.\n'
'\n'
'A case block is considered irrefutable if it has no guard and '
'its\n'
'pattern is irrefutable. A pattern is considered irrefutable if '
'we can\n'
'prove from its syntax alone that it will always succeed. Only '
'the\n'
'following patterns are irrefutable:\n'
'\n'
'* AS Patterns whose left-hand side is irrefutable\n'
'\n'
'* OR Patterns containing at least one irrefutable pattern\n'
'\n'
'* Capture Patterns\n'
'\n'
'* Wildcard Patterns\n'
'\n'
'* parenthesized irrefutable patterns\n'
'\n'
'\n'
'Patterns\n'
'--------\n'
'\n'
'Note:\n'
'\n'
' This section uses grammar notations beyond standard EBNF:\n'
'\n'
' * the notation "SEP.RULE+" is shorthand for "RULE (SEP '
'RULE)*"\n'
'\n'
' * the notation "!RULE" is shorthand for a negative lookahead\n'
' assertion\n'
'\n'
'The top-level syntax for "patterns" is:\n'
'\n'
' patterns ::= open_sequence_pattern | pattern\n'
' pattern ::= as_pattern | or_pattern\n'
' closed_pattern ::= | literal_pattern\n'
' | capture_pattern\n'
' | wildcard_pattern\n'
' | value_pattern\n'
' | group_pattern\n'
' | sequence_pattern\n'
' | mapping_pattern\n'
' | class_pattern\n'
'\n'
'The descriptions below will include a description “in simple '
'terms” of\n'
'what a pattern does for illustration purposes (credits to '
'Raymond\n'
'Hettinger for a document that inspired most of the '
'descriptions). Note\n'
'that these descriptions are purely for illustration purposes and '
'**may\n'
'not** reflect the underlying implementation. Furthermore, they '
'do not\n'
'cover all valid forms.\n'
'\n'
'\n'
'OR Patterns\n'