Skip to content
Snippets Groups Projects
topics.py 669 KiB
Newer Older
  • Learn to ignore specific revisions
  •                 '* 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. '
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                    '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'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                    '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 '
    
                    'non-\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                    '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'
    
                 '*******************\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 '
    
                 'clause\n'
    
                 '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 '
    
                 'header’s\n'
    
                 '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 '
    
                 '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'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 '   if_stmt ::= "if" assignment_expression ":" suite\n'
                 '               ("elif" assignment_expression ":" suite)*\n'
    
                 '               ["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'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 '   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" expression_list ":" '
                 'suite\n'
                 '                ["else" ":" suite]\n'
                 '\n'
                 'The expression list is evaluated once; it should yield an '
                 'iterable\n'
                 'object.  An iterator is created for the result of the\n'
                 '"expression_list".  The suite is then executed once for each '
                 'item\n'
                 'provided by the iterator, in the order returned by the '
                 'iterator.  Each\n'
                 'item in turn is assigned to the target list using the standard '
                 'rules\n'
                 'for assignments (see Assignment statements), and then the suite '
                 'is\n'
                 'executed.  When the items are exhausted (which is immediately '
                 'when the\n'
                 'sequence is empty or an iterator raises a "StopIteration" '
                 'exception),\n'
                 'the suite 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'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 'Note:\n'
                 '\n'
                 '  There is a subtlety when the sequence is being modified by the '
                 'loop\n'
                 '  (this can only occur for mutable sequences, e.g. lists).  An\n'
    
                 '  internal counter is used to keep track of which item is used '
                 'next,\n'
                 '  and this is incremented on each iteration.  When this counter '
                 'has\n'
                 '  reached the length of the sequence the loop terminates.  This '
                 'means\n'
                 '  that if the suite deletes the current (or a previous) item '
                 'from the\n'
                 '  sequence, the next item will be skipped (since it gets the '
                 'index of\n'
                 '  the current item which has already been treated).  Likewise, '
                 'if the\n'
                 '  suite inserts an item in the sequence before the current item, '
                 'the\n'
                 '  current item will be treated again the next time through the '
                 'loop.\n'
                 '  This can lead to nasty bugs that can be avoided by making a\n'
                 '  temporary copy using a slice of the whole sequence, e.g.,\n'
                 '\n'
                 '     for x in a[:]:\n'
                 '         if x < 0: a.remove(x)\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'
                 '   try_stmt  ::= try1_stmt | try2_stmt\n'
                 '   try1_stmt ::= "try" ":" suite\n'
                 '                 ("except" [expression ["as" identifier]] ":" '
                 'suite)+\n'
                 '                 ["else" ":" suite]\n'
                 '                 ["finally" ":" suite]\n'
                 '   try2_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 '
    
                 'compatible\n'
                 'with an exception if it is the class or a base class of the '
                 'exception\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 'object, or a tuple containing an item that is the class or a '
                 'base\n'
                 'class of the exception object.\n'
    
                 '\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'
    
                 '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'
                 'program where the exception occurred.  "sys.exc_info()" values '
                 'are\n'
                 'restored to their previous values (before the call) when '
                 'returning\n'
                 'from a function that handled an exception.\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'
    
                 '\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'
    
                 '\n'
                 '   with_stmt ::= "with" with_item ("," with_item)* ":" suite\n'
                 '   with_item ::= expression ["as" target]\n'
                 '\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 '
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 '"with_item") is\n'
                 '   evaluated to obtain a context manager.\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 '2. The context manager’s "__enter__()" is loaded for later use.\n'
                 '\n'
                 '3. The context manager’s "__exit__()" is loaded for later use.\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 '4. The context manager’s "__enter__()" method is invoked.\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 '5. If a target was included in the "with" statement, the return '
                 'value\n'
                 '   from "__enter__()" is assigned to it.\n'
                 '\n'
                 '   Note:\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 '     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'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 '6. The suite is executed.\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 '7. The context manager’s "__exit__()" method is invoked.  If an\n'
    
                 '   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'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 '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'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 '       SUITE\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 'is semantically equivalent to:\n'
    
                 '\n'
                 '   with A() as a:\n'
                 '       with B() as b:\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 '           SUITE\n'
    
                 '\n'
                 'Changed in version 3.1: Support for multiple context '
                 'expressions.\n'
                 '\n'
                 'See also:\n'
                 '\n'
    
                 '  **PEP 343** - The “with” statement\n'
    
                 '     The specification, background, and examples for the Python '
                 '"with"\n'
                 '     statement.\n'
                 '\n'
                 '\n'
                 'Function definitions\n'
                 '====================\n'
                 '\n'
                 'A function definition defines a user-defined function object '
                 '(see\n'
                 'section The standard type hierarchy):\n'
                 '\n'
    
                 '   funcdef                   ::= [decorators] "def" funcname "(" '
    
                 '[parameter_list] ")"\n'
                 '               ["->" expression] ":" suite\n'
    
                 '   decorators                ::= decorator+\n'
                 '   decorator                 ::= "@" dotted_name ["(" '
    
                 '[argument_list [","]] ")"] NEWLINE\n'
    
                 '   dotted_name               ::= identifier ("." identifier)*\n'
                 '   parameter_list            ::= defparameter ("," '
                 'defparameter)* "," "/" ["," [parameter_list_no_posonly]]\n'
                 '                        | parameter_list_no_posonly\n'
                 '   parameter_list_no_posonly ::= defparameter ("," '
                 'defparameter)* ["," [parameter_list_starargs]]\n'
                 '                                 | parameter_list_starargs\n'
                 '   parameter_list_starargs   ::= "*" [parameter] ("," '
    
                 'defparameter)* ["," ["**" parameter [","]]]\n'
                 '                               | "**" parameter [","]\n'
    
                 '   parameter                 ::= identifier [":" expression]\n'
                 '   defparameter              ::= parameter ["=" expression]\n'
                 '   funcname                  ::= identifier\n'
    
                 '\n'
                 'A function definition is an executable statement.  Its execution '
                 'binds\n'
                 'the function name in the current local namespace to a function '
                 'object\n'
                 '(a wrapper around the executable code for the function).  This\n'
                 'function object contains a reference to the current global '
                 'namespace\n'
                 'as the global namespace to be used when the function is called.\n'
                 '\n'
                 'The function definition does not execute the function body; this '
                 'gets\n'
    
                 'executed only when the function is called. [2]\n'
    
                 '\n'
                 'A function definition may be wrapped by one or more *decorator*\n'
                 'expressions. Decorator expressions are evaluated when the '
                 'function is\n'
                 'defined, in the scope that contains the function definition.  '
                 'The\n'
                 'result must be a callable, which is invoked with the function '
                 'object\n'
                 'as the only argument. The returned value is bound to the '
                 'function name\n'
                 'instead of the function object.  Multiple decorators are applied '
                 'in\n'
                 'nested fashion. For example, the following code\n'
                 '\n'
                 '   @f1(arg)\n'
                 '   @f2\n'
                 '   def func(): pass\n'
                 '\n'
    
                 'is roughly equivalent to\n'
    
                 '\n'
                 '   def func(): pass\n'
                 '   func = f1(arg)(f2(func))\n'
                 '\n'
    
                 'except that the original function is not temporarily bound to '
                 'the name\n'
                 '"func".\n'
                 '\n'
    
                 'When one or more *parameters* have the form *parameter* "="\n'
    
                 '*expression*, the function is said to have “default parameter '
                 'values.”\n'
    
                 'For a parameter with a default value, the corresponding '
                 '*argument* may\n'
    
                 'be omitted from a call, in which case the parameter’s default '
    
                 'value is\n'
                 'substituted.  If a parameter has a default value, all following\n'
    
                 'parameters up until the “"*"” must also have a default value — '
                 'this is\n'
                 'a syntactic restriction that is not expressed by the grammar.\n'
    
                 '\n'
                 '**Default parameter values are evaluated from left to right when '
                 'the\n'
                 'function definition is executed.** This means that the '
                 'expression is\n'
                 'evaluated once, when the function is defined, and that the same '
    
                 '“pre-\n'
                 'computed” value is used for each call.  This is especially '
    
                 'important\n'
                 'to understand when a default parameter is a mutable object, such '
                 'as a\n'
                 'list or a dictionary: if the function modifies the object (e.g. '
                 'by\n'
                 'appending an item to a list), the default value is in effect '
                 'modified.\n'
                 'This is generally not what was intended.  A way around this is '
                 'to use\n'
                 '"None" as the default, and explicitly test for it in the body of '
                 'the\n'
                 'function, e.g.:\n'
                 '\n'
                 '   def whats_on_the_telly(penguin=None):\n'
                 '       if penguin is None:\n'
                 '           penguin = []\n'
                 '       penguin.append("property of the zoo")\n'
                 '       return penguin\n'
                 '\n'
                 'Function call semantics are described in more detail in section '
                 'Calls.\n'
                 'A function call always assigns values to all parameters '
                 'mentioned in\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 'the parameter list, either from positional arguments, from '
    
                 'keyword\n'
    
                 'arguments, or from default values.  If the form “"*identifier"” '
    
                 'is\n'
                 'present, it is initialized to a tuple receiving any excess '
                 'positional\n'
    
                 'parameters, defaulting to the empty tuple. If the form\n'
    
                 '“"**identifier"” is present, it is initialized to a new ordered\n'
    
                 'mapping receiving any excess keyword arguments, defaulting to a '
                 'new\n'
    
                 'empty mapping of the same type.  Parameters after “"*"” or\n'
                 '“"*identifier"” are keyword-only parameters and may only be '
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 'passed by\n'
                 'keyword arguments.  Parameters before “"/"” are positional-only\n'
                 'parameters and may only be passed by positional arguments.\n'
                 '\n'
                 'Changed in version 3.8: The "/" function parameter syntax may be '
                 'used\n'
                 'to indicate positional-only parameters. See **PEP 570** for '
                 'details.\n'
    
                 'Parameters may have an *annotation* of the form “": '
                 'expression"”\n'
                 'following the parameter name.  Any parameter may have an '
                 'annotation,\n'
                 'even those of the form "*identifier" or "**identifier".  '
                 'Functions may\n'
                 'have “return” annotation of the form “"-> expression"” after '
    
                 'parameter list.  These annotations can be any valid Python '
                 'expression.\n'
                 'The presence of annotations does not change the semantics of a\n'
                 'function.  The annotation values are available as values of a\n'
                 'dictionary keyed by the parameters’ names in the '
                 '"__annotations__"\n'
                 'attribute of the function object.  If the "annotations" import '
                 'from\n'
                 '"__future__" is used, annotations are preserved as strings at '
                 'runtime\n'
                 'which enables postponed evaluation.  Otherwise, they are '
                 'evaluated\n'
                 'when the function definition is executed.  In this case '
                 'annotations\n'
                 'may be evaluated in a different order than they appear in the '
                 'source\n'
                 'code.\n'
    
                 '\n'
                 'It is also possible to create anonymous functions (functions not '
                 'bound\n'
                 'to a name), for immediate use in expressions.  This uses lambda\n'
                 'expressions, described in section Lambdas.  Note that the '
                 'lambda\n'
                 'expression is merely a shorthand for a simplified function '
                 'definition;\n'
    
                 'a function defined in a “"def"” statement can be passed around '
    
                 'or\n'
                 'assigned to another name just like a function defined by a '
                 'lambda\n'
    
                 'expression.  The “"def"” form is actually more powerful since '
    
                 'it\n'
                 'allows the execution of multiple statements and annotations.\n'
                 '\n'
    
                 '**Programmer’s note:** Functions are first-class objects.  A '
                 '“"def"”\n'
    
                 'statement executed inside a function definition defines a local\n'
                 'function that can be returned or passed around.  Free variables '
                 'used\n'
                 'in the nested function can access the local variables of the '
                 'function\n'
                 'containing the def.  See section Naming and binding for '
                 'details.\n'
                 '\n'
                 'See also:\n'
                 '\n'
                 '  **PEP 3107** - Function Annotations\n'
                 '     The original specification for function annotations.\n'
                 '\n'
    
                 '  **PEP 484** - Type Hints\n'
                 '     Definition of a standard meaning for annotations: type '
                 'hints.\n'
                 '\n'
                 '  **PEP 526** - Syntax for Variable Annotations\n'
                 '     Ability to type hint variable declarations, including '
                 'class\n'
                 '     variables and instance variables\n'
                 '\n'
                 '  **PEP 563** - Postponed Evaluation of Annotations\n'
                 '     Support for forward references within annotations by '
                 'preserving\n'
                 '     annotations in a string form at runtime instead of eager\n'
                 '     evaluation.\n'
                 '\n'
    
                 '\n'
                 'Class definitions\n'
                 '=================\n'
                 '\n'
                 'A class definition defines a class object (see section The '
                 'standard\n'
                 'type hierarchy):\n'
                 '\n'
                 '   classdef    ::= [decorators] "class" classname [inheritance] '
                 '":" suite\n'
    
                 '   inheritance ::= "(" [argument_list] ")"\n'
    
                 '   classname   ::= identifier\n'
                 '\n'
                 'A class definition is an executable statement.  The inheritance '
                 'list\n'
    
                 'usually gives a list of base classes (see Metaclasses for more\n'
                 'advanced uses), so each item in the list should evaluate to a '
                 'class\n'
                 'object which allows subclassing.  Classes without an inheritance '
                 'list\n'
                 'inherit, by default, from the base class "object"; hence,\n'
    
                 '\n'
                 '   class Foo:\n'
                 '       pass\n'
                 '\n'
                 'is equivalent to\n'
                 '\n'
                 '   class Foo(object):\n'
                 '       pass\n'
                 '\n'
    
                 'The class’s suite is then executed in a new execution frame '
    
                 '(see\n'
                 'Naming and binding), using a newly created local namespace and '
                 'the\n'
                 'original global namespace. (Usually, the suite contains mostly\n'
    
                 'function definitions.)  When the class’s suite finishes '
    
                 'execution, its\n'
                 'execution frame is discarded but its local namespace is saved. '
    
                 'class object is then created using the inheritance list for the '
                 'base\n'
                 'classes and the saved local namespace for the attribute '
                 'dictionary.\n'
                 'The class name is bound to this class object in the original '
                 'local\n'
                 'namespace.\n'
                 '\n'
    
                 'The order in which attributes are defined in the class body is\n'
    
                 'preserved in the new class’s "__dict__".  Note that this is '
    
                 'reliable\n'
                 'only right after the class is created and only for classes that '
                 'were\n'
                 'defined using the definition syntax.\n'
                 '\n'
    
                 'Class creation can be customized heavily using metaclasses.\n'
                 '\n'
                 'Classes can also be decorated: just like when decorating '
                 'functions,\n'
                 '\n'
                 '   @f1(arg)\n'
                 '   @f2\n'
                 '   class Foo: pass\n'
                 '\n'
    
                 'is roughly equivalent to\n'
    
                 '\n'
                 '   class Foo: pass\n'
                 '   Foo = f1(arg)(f2(Foo))\n'
                 '\n'
                 'The evaluation rules for the decorator expressions are the same '
                 'as for\n'
    
                 'function decorators.  The result is then bound to the class '
                 'name.\n'
    
                 '**Programmer’s note:** Variables defined in the class definition '
    
                 'are\n'
                 'class attributes; they are shared by instances.  Instance '
                 'attributes\n'
                 'can be set in a method with "self.name = value".  Both class '
                 'and\n'
                 'instance attributes are accessible through the notation '
    
                 '“"self.name"”,\n'
    
                 'and an instance attribute hides a class attribute with the same '
                 'name\n'
                 'when accessed in this way.  Class attributes can be used as '
                 'defaults\n'
                 'for instance attributes, but using mutable values there can lead '
                 'to\n'
                 'unexpected results.  Descriptors can be used to create instance\n'
                 'variables with different implementation details.\n'
                 '\n'
    
                 'See also:\n'
                 '\n'
                 '  **PEP 3115** - Metaclasses in Python 3000\n'
                 '     The proposal that changed the declaration of metaclasses to '
                 'the\n'
                 '     current syntax, and the semantics for how classes with\n'
                 '     metaclasses are constructed.\n'
                 '\n'
                 '  **PEP 3129** - Class Decorators\n'
                 '     The proposal that added class decorators.  Function and '
                 'method\n'
                 '     decorators were introduced in **PEP 318**.\n'
    
                 '\n'
                 '\n'
                 'Coroutines\n'
                 '==========\n'
                 '\n'
                 'New in version 3.5.\n'
                 '\n'
                 '\n'
                 'Coroutine function definition\n'
                 '-----------------------------\n'
                 '\n'
                 '   async_funcdef ::= [decorators] "async" "def" funcname "(" '
    
                 '[parameter_list] ")"\n'
                 '                     ["->" expression] ":" suite\n'
    
                 '\n'
                 'Execution of Python coroutines can be suspended and resumed at '
                 'many\n'
    
                 'points (see *coroutine*).  Inside the body of a coroutine '
                 'function,\n'
                 '"await" and "async" identifiers become reserved keywords; '
                 '"await"\n'
                 'expressions, "async for" and "async with" can only be used in\n'
                 'coroutine function bodies.\n'
    
                 '\n'
                 'Functions defined with "async def" syntax are always coroutine\n'
                 'functions, even if they do not contain "await" or "async" '
                 'keywords.\n'
                 '\n'
    
                 'It is a "SyntaxError" to use a "yield from" expression inside '
                 'the body\n'
                 'of a coroutine function.\n'
    
                 '\n'
                 'An example of a coroutine function:\n'
                 '\n'
                 '   async def func(param1, param2):\n'
                 '       do_stuff()\n'
                 '       await some_coroutine()\n'
                 '\n'
                 '\n'
                 'The "async for" statement\n'
                 '-------------------------\n'
                 '\n'
                 '   async_for_stmt ::= "async" for_stmt\n'
                 '\n'
                 'An *asynchronous iterable* is able to call asynchronous code in '
                 'its\n'
                 '*iter* implementation, and *asynchronous iterator* can call\n'
                 'asynchronous code in its *next* method.\n'
                 '\n'
                 'The "async for" statement allows convenient iteration over\n'
                 'asynchronous iterators.\n'
                 '\n'
                 'The following code:\n'
                 '\n'