The false value of the bool type. Assignments to False +are illegal and raise a SyntaxError.
+The sole value of the type NoneType. None is frequently used to +represent the absence of a value, as when default arguments are not passed to a +function. Assignments to None are illegal and raise a SyntaxError.
+The true value of the bool type. Assignments to True +are illegal and raise a SyntaxError.
+This constant is true if Python was not started with an -O option. +See also the assert statement.
++or_test ::= and_test | or_test "or" and_test +and_test ::= not_test | and_test "and" not_test +not_test ::= comparison | "not" not_test ++
In the context of Boolean operations, and also when expressions are used by +control flow statements, the following values are interpreted as false: +False, None, numeric zero of all types, and empty strings and containers +(including strings, tuples, lists, dictionaries, sets and frozensets). All +other values are interpreted as true. User-defined objects can customize their +truth value by providing a __bool__() method.
+The operator not yields True if its argument is false, False +otherwise.
+The expression x and y first evaluates x; if x is false, its value is +returned; otherwise, y is evaluated and the resulting value is returned.
+The expression x or y first evaluates x; if x is true, its value is +returned; otherwise, y is evaluated and the resulting value is returned.
+(Note that neither and nor or restrict the value and type +they return to False and True, but rather return the last evaluated +argument. This is sometimes useful, e.g., if s is a string that should be +replaced by a default value if it is empty, the expression s or 'foo' yields +the desired value. Because not has to create a new value, it +returns a boolean value regardless of the type of its argument +(for example, not 'foo' produces False rather than ''.)
++import_stmt ::= "import" module ["as" name] ( "," module ["as" name] )* + | "from" relative_module "import" identifier ["as" name] + ( "," identifier ["as" name] )* + | "from" relative_module "import" "(" identifier ["as" name] + ( "," identifier ["as" name] )* [","] ")" + | "from" module "import" "*" +module ::= (identifier ".")* identifier +relative_module ::= "."* module | "."+ +name ::= identifier ++
The basic import statement (no from clause) is executed in two +steps:
+When the statement contains multiple clauses (separated by +commas) the two steps are carried out separately for each clause, just +as though the clauses had been separated out into individiual import +statements.
+The details of the first step, finding and loading modules are described in +greater detail in the section on the import system, +which also describes the various types of packages and modules that can +be imported, as well as all the hooks that can be used to customize +the import system. Note that failures in this step may indicate either +that the module could not be located, or that an error occurred while +initializing the module, which includes execution of the module’s code.
+If the requested module is retrieved successfully, it will be made +available in the local namespace in one of three ways:
+The from form uses a slightly more complex process:
+Examples:
+import foo # foo imported and bound locally
+import foo.bar.baz # foo.bar.baz imported, foo bound locally
+import foo.bar.baz as fbb # foo.bar.baz imported and bound as fbb
+from foo.bar import baz # foo.bar.baz imported and bound as baz
+from foo import attr # foo imported and foo.attr bound as attr
+If the list of identifiers is replaced by a star ('*'), all public +names defined in the module are bound in the local namespace for the scope +where the import statement occurs.
+The public names defined by a module are determined by checking the module’s +namespace for a variable named __all__; if defined, it must be a sequence +of strings which are names defined or imported by that module. The names +given in __all__ are all considered public and are required to exist. If +__all__ is not defined, the set of public names includes all names found +in the module’s namespace which do not begin with an underscore character +('_'). __all__ should contain the entire public API. It is intended +to avoid accidentally exporting items that are not part of the API (such as +library modules which were imported and used within the module).
+The wild card form of import — from module import * — is only allowed at +the module level. Attempting to use it in class or function definitions will +raise a SyntaxError.
+When specifying what module to import you do not have to specify the absolute +name of the module. When a module or package is contained within another +package it is possible to make a relative import within the same top package +without having to mention the package name. By using leading dots in the +specified module or package after from you can specify how high to +traverse up the current package hierarchy without specifying exact names. One +leading dot means the current package where the module making the import +exists. Two dots means up one package level. Three dots is up two levels, etc. +So if you execute from . import mod from a module in the pkg package +then you will end up importing pkg.mod. If you execute from ..subpkg2 +import mod from within pkg.subpkg1 you will import pkg.subpkg2.mod. +The specification for relative imports is contained within PEP 328.
+importlib.import_module() is provided to support applications that +determine dynamically the modules to be loaded.
diff --git a/python/helpers/tools/python_keywords/assert b/python/helpers/tools/python_keywords/assert new file mode 100644 index 000000000000..ae5e0bf73cb1 --- /dev/null +++ b/python/helpers/tools/python_keywords/assert @@ -0,0 +1,28 @@ +Assert statements are a convenient way to insert debugging assertions into a +program:
++assert_stmt ::= "assert" expression ["," expression] ++
The simple form, assert expression, is equivalent to
+if __debug__:
+ if not expression: raise AssertionError
+The extended form, assert expression1, expression2, is equivalent to
+if __debug__:
+ if not expression1: raise AssertionError(expression2)
+These equivalences assume that __debug__ and AssertionError refer to +the built-in variables with those names. In the current implementation, the +built-in variable __debug__ is True under normal circumstances, +False when optimization is requested (command line option -O). The current +code generator emits no code for an assert statement when optimization is +requested at compile time. Note that it is unnecessary to include the source +code for the expression that failed in the error message; it will be displayed +as part of the stack trace.
+Assignments to __debug__ are illegal. The value for the built-in variable +is determined when the interpreter starts.
++break_stmt ::= "break" ++
break may only occur syntactically nested in a for or +while loop, but not nested in a function or class definition within +that loop.
+It terminates the nearest enclosing loop, skipping the optional else +clause if the loop has one.
+If a for loop is terminated by break, the loop control +target keeps its current value.
+When break passes control out of a try statement with a +finally clause, that finally clause is executed before +really leaving the loop.
+A class definition defines a class object (see section The standard type hierarchy):
++classdef ::= [decorators] "class" classname [inheritance] ":" suite +inheritance ::= "(" [parameter_list] ")" +classname ::= identifier ++
A class definition is an executable statement. The inheritance list usually +gives a list of base classes (see Customizing class creation for more advanced uses), so +each item in the list should evaluate to a class object which allows +subclassing. Classes without an inheritance list inherit, by default, from the +base class object; hence,
+class Foo:
+ pass
+is equivalent to
+class Foo(object):
+ pass
+The class’s suite is then executed in a new execution frame (see Naming and binding), +using a newly created local namespace and the original global namespace. +(Usually, the suite contains mostly function definitions.) When the class’s +suite finishes execution, its execution frame is discarded but its local +namespace is saved. [4] A class object is then created using the inheritance +list for the base classes and the saved local namespace for the attribute +dictionary. The class name is bound to this class object in the original local +namespace.
+Class creation can be customized heavily using metaclasses.
+Classes can also be decorated: just like when decorating functions,
+@f1(arg)
+@f2
+class Foo: pass
+is equivalent to
+class Foo: pass
+Foo = f1(arg)(f2(Foo))
+The evaluation rules for the decorator expressions are the same as for function +decorators. The result must be a class object, which is then bound to the class +name.
+Programmer’s note: Variables defined in the class definition are class +attributes; they are shared by instances. Instance attributes can be set in a +method with self.name = value. Both class and instance attributes are +accessible through the notation “self.name”, and an instance attribute hides +a class attribute with the same name when accessed in this way. Class +attributes can be used as defaults for instance attributes, but using mutable +values there can lead to unexpected results. Descriptors +can be used to create instance variables with different implementation details.
+ +Footnotes
+| [1] | The exception is propagated to the invocation stack unless +there is a finally clause which happens to raise another +exception. That new exception causes the old one to be lost. |
| [2] | Currently, control “flows off the end” except in the case of an exception +or the execution of a return, continue, or +break statement. |
| [3] | A string literal appearing as the first statement in the function body is +transformed into the function’s __doc__ attribute and therefore the +function’s docstring. |
| [4] | A string literal appearing as the first statement in the class body is +transformed into the namespace’s __doc__ item and therefore the class’s +docstring. |
+continue_stmt ::= "continue" ++
continue may only occur syntactically nested in a for or +while loop, but not nested in a function or class definition or +finally clause within that loop. It continues with the next +cycle of the nearest enclosing loop.
+When continue passes control out of a try statement with a +finally clause, that finally clause is executed before +really starting the next loop cycle.
+A function definition defines a user-defined function object (see section +The standard type hierarchy):
++funcdef ::= [decorators] "def" funcname "(" [parameter_list] ")" ["->" expression] ":" suite +decorators ::= decorator+ +decorator ::= "@" dotted_name ["(" [parameter_list [","]] ")"] NEWLINE +dotted_name ::= identifier ("." identifier)* +parameter_list ::= (defparameter ",")* + | "*" [parameter] ("," defparameter)* ["," "**" parameter] + | "**" parameter + | defparameter [","] ) +parameter ::= identifier [":" expression] +defparameter ::= parameter ["=" expression] +funcname ::= identifier ++
A function definition is an executable statement. Its execution binds the +function name in the current local namespace to a function object (a wrapper +around the executable code for the function). This function object contains a +reference to the current global namespace as the global namespace to be used +when the function is called.
+The function definition does not execute the function body; this gets executed +only when the function is called. [3]
+A function definition may be wrapped by one or more decorator expressions. +Decorator expressions are evaluated when the function is defined, in the scope +that contains the function definition. The result must be a callable, which is +invoked with the function object as the only argument. The returned value is +bound to the function name instead of the function object. Multiple decorators +are applied in nested fashion. For example, the following code
+@f1(arg)
+@f2
+def func(): pass
+is equivalent to
+def func(): pass
+func = f1(arg)(f2(func))
+When one or more parameters have the form parameter = +expression, the function is said to have “default parameter values.” For a +parameter with a default value, the corresponding argument may be +omitted from a call, in which +case the parameter’s default value is substituted. If a parameter has a default +value, all following parameters up until the “*” must also have a default +value — this is a syntactic restriction that is not expressed by the grammar.
+Default parameter values are evaluated from left to right when the function +definition is executed. This means that the expression is evaluated once, when +the function is defined, and that the same “pre-computed” value is used for each +call. This is especially important to understand when a default parameter is a +mutable object, such as a list or a dictionary: if the function modifies the +object (e.g. by appending an item to a list), the default value is in effect +modified. This is generally not what was intended. A way around this is to use +None as the default, and explicitly test for it in the body of the function, +e.g.:
+def whats_on_the_telly(penguin=None):
+ if penguin is None:
+ penguin = []
+ penguin.append("property of the zoo")
+ return penguin
+Function call semantics are described in more detail in section Calls. A +function call always assigns values to all parameters mentioned in the parameter +list, either from position arguments, from keyword arguments, or from default +values. If the form “*identifier” is present, it is initialized to a tuple +receiving any excess positional parameters, defaulting to the empty tuple. If +the form “**identifier” is present, it is initialized to a new dictionary +receiving any excess keyword arguments, defaulting to a new empty dictionary. +Parameters after “*” or “*identifier” are keyword-only parameters and +may only be passed used keyword arguments.
+Parameters may have annotations of the form “: expression” following the +parameter name. Any parameter may have an annotation even those of the form +*identifier or **identifier. Functions may have “return” annotation of +the form “-> expression” after the parameter list. These annotations can be +any valid Python expression and are evaluated when the function definition is +executed. Annotations may be evaluated in a different order than they appear in +the source code. The presence of annotations does not change the semantics of a +function. The annotation values are available as values of a dictionary keyed +by the parameters’ names in the __annotations__ attribute of the +function object.
+It is also possible to create anonymous functions (functions not bound to a +name), for immediate use in expressions. This uses lambda expressions, described in +section Lambdas. Note that the lambda expression is merely a shorthand for a +simplified function definition; a function defined in a “def” +statement can be passed around or assigned to another name just like a function +defined by a lambda expression. The “def” form is actually more powerful +since it allows the execution of multiple statements and annotations.
+Programmer’s note: Functions are first-class objects. A “def” statement +executed inside a function definition defines a local function that can be +returned or passed around. Free variables used in the nested function can +access the local variables of the function containing the def. See section +Naming and binding for details.
+See also
++del_stmt ::= "del" target_list ++
Deletion is recursively defined very similar to the way assignment is defined. +Rather than spelling it out in full details, here are some hints.
+Deletion of a target list recursively deletes each target, from left to right.
+Deletion of a name removes the binding of that name from the local or global +namespace, depending on whether the name occurs in a global statement +in the same code block. If the name is unbound, a NameError exception +will be raised.
+Deletion of attribute references, subscriptions and slicings is passed to the +primary object involved; deletion of a slicing is in general equivalent to +assignment of an empty slice of the right type (but even this is determined by +the sliced object).
+Changed in version 3.2: Previously it was illegal to delete a name from the local namespace if it +occurs as a free variable in a nested block.
+The if statement is used for conditional execution:
++if_stmt ::= "if" expression ":" suite + ( "elif" expression ":" suite )* + ["else" ":" suite] ++
It selects exactly one of the suites by evaluating the expressions one by one +until one is found to be true (see section Boolean operations for the definition of +true and false); then that suite is executed (and no other part of the +if statement is executed or evaluated). If all expressions are +false, the suite of the else clause, if present, is executed.
+The if statement is used for conditional execution:
++if_stmt ::= "if" expression ":" suite + ( "elif" expression ":" suite )* + ["else" ":" suite] ++
It selects exactly one of the suites by evaluating the expressions one by one +until one is found to be true (see section Boolean operations for the definition of +true and false); then that suite is executed (and no other part of the +if statement is executed or evaluated). If all expressions are +false, the suite of the else clause, if present, is executed.
+The try statement specifies exception handlers and/or cleanup code +for a group of statements:
++try_stmt ::= try1_stmt | try2_stmt +try1_stmt ::= "try" ":" suite + ("except" [expression ["as" identifier]] ":" suite)+ + ["else" ":" suite] + ["finally" ":" suite] +try2_stmt ::= "try" ":" suite + "finally" ":" suite ++
The except clause(s) specify one or more exception handlers. When no +exception occurs in the try clause, no exception handler is executed. +When an exception occurs in the try suite, a search for an exception +handler is started. This search inspects the except clauses in turn until one +is found that matches the exception. An expression-less except clause, if +present, must be last; it matches any exception. For an except clause with an +expression, that expression is evaluated, and the clause matches the exception +if the resulting object is “compatible” with the exception. An object is +compatible with an exception if it is the class or a base class of the exception +object or a tuple containing an item compatible with the exception.
+If no except clause matches the exception, the search for an exception handler +continues in the surrounding code and on the invocation stack. [1]
+If the evaluation of an expression in the header of an except clause raises an +exception, the original search for a handler is canceled and a search starts for +the new exception in the surrounding code and on the call stack (it is treated +as if the entire try statement raised the exception).
+When a matching except clause is found, the exception is assigned to the target +specified after the as keyword in that except clause, if present, and +the except clause’s suite is executed. All except clauses must have an +executable block. When the end of this block is reached, execution continues +normally after the entire try statement. (This means that if two nested +handlers exist for the same exception, and the exception occurs in the try +clause of the inner handler, the outer handler will not handle the exception.)
+When an exception has been assigned using as target, it is cleared at the +end of the except clause. This is as if
+except E as N:
+ foo
+was translated to
+except E as N:
+ try:
+ foo
+ finally:
+ del N
+This means the exception must be assigned to a different name to be able to +refer to it after the except clause. Exceptions are cleared because with the +traceback 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 an except clause’s suite is executed, details about the exception are +stored in the sys module and can be accessed via sys.exc_info(). +sys.exc_info() returns a 3-tuple consisting of the exception class, the +exception instance and a traceback object (see section The standard type hierarchy) identifying +the point in the program where the exception occurred. sys.exc_info() +values are restored to their previous values (before the call) when returning +from a function that handled an exception.
+The optional else clause is executed if and when control flows off +the end of the try clause. [2] Exceptions in the else +clause are not handled by the preceding except clauses.
+If finally is present, it specifies a ‘cleanup’ handler. The +try clause is executed, including any except and +else clauses. If an exception occurs in any of the clauses and is +not handled, the exception is temporarily saved. The finally clause +is executed. If there is a saved exception it is re-raised at the end of the +finally clause. If the finally clause raises another +exception, the saved exception is set as the context of the new exception. +If the finally clause executes a return or break +statement, the saved exception is discarded:
+>>> def f():
+... try:
+... 1/0
+... finally:
+... return 42
+...
+>>> f()
+42
+The exception information is not available to the program during execution of +the finally clause.
+When a return, break or continue statement is +executed in the try suite of a try...finally +statement, the finally clause is also executed ‘on the way out.’ A +continue statement is illegal in the finally clause. (The +reason is a problem with the current implementation — this restriction may be +lifted in the future).
+The return value of a function is determined by the last return +statement executed. Since the finally clause always executes, a +return statement executed in the finally clause will +always be the last one executed:
+>>> def foo():
+... try:
+... return 'try'
+... finally:
+... return 'finally'
+...
+>>> foo()
+'finally'
+Additional information on exceptions can be found in section Exceptions, +and information on using the raise statement to generate exceptions +may be found in section The raise statement.
++exec_stmt ::= "exec" or_expr ["in" expression ["," expression]] ++
This statement supports dynamic execution of Python code. The first expression +should evaluate to either a string, an open file object, or a code object. If +it is a string, the string is parsed as a suite of Python statements which is +then executed (unless a syntax error occurs). [1] If it is an open file, the file +is parsed until EOF and executed. If it is a code object, it is simply +executed. In all cases, the code that’s executed is expected to be valid as +file input (see section File input). Be aware that the +return and yield statements may not be used outside of +function definitions even within the context of code passed to the +exec statement.
+In all cases, if the optional parts are omitted, the code is executed in the +current scope. If only the first expression after in is specified, +it should be a dictionary, which will be used for both the global and the local +variables. If two expressions are given, they are used for the global and local +variables, respectively. If provided, locals can be any mapping object.
++Changed in version 2.4: Formerly, locals was required to be a dictionary.
+As a side effect, an implementation may insert additional keys into the +dictionaries given besides those corresponding to variable names set by the +executed code. For example, the current implementation may add a reference to +the dictionary of the built-in module __builtin__ under the key +__builtins__ (!).
+Programmer’s hints: dynamic evaluation of expressions is supported by the +built-in function eval(). The built-in functions globals() and +locals() return the current global and local dictionary, respectively, +which may be useful to pass around for use by exec.
+Footnotes
+| [1] | Note that the parser only accepts the Unix-style end of line convention. +If you are reading the code from a file, make sure to use universal +newline mode to convert Windows or Mac-style newlines. |
The try statement specifies exception handlers and/or cleanup code +for a group of statements:
++try_stmt ::= try1_stmt | try2_stmt +try1_stmt ::= "try" ":" suite + ("except" [expression ["as" identifier]] ":" suite)+ + ["else" ":" suite] + ["finally" ":" suite] +try2_stmt ::= "try" ":" suite + "finally" ":" suite ++
The except clause(s) specify one or more exception handlers. When no +exception occurs in the try clause, no exception handler is executed. +When an exception occurs in the try suite, a search for an exception +handler is started. This search inspects the except clauses in turn until one +is found that matches the exception. An expression-less except clause, if +present, must be last; it matches any exception. For an except clause with an +expression, that expression is evaluated, and the clause matches the exception +if the resulting object is “compatible” with the exception. An object is +compatible with an exception if it is the class or a base class of the exception +object or a tuple containing an item compatible with the exception.
+If no except clause matches the exception, the search for an exception handler +continues in the surrounding code and on the invocation stack. [1]
+If the evaluation of an expression in the header of an except clause raises an +exception, the original search for a handler is canceled and a search starts for +the new exception in the surrounding code and on the call stack (it is treated +as if the entire try statement raised the exception).
+When a matching except clause is found, the exception is assigned to the target +specified after the as keyword in that except clause, if present, and +the except clause’s suite is executed. All except clauses must have an +executable block. When the end of this block is reached, execution continues +normally after the entire try statement. (This means that if two nested +handlers exist for the same exception, and the exception occurs in the try +clause of the inner handler, the outer handler will not handle the exception.)
+When an exception has been assigned using as target, it is cleared at the +end of the except clause. This is as if
+except E as N:
+ foo
+was translated to
+except E as N:
+ try:
+ foo
+ finally:
+ del N
+This means the exception must be assigned to a different name to be able to +refer to it after the except clause. Exceptions are cleared because with the +traceback 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 an except clause’s suite is executed, details about the exception are +stored in the sys module and can be accessed via sys.exc_info(). +sys.exc_info() returns a 3-tuple consisting of the exception class, the +exception instance and a traceback object (see section The standard type hierarchy) identifying +the point in the program where the exception occurred. sys.exc_info() +values are restored to their previous values (before the call) when returning +from a function that handled an exception.
+The optional else clause is executed if and when control flows off +the end of the try clause. [2] Exceptions in the else +clause are not handled by the preceding except clauses.
+If finally is present, it specifies a ‘cleanup’ handler. The +try clause is executed, including any except and +else clauses. If an exception occurs in any of the clauses and is +not handled, the exception is temporarily saved. The finally clause +is executed. If there is a saved exception it is re-raised at the end of the +finally clause. If the finally clause raises another +exception, the saved exception is set as the context of the new exception. +If the finally clause executes a return or break +statement, the saved exception is discarded:
+>>> def f():
+... try:
+... 1/0
+... finally:
+... return 42
+...
+>>> f()
+42
+The exception information is not available to the program during execution of +the finally clause.
+When a return, break or continue statement is +executed in the try suite of a try...finally +statement, the finally clause is also executed ‘on the way out.’ A +continue statement is illegal in the finally clause. (The +reason is a problem with the current implementation — this restriction may be +lifted in the future).
+The return value of a function is determined by the last return +statement executed. Since the finally clause always executes, a +return statement executed in the finally clause will +always be the last one executed:
+>>> def foo():
+... try:
+... return 'try'
+... finally:
+... return 'finally'
+...
+>>> foo()
+'finally'
+Additional information on exceptions can be found in section Exceptions, +and information on using the raise statement to generate exceptions +may be found in section The raise statement.
+The for 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" expression_list ":" suite + ["else" ":" suite] ++
The expression list is evaluated once; it should yield an iterable object. An +iterator is created for the result of the expression_list. The suite is +then executed once for each item provided by the iterator, in the order returned +by the iterator. Each item in turn is assigned to the target list using the +standard rules for assignments (see Assignment statements), and then the suite is +executed. When the items are exhausted (which is immediately when the sequence +is empty or an iterator raises a StopIteration exception), the suite in +the else clause, if present, is executed, and the loop terminates.
+A break statement executed in the first suite terminates the loop +without executing the else clause’s suite. A continue +statement executed in the first suite skips the rest of the suite and continues +with the next item, or with the else clause if there is no next +item.
+The for-loop makes assignments to the variables(s) in the target list. +This overwrites all previous assignments to those variables including +those made in the suite of the for-loop:
+for i in range(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 the +sequence is empty, they will not have been assigned to at all by the loop. Hint: +the built-in function range() returns an iterator of integers suitable to +emulate the effect of Pascal’s for i := a to b do; e.g., list(range(3)) +returns the list [0, 1, 2].
+Note
+There is a subtlety when the sequence is being modified by the loop (this can +only occur for mutable sequences, i.e. lists). An internal counter is used +to keep track of which item is used next, and this is incremented on each +iteration. When this counter has reached the length of the sequence the loop +terminates. This means that if the suite deletes the current (or a previous) +item from the sequence, the next item will be skipped (since it gets the +index of the current item which has already been treated). Likewise, if the +suite inserts an item in the sequence before the current item, the current +item will be treated again the next time through the loop. This can lead to +nasty bugs that can be avoided by making a temporary copy using a slice of +the whole sequence, e.g.,
+for x in a[:]:
+ if x < 0: a.remove(x)
++import_stmt ::= "import" module ["as" name] ( "," module ["as" name] )* + | "from" relative_module "import" identifier ["as" name] + ( "," identifier ["as" name] )* + | "from" relative_module "import" "(" identifier ["as" name] + ( "," identifier ["as" name] )* [","] ")" + | "from" module "import" "*" +module ::= (identifier ".")* identifier +relative_module ::= "."* module | "."+ +name ::= identifier ++
The basic import statement (no from clause) is executed in two +steps:
+When the statement contains multiple clauses (separated by +commas) the two steps are carried out separately for each clause, just +as though the clauses had been separated out into individiual import +statements.
+The details of the first step, finding and loading modules are described in +greater detail in the section on the import system, +which also describes the various types of packages and modules that can +be imported, as well as all the hooks that can be used to customize +the import system. Note that failures in this step may indicate either +that the module could not be located, or that an error occurred while +initializing the module, which includes execution of the module’s code.
+If the requested module is retrieved successfully, it will be made +available in the local namespace in one of three ways:
+The from form uses a slightly more complex process:
+Examples:
+import foo # foo imported and bound locally
+import foo.bar.baz # foo.bar.baz imported, foo bound locally
+import foo.bar.baz as fbb # foo.bar.baz imported and bound as fbb
+from foo.bar import baz # foo.bar.baz imported and bound as baz
+from foo import attr # foo imported and foo.attr bound as attr
+If the list of identifiers is replaced by a star ('*'), all public +names defined in the module are bound in the local namespace for the scope +where the import statement occurs.
+The public names defined by a module are determined by checking the module’s +namespace for a variable named __all__; if defined, it must be a sequence +of strings which are names defined or imported by that module. The names +given in __all__ are all considered public and are required to exist. If +__all__ is not defined, the set of public names includes all names found +in the module’s namespace which do not begin with an underscore character +('_'). __all__ should contain the entire public API. It is intended +to avoid accidentally exporting items that are not part of the API (such as +library modules which were imported and used within the module).
+The wild card form of import — from module import * — is only allowed at +the module level. Attempting to use it in class or function definitions will +raise a SyntaxError.
+When specifying what module to import you do not have to specify the absolute +name of the module. When a module or package is contained within another +package it is possible to make a relative import within the same top package +without having to mention the package name. By using leading dots in the +specified module or package after from you can specify how high to +traverse up the current package hierarchy without specifying exact names. One +leading dot means the current package where the module making the import +exists. Two dots means up one package level. Three dots is up two levels, etc. +So if you execute from . import mod from a module in the pkg package +then you will end up importing pkg.mod. If you execute from ..subpkg2 +import mod from within pkg.subpkg1 you will import pkg.subpkg2.mod. +The specification for relative imports is contained within PEP 328.
+importlib.import_module() is provided to support applications that +determine dynamically the modules to be loaded.
diff --git a/python/helpers/tools/python_keywords/global b/python/helpers/tools/python_keywords/global new file mode 100644 index 000000000000..1b16892d475c --- /dev/null +++ b/python/helpers/tools/python_keywords/global @@ -0,0 +1,28 @@ ++global_stmt ::= "global" identifier ("," identifier)* ++
The global statement is a declaration which holds for the entire +current code block. It means that the listed identifiers are to be interpreted +as globals. It would be impossible to assign to a global variable without +global, although free variables may refer to globals without being +declared global.
+Names listed in a global statement must not be used in the same code +block textually preceding that global statement.
+Names listed in a global statement must not be defined as formal +parameters or in a for loop control target, class +definition, function definition, or import statement.
+CPython implementation detail: The current implementation does not enforce the two restrictions, but +programs should not abuse this freedom, as future implementations may enforce +them or silently change the meaning of the program.
+Programmer’s note: the global is a directive to the parser. It +applies only to code parsed at the same time as the global statement. +In particular, a global statement contained in a string or code +object supplied to the built-in exec() function does not affect the code +block containing the function call, and code contained in such a string is +unaffected by global statements in the code containing the function +call. The same applies to the eval() and compile() functions.
+The if statement is used for conditional execution:
++if_stmt ::= "if" expression ":" suite + ( "elif" expression ":" suite )* + ["else" ":" suite] ++
It selects exactly one of the suites by evaluating the expressions one by one +until one is found to be true (see section Boolean operations for the definition of +true and false); then that suite is executed (and no other part of the +if statement is executed or evaluated). If all expressions are +false, the suite of the else clause, if present, is executed.
++import_stmt ::= "import" module ["as" name] ( "," module ["as" name] )* + | "from" relative_module "import" identifier ["as" name] + ( "," identifier ["as" name] )* + | "from" relative_module "import" "(" identifier ["as" name] + ( "," identifier ["as" name] )* [","] ")" + | "from" module "import" "*" +module ::= (identifier ".")* identifier +relative_module ::= "."* module | "."+ +name ::= identifier ++
The basic import statement (no from clause) is executed in two +steps:
+When the statement contains multiple clauses (separated by +commas) the two steps are carried out separately for each clause, just +as though the clauses had been separated out into individiual import +statements.
+The details of the first step, finding and loading modules are described in +greater detail in the section on the import system, +which also describes the various types of packages and modules that can +be imported, as well as all the hooks that can be used to customize +the import system. Note that failures in this step may indicate either +that the module could not be located, or that an error occurred while +initializing the module, which includes execution of the module’s code.
+If the requested module is retrieved successfully, it will be made +available in the local namespace in one of three ways:
+The from form uses a slightly more complex process:
+Examples:
+import foo # foo imported and bound locally
+import foo.bar.baz # foo.bar.baz imported, foo bound locally
+import foo.bar.baz as fbb # foo.bar.baz imported and bound as fbb
+from foo.bar import baz # foo.bar.baz imported and bound as baz
+from foo import attr # foo imported and foo.attr bound as attr
+If the list of identifiers is replaced by a star ('*'), all public +names defined in the module are bound in the local namespace for the scope +where the import statement occurs.
+The public names defined by a module are determined by checking the module’s +namespace for a variable named __all__; if defined, it must be a sequence +of strings which are names defined or imported by that module. The names +given in __all__ are all considered public and are required to exist. If +__all__ is not defined, the set of public names includes all names found +in the module’s namespace which do not begin with an underscore character +('_'). __all__ should contain the entire public API. It is intended +to avoid accidentally exporting items that are not part of the API (such as +library modules which were imported and used within the module).
+The wild card form of import — from module import * — is only allowed at +the module level. Attempting to use it in class or function definitions will +raise a SyntaxError.
+When specifying what module to import you do not have to specify the absolute +name of the module. When a module or package is contained within another +package it is possible to make a relative import within the same top package +without having to mention the package name. By using leading dots in the +specified module or package after from you can specify how high to +traverse up the current package hierarchy without specifying exact names. One +leading dot means the current package where the module making the import +exists. Two dots means up one package level. Three dots is up two levels, etc. +So if you execute from . import mod from a module in the pkg package +then you will end up importing pkg.mod. If you execute from ..subpkg2 +import mod from within pkg.subpkg1 you will import pkg.subpkg2.mod. +The specification for relative imports is contained within PEP 328.
+importlib.import_module() is provided to support applications that +determine dynamically the modules to be loaded.
diff --git a/python/helpers/tools/python_keywords/in b/python/helpers/tools/python_keywords/in new file mode 100644 index 000000000000..e07b49ebc138 --- /dev/null +++ b/python/helpers/tools/python_keywords/in @@ -0,0 +1,97 @@ +Unlike C, all comparison operations in Python have the same priority, which is +lower than that of any arithmetic, shifting or bitwise operation. Also unlike +C, expressions like a < b < c have the interpretation that is conventional +in mathematics:
++comparison ::= or_expr ( comp_operator or_expr )* +comp_operator ::= "<" | ">" | "==" | ">=" | "<=" | "<>" | "!=" + | "is" ["not"] | ["not"] "in" ++
Comparisons yield boolean values: True or False.
+Comparisons can be chained arbitrarily, e.g., x < y <= z is equivalent to +x < y and y <= z, except that y is evaluated only once (but in both +cases z is not evaluated at all when x < y is found to be false).
+Formally, if a, b, c, ..., y, z are expressions and op1, op2, ..., +opN are comparison operators, then a op1 b op2 c ... y opN z is equivalent +to a op1 b and b op2 c and ... y opN z, except that each expression is +evaluated at most once.
+Note that a op1 b op2 c doesn’t imply any kind of comparison between a and +c, so that, e.g., x < y > z is perfectly legal (though perhaps not +pretty).
+The forms <> and != are equivalent; for consistency with C, != is +preferred; where != is mentioned below <> is also accepted. The <> +spelling is considered obsolescent.
+The operators <, >, ==, >=, <=, and != compare the +values of two objects. The objects need not have the same type. If both are +numbers, they are converted to a common type. Otherwise, objects of different +types always compare unequal, and are ordered consistently but arbitrarily. +You can control comparison behavior of objects of non-built-in types by defining +a __cmp__ method or rich comparison methods like __gt__, described in +section Special method names.
+(This unusual definition of comparison was used to simplify the definition of +operations like sorting and the in and not in operators. +In the future, the comparison rules for objects of different types are likely to +change.)
+Comparison of objects of the same type depends on the type:
+Numbers are compared arithmetically.
+Strings are compared lexicographically using the numeric equivalents (the +result of the built-in function ord()) of their characters. Unicode and +8-bit strings are fully interoperable in this behavior. [4]
+Tuples and lists are compared lexicographically using comparison of +corresponding elements. This means that to compare equal, each element must +compare equal and the two sequences must be of the same type and have the same +length.
+If not equal, the sequences are ordered the same as their first differing +elements. For example, cmp([1,2,x], [1,2,y]) returns the same as +cmp(x,y). If the corresponding element does not exist, the shorter sequence +is ordered first (for example, [1,2] < [1,2,3]).
+Mappings (dictionaries) compare equal if and only if their sorted (key, value) +lists compare equal. [5] Outcomes other than equality are resolved +consistently, but are not otherwise defined. [6]
+Most other objects of built-in types compare unequal unless they are the same +object; the choice whether one object is considered smaller or larger than +another one is made arbitrarily but consistently within one execution of a +program.
+The operators in and not in test for collection +membership. x in s evaluates to true if x is a member of the collection +s, and false otherwise. x not in s returns the negation of x in s. +The collection membership test has traditionally been bound to sequences; an +object is a member of a collection if the collection is a sequence and contains +an element equal to that object. However, it make sense for many other object +types to support membership tests without being a sequence. In particular, +dictionaries (for keys) and sets support membership testing.
+For the list and tuple types, x in y is true if and only if there exists an +index i such that x == y[i] is true.
+For the Unicode and string types, x in y is true if and only if x is a +substring of y. An equivalent test is y.find(x) != -1. Note, x and y +need not be the same type; consequently, u'ab' in 'abc' will return +True. Empty strings are always considered to be a substring of any other +string, so "" in "abc" will return True.
++Changed in version 2.3: Previously, x was required to be a string of length 1.
+For user-defined classes which define the __contains__() method, x in +y is true if and only if y.__contains__(x) is true.
+For user-defined classes which do not define __contains__() but do define +__iter__(), x in y is true if some value z with x == z is +produced while iterating over y. If an exception is raised during the +iteration, it is as if in raised that exception.
+Lastly, the old-style iteration protocol is tried: if a class defines +__getitem__(), x in y is true if and only if there is a non-negative +integer index i such that x == y[i], and all lower integer indices do not +raise IndexError exception. (If any other exception is raised, it is as +if in raised that exception).
+The operator not in is defined to have the inverse true value of +in.
+The operators is and is not test for object identity: x +is y is true if and only if x and y are the same object. x is not y +yields the inverse truth value. [7]
+Unlike C, all comparison operations in Python have the same priority, which is +lower than that of any arithmetic, shifting or bitwise operation. Also unlike +C, expressions like a < b < c have the interpretation that is conventional +in mathematics:
++comparison ::= or_expr ( comp_operator or_expr )* +comp_operator ::= "<" | ">" | "==" | ">=" | "<=" | "<>" | "!=" + | "is" ["not"] | ["not"] "in" ++
Comparisons yield boolean values: True or False.
+Comparisons can be chained arbitrarily, e.g., x < y <= z is equivalent to +x < y and y <= z, except that y is evaluated only once (but in both +cases z is not evaluated at all when x < y is found to be false).
+Formally, if a, b, c, ..., y, z are expressions and op1, op2, ..., +opN are comparison operators, then a op1 b op2 c ... y opN z is equivalent +to a op1 b and b op2 c and ... y opN z, except that each expression is +evaluated at most once.
+Note that a op1 b op2 c doesn’t imply any kind of comparison between a and +c, so that, e.g., x < y > z is perfectly legal (though perhaps not +pretty).
+The forms <> and != are equivalent; for consistency with C, != is +preferred; where != is mentioned below <> is also accepted. The <> +spelling is considered obsolescent.
+The operators <, >, ==, >=, <=, and != compare the +values of two objects. The objects need not have the same type. If both are +numbers, they are converted to a common type. Otherwise, objects of different +types always compare unequal, and are ordered consistently but arbitrarily. +You can control comparison behavior of objects of non-built-in types by defining +a __cmp__ method or rich comparison methods like __gt__, described in +section Special method names.
+(This unusual definition of comparison was used to simplify the definition of +operations like sorting and the in and not in operators. +In the future, the comparison rules for objects of different types are likely to +change.)
+Comparison of objects of the same type depends on the type:
+Numbers are compared arithmetically.
+Strings are compared lexicographically using the numeric equivalents (the +result of the built-in function ord()) of their characters. Unicode and +8-bit strings are fully interoperable in this behavior. [4]
+Tuples and lists are compared lexicographically using comparison of +corresponding elements. This means that to compare equal, each element must +compare equal and the two sequences must be of the same type and have the same +length.
+If not equal, the sequences are ordered the same as their first differing +elements. For example, cmp([1,2,x], [1,2,y]) returns the same as +cmp(x,y). If the corresponding element does not exist, the shorter sequence +is ordered first (for example, [1,2] < [1,2,3]).
+Mappings (dictionaries) compare equal if and only if their sorted (key, value) +lists compare equal. [5] Outcomes other than equality are resolved +consistently, but are not otherwise defined. [6]
+Most other objects of built-in types compare unequal unless they are the same +object; the choice whether one object is considered smaller or larger than +another one is made arbitrarily but consistently within one execution of a +program.
+The operators in and not in test for collection +membership. x in s evaluates to true if x is a member of the collection +s, and false otherwise. x not in s returns the negation of x in s. +The collection membership test has traditionally been bound to sequences; an +object is a member of a collection if the collection is a sequence and contains +an element equal to that object. However, it make sense for many other object +types to support membership tests without being a sequence. In particular, +dictionaries (for keys) and sets support membership testing.
+For the list and tuple types, x in y is true if and only if there exists an +index i such that x == y[i] is true.
+For the Unicode and string types, x in y is true if and only if x is a +substring of y. An equivalent test is y.find(x) != -1. Note, x and y +need not be the same type; consequently, u'ab' in 'abc' will return +True. Empty strings are always considered to be a substring of any other +string, so "" in "abc" will return True.
++Changed in version 2.3: Previously, x was required to be a string of length 1.
+For user-defined classes which define the __contains__() method, x in +y is true if and only if y.__contains__(x) is true.
+For user-defined classes which do not define __contains__() but do define +__iter__(), x in y is true if some value z with x == z is +produced while iterating over y. If an exception is raised during the +iteration, it is as if in raised that exception.
+Lastly, the old-style iteration protocol is tried: if a class defines +__getitem__(), x in y is true if and only if there is a non-negative +integer index i such that x == y[i], and all lower integer indices do not +raise IndexError exception. (If any other exception is raised, it is as +if in raised that exception).
+The operator not in is defined to have the inverse true value of +in.
+The operators is and is not test for object identity: x +is y is true if and only if x and y are the same object. x is not y +yields the inverse truth value. [7]
++lambda_expr ::= "lambda" [parameter_list]: expression +lambda_expr_nocond ::= "lambda" [parameter_list]: expression_nocond ++
Lambda expressions (sometimes called lambda forms) are used to create anonymous +functions. The expression lambda arguments: expression yields a function +object. The unnamed object behaves like a function object defined with
+def <lambda>(arguments):
+ return expression
+See section Function definitions for the syntax of parameter lists. Note that +functions created with lambda expressions cannot contain statements or +annotations.
++nonlocal_stmt ::= "nonlocal" identifier ("," identifier)* ++
The nonlocal statement causes the listed identifiers to refer to +previously bound variables in the nearest enclosing scope excluding globals. +This is important because the default behavior for binding is to search the +local namespace first. The statement allows encapsulated code to rebind +variables outside of the local scope besides the global (module) scope.
+Names listed in a nonlocal statement, unlike those listed in a +global statement, must refer to pre-existing bindings in an +enclosing scope (the scope in which a new binding should be created cannot +be determined unambiguously).
+Names listed in a nonlocal statement must not collide with +pre-existing bindings in the local scope.
+ ++or_test ::= and_test | or_test "or" and_test +and_test ::= not_test | and_test "and" not_test +not_test ::= comparison | "not" not_test ++
In the context of Boolean operations, and also when expressions are used by +control flow statements, the following values are interpreted as false: +False, None, numeric zero of all types, and empty strings and containers +(including strings, tuples, lists, dictionaries, sets and frozensets). All +other values are interpreted as true. User-defined objects can customize their +truth value by providing a __bool__() method.
+The operator not yields True if its argument is false, False +otherwise.
+The expression x and y first evaluates x; if x is false, its value is +returned; otherwise, y is evaluated and the resulting value is returned.
+The expression x or y first evaluates x; if x is true, its value is +returned; otherwise, y is evaluated and the resulting value is returned.
+(Note that neither and nor or restrict the value and type +they return to False and True, but rather return the last evaluated +argument. This is sometimes useful, e.g., if s is a string that should be +replaced by a default value if it is empty, the expression s or 'foo' yields +the desired value. Because not has to create a new value, it +returns a boolean value regardless of the type of its argument +(for example, not 'foo' produces False rather than ''.)
++or_test ::= and_test | or_test "or" and_test +and_test ::= not_test | and_test "and" not_test +not_test ::= comparison | "not" not_test ++
In the context of Boolean operations, and also when expressions are used by +control flow statements, the following values are interpreted as false: +False, None, numeric zero of all types, and empty strings and containers +(including strings, tuples, lists, dictionaries, sets and frozensets). All +other values are interpreted as true. User-defined objects can customize their +truth value by providing a __bool__() method.
+The operator not yields True if its argument is false, False +otherwise.
+The expression x and y first evaluates x; if x is false, its value is +returned; otherwise, y is evaluated and the resulting value is returned.
+The expression x or y first evaluates x; if x is true, its value is +returned; otherwise, y is evaluated and the resulting value is returned.
+(Note that neither and nor or restrict the value and type +they return to False and True, but rather return the last evaluated +argument. This is sometimes useful, e.g., if s is a string that should be +replaced by a default value if it is empty, the expression s or 'foo' yields +the desired value. Because not has to create a new value, it +returns a boolean value regardless of the type of its argument +(for example, not 'foo' produces False rather than ''.)
++pass_stmt ::= "pass" ++
pass is a null operation — when it is executed, nothing happens. +It is useful as a placeholder when a statement is required syntactically, but no +code needs to be executed, for example:
+def f(arg): pass # a function that does nothing (yet)
+
+class C: pass # a class with no methods (yet)
++raise_stmt ::= "raise" [expression ["from" expression]] ++
If no expressions are present, raise re-raises the last exception +that was active in the current scope. If no exception is active in the current +scope, a RuntimeError exception is raised indicating that this is an +error.
+Otherwise, raise evaluates the first expression as the exception +object. It must be either a subclass or an instance of BaseException. +If it is a class, the exception instance will be obtained when needed by +instantiating the class with no arguments.
+The type of the exception is the exception instance’s class, the +value is the instance itself.
+A traceback object is normally created automatically when an exception is raised +and attached to it as the __traceback__ attribute, which is writable. +You can create an exception and set your own traceback in one step using the +with_traceback() exception method (which returns the same exception +instance, with its traceback set to its argument), like so:
+raise Exception("foo occurred").with_traceback(tracebackobj)
+The from clause is used for exception chaining: if given, the second +expression must be another exception class or instance, which will then be +attached to the raised exception as the __cause__ attribute (which is +writable). If the raised exception is not handled, both exceptions will be +printed:
+>>> try:
+... print(1 / 0)
+... except Exception as exc:
+... raise RuntimeError("Something bad happened") from exc
+...
+Traceback (most recent call last):
+ File "<stdin>", line 2, in <module>
+ZeroDivisionError: int division or modulo by zero
+
+The above exception was the direct cause of the following exception:
+
+Traceback (most recent call last):
+ File "<stdin>", line 4, in <module>
+RuntimeError: Something bad happened
+A similar mechanism works implicitly if an exception is raised inside an +exception handler or a finally clause: the previous exception is then +attached as the new exception’s __context__ attribute:
+>>> try:
+... print(1 / 0)
+... except:
+... raise RuntimeError("Something bad happened")
+...
+Traceback (most recent call last):
+ File "<stdin>", line 2, in <module>
+ZeroDivisionError: int division or modulo by zero
+
+During handling of the above exception, another exception occurred:
+
+Traceback (most recent call last):
+ File "<stdin>", line 4, in <module>
+RuntimeError: Something bad happened
+Additional information on exceptions can be found in section Exceptions, +and information about handling exceptions is in section The try statement.
++return_stmt ::= "return" [expression_list] ++
return may only occur syntactically nested in a function definition, +not within a nested class definition.
+If an expression list is present, it is evaluated, else None is substituted.
+return leaves the current function call with the expression list (or +None) as return value.
+When return passes control out of a try statement with a +finally clause, that finally clause is executed before +really leaving the function.
+In a generator function, the return statement indicates that the +generator is done and will cause StopIteration to be raised. The returned +value (if any) is used as an argument to construct StopIteration and +becomes the StopIteration.value attribute.
+The try statement specifies exception handlers and/or cleanup code +for a group of statements:
++try_stmt ::= try1_stmt | try2_stmt +try1_stmt ::= "try" ":" suite + ("except" [expression ["as" identifier]] ":" suite)+ + ["else" ":" suite] + ["finally" ":" suite] +try2_stmt ::= "try" ":" suite + "finally" ":" suite ++
The except clause(s) specify one or more exception handlers. When no +exception occurs in the try clause, no exception handler is executed. +When an exception occurs in the try suite, a search for an exception +handler is started. This search inspects the except clauses in turn until one +is found that matches the exception. An expression-less except clause, if +present, must be last; it matches any exception. For an except clause with an +expression, that expression is evaluated, and the clause matches the exception +if the resulting object is “compatible” with the exception. An object is +compatible with an exception if it is the class or a base class of the exception +object or a tuple containing an item compatible with the exception.
+If no except clause matches the exception, the search for an exception handler +continues in the surrounding code and on the invocation stack. [1]
+If the evaluation of an expression in the header of an except clause raises an +exception, the original search for a handler is canceled and a search starts for +the new exception in the surrounding code and on the call stack (it is treated +as if the entire try statement raised the exception).
+When a matching except clause is found, the exception is assigned to the target +specified after the as keyword in that except clause, if present, and +the except clause’s suite is executed. All except clauses must have an +executable block. When the end of this block is reached, execution continues +normally after the entire try statement. (This means that if two nested +handlers exist for the same exception, and the exception occurs in the try +clause of the inner handler, the outer handler will not handle the exception.)
+When an exception has been assigned using as target, it is cleared at the +end of the except clause. This is as if
+except E as N:
+ foo
+was translated to
+except E as N:
+ try:
+ foo
+ finally:
+ del N
+This means the exception must be assigned to a different name to be able to +refer to it after the except clause. Exceptions are cleared because with the +traceback 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 an except clause’s suite is executed, details about the exception are +stored in the sys module and can be accessed via sys.exc_info(). +sys.exc_info() returns a 3-tuple consisting of the exception class, the +exception instance and a traceback object (see section The standard type hierarchy) identifying +the point in the program where the exception occurred. sys.exc_info() +values are restored to their previous values (before the call) when returning +from a function that handled an exception.
+The optional else clause is executed if and when control flows off +the end of the try clause. [2] Exceptions in the else +clause are not handled by the preceding except clauses.
+If finally is present, it specifies a ‘cleanup’ handler. The +try clause is executed, including any except and +else clauses. If an exception occurs in any of the clauses and is +not handled, the exception is temporarily saved. The finally clause +is executed. If there is a saved exception it is re-raised at the end of the +finally clause. If the finally clause raises another +exception, the saved exception is set as the context of the new exception. +If the finally clause executes a return or break +statement, the saved exception is discarded:
+>>> def f():
+... try:
+... 1/0
+... finally:
+... return 42
+...
+>>> f()
+42
+The exception information is not available to the program during execution of +the finally clause.
+When a return, break or continue statement is +executed in the try suite of a try...finally +statement, the finally clause is also executed ‘on the way out.’ A +continue statement is illegal in the finally clause. (The +reason is a problem with the current implementation — this restriction may be +lifted in the future).
+The return value of a function is determined by the last return +statement executed. Since the finally clause always executes, a +return statement executed in the finally clause will +always be the last one executed:
+>>> def foo():
+... try:
+... return 'try'
+... finally:
+... return 'finally'
+...
+>>> foo()
+'finally'
+Additional information on exceptions can be found in section Exceptions, +and information on using the raise statement to generate exceptions +may be found in section The raise statement.
+The while statement is used for repeated execution as long as an +expression is true:
++while_stmt ::= "while" expression ":" suite + ["else" ":" suite] ++
This repeatedly tests the expression and, if it is true, executes the first +suite; if the expression is false (which may be the first time it is tested) the +suite of the else clause, if present, is executed and the loop +terminates.
+A break statement executed in the first suite terminates the loop +without executing the else clause’s suite. A continue +statement executed in the first suite skips the rest of the suite and goes back +to testing the expression.
+The with statement is used to wrap the execution of a block with +methods defined by a context manager (see section With Statement Context Managers). +This allows common try...except...finally +usage patterns to be encapsulated for convenient reuse.
+
+with_stmt ::= "with" with_item ("," with_item)* ":" suite
+with_item ::= expression ["as" target]
+
+The execution of the with statement with one “item” proceeds as follows:
+The context expression (the expression given in the with_item) is +evaluated to obtain a context manager.
+The context manager’s __exit__() is loaded for later use.
+The context manager’s __enter__() method is invoked.
+If a target was included in the with statement, the return value +from __enter__() is assigned to it.
+Note
+The with statement guarantees that if the __enter__() +method returns without an error, then __exit__() will always be +called. 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 would +be. See step 6 below.
+The suite is executed.
+The context manager’s __exit__() method is invoked. If an exception +caused the suite to be exited, its type, value, and traceback are passed as +arguments to __exit__(). Otherwise, three None arguments are +supplied.
+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 return +value was true, the exception is suppressed, and execution continues with the +statement following the with statement.
+If the suite was exited for any reason other than an exception, the return +value from __exit__() is ignored, and execution proceeds at the normal +location for the kind of exit that was taken.
+With more than one item, the context managers are processed as if multiple +with statements were nested:
+with A() as a, B() as b:
+ suite
+is equivalent to
+with A() as a:
+ with B() as b:
+ suite
+Changed in version 3.1: Support for multiple context expressions.
++yield_stmt ::= yield_expression ++
A yield statement is semantically equivalent to a yield +expression. The yield statement can be used to omit the parentheses +that would otherwise be required in the equivalent yield expression +statement. For example, the yield statements
+yield <expr>
+yield from <expr>
+are equivalent to the yield expression statements
+(yield <expr>)
+(yield from <expr>)
+Yield expressions and statements are only used when defining a generator +function, and are only used in the body of the generator function. Using yield +in a function definition is sufficient to cause that definition to create a +generator function instead of a normal function.
+For full details of yield semantics, refer to the +Yield expressions section.
++return_stmt ::= "return" [expression_list] ++
return may only occur syntactically nested in a function definition, +not within a nested class definition.
+If an expression list is present, it is evaluated, else None is substituted.
+return leaves the current function call with the expression list (or +None) as return value.
+When return passes control out of a try statement with a +finally clause, that finally clause is executed before +really leaving the function.
+In a generator function, the return statement indicates that the +generator is done and will cause StopIteration to be raised. The returned +value (if any) is used as an argument to construct StopIteration and +becomes the StopIteration.value attribute.
+