diff options
Diffstat (limited to 'Doc/ref/ref7.tex')
| -rw-r--r-- | Doc/ref/ref7.tex | 552 |
1 files changed, 0 insertions, 552 deletions
diff --git a/Doc/ref/ref7.tex b/Doc/ref/ref7.tex deleted file mode 100644 index 9294557..0000000 --- a/Doc/ref/ref7.tex +++ /dev/null @@ -1,552 +0,0 @@ -\chapter{Compound statements\label{compound}} -\indexii{compound}{statement} - -Compound statements contain (groups of) other statements; they affect -or control the execution of those other statements in some way. In -general, compound statements span multiple lines, although in simple -incarnations a whole compound statement may be contained in one line. - -The \keyword{if}, \keyword{while} and \keyword{for} statements implement -traditional control flow constructs. \keyword{try} specifies exception -handlers and/or cleanup code for a group of statements. Function and -class definitions are also syntactically compound statements. - -Compound statements consist of one or more `clauses.' A clause -consists of a header and a `suite.' The clause headers of a -particular compound statement are all at the same indentation level. -Each clause header begins with a uniquely identifying keyword and ends -with a colon. A suite is a group of statements controlled by a -clause. A suite can be one or more semicolon-separated simple -statements on the same line as the header, following the header's -colon, or it can be one or more indented statements on subsequent -lines. Only the latter form of suite can contain nested compound -statements; the following is illegal, mostly because it wouldn't be -clear to which \keyword{if} clause a following \keyword{else} clause would -belong: -\index{clause} -\index{suite} - -\begin{verbatim} -if test1: if test2: print x -\end{verbatim} - -Also note that the semicolon binds tighter than the colon in this -context, so that in the following example, either all or none of the -\keyword{print} statements are executed: - -\begin{verbatim} -if x < y < z: print x; print y; print z -\end{verbatim} - -Summarizing: - -\begin{productionlist} - \production{compound_stmt} - {\token{if_stmt}} - \productioncont{| \token{while_stmt}} - \productioncont{| \token{for_stmt}} - \productioncont{| \token{try_stmt}} - \productioncont{| \token{with_stmt}} - \productioncont{| \token{funcdef}} - \productioncont{| \token{classdef}} - \production{suite} - {\token{stmt_list} NEWLINE - | NEWLINE INDENT \token{statement}+ DEDENT} - \production{statement} - {\token{stmt_list} NEWLINE | \token{compound_stmt}} - \production{stmt_list} - {\token{simple_stmt} (";" \token{simple_stmt})* [";"]} -\end{productionlist} - -Note that statements always end in a -\code{NEWLINE}\index{NEWLINE token} possibly followed by a -\code{DEDENT}.\index{DEDENT token} Also note that optional -continuation clauses always begin with a keyword that cannot start a -statement, thus there are no ambiguities (the `dangling -\keyword{else}' problem is solved in Python by requiring nested -\keyword{if} statements to be indented). -\indexii{dangling}{else} - -The formatting of the grammar rules in the following sections places -each clause on a separate line for clarity. - - -\section{The \keyword{if} statement\label{if}} -\stindex{if} - -The \keyword{if} statement is used for conditional execution: - -\begin{productionlist} - \production{if_stmt} - {"if" \token{expression} ":" \token{suite}} - \productioncont{( "elif" \token{expression} ":" \token{suite} )*} - \productioncont{["else" ":" \token{suite}]} -\end{productionlist} - -It selects exactly one of the suites by evaluating the expressions one -by one until one is found to be true (see section~\ref{Booleans} for -the definition of true and false); then that suite is executed (and no -other part of the \keyword{if} statement is executed or evaluated). If -all expressions are false, the suite of the \keyword{else} clause, if -present, is executed. -\kwindex{elif} -\kwindex{else} - - -\section{The \keyword{while} statement\label{while}} -\stindex{while} -\indexii{loop}{statement} - -The \keyword{while} statement is used for repeated execution as long -as an expression is true: - -\begin{productionlist} - \production{while_stmt} - {"while" \token{expression} ":" \token{suite}} - \productioncont{["else" ":" \token{suite}]} -\end{productionlist} - -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 \keyword{else} clause, if present, is -executed and the loop terminates. -\kwindex{else} - -A \keyword{break} statement executed in the first suite terminates the -loop without executing the \keyword{else} clause's suite. A -\keyword{continue} statement executed in the first suite skips the rest -of the suite and goes back to testing the expression. -\stindex{break} -\stindex{continue} - - -\section{The \keyword{for} statement\label{for}} -\stindex{for} -\indexii{loop}{statement} - -The \keyword{for} statement is used to iterate over the elements of a -sequence (such as a string, tuple or list) or other iterable object: -\obindex{sequence} - -\begin{productionlist} - \production{for_stmt} - {"for" \token{target_list} "in" \token{expression_list} - ":" \token{suite}} - \productioncont{["else" ":" \token{suite}]} -\end{productionlist} - -The expression list is evaluated once; it should yield an iterable -object. An iterator is created for the result of the -{}\code{expression_list}. The suite is then executed once for each -item provided by the iterator, in the -order of ascending indices. Each item in turn is assigned to the -target list using the standard rules for assignments, and then the -suite is executed. When the items are exhausted (which is immediately -when the sequence is empty), the suite in the \keyword{else} clause, if -present, is executed, and the loop terminates. -\kwindex{in} -\kwindex{else} -\indexii{target}{list} - -A \keyword{break} statement executed in the first suite terminates the -loop without executing the \keyword{else} clause's suite. A -\keyword{continue} statement executed in the first suite skips the rest -of the suite and continues with the next item, or with the \keyword{else} -clause if there was no next item. -\stindex{break} -\stindex{continue} - -The suite may assign to the variable(s) in the target list; this does -not affect the next item assigned to it. - -The target list is not deleted when the loop is finished, but if the -sequence is empty, it will not have been assigned to at all by the -loop. Hint: the built-in function \function{range()} returns a -sequence of integers suitable to emulate the effect of Pascal's -\code{for i := a to b do}; -e.g., \code{range(3)} returns the list \code{[0, 1, 2]}. -\bifuncindex{range} -\indexii{Pascal}{language} - -\warning{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., -\index{loop!over mutable sequence} -\index{mutable sequence!loop over}} - -\begin{verbatim} -for x in a[:]: - if x < 0: a.remove(x) -\end{verbatim} - - -\section{The \keyword{try} statement\label{try}} -\stindex{try} - -The \keyword{try} statement specifies exception handlers and/or cleanup -code for a group of statements: - -\begin{productionlist} - \production{try_stmt} {try1_stmt | try2_stmt} - \production{try1_stmt} - {"try" ":" \token{suite}} - \productioncont{("except" [\token{expression} - ["," \token{target}]] ":" \token{suite})+} - \productioncont{["else" ":" \token{suite}]} - \productioncont{["finally" ":" \token{suite}]} - \production{try2_stmt} - {"try" ":" \token{suite}} - \productioncont{"finally" ":" \token{suite}} -\end{productionlist} - -\versionchanged[In previous versions of Python, -\keyword{try}...\keyword{except}...\keyword{finally} did not work. -\keyword{try}...\keyword{except} had to be nested in -\keyword{try}...\keyword{finally}]{2.5} - -The \keyword{except} clause(s) specify one or more exception handlers. -When no exception occurs in the -\keyword{try} clause, no exception handler is executed. When an -exception occurs in the \keyword{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, a tuple -containing an item compatible with the exception, or, in the -(deprecated) case of string exceptions, is the raised string itself -(note that the object identities must match, i.e. it must be the same -string object, not just a string with the same value). -\kwindex{except} - -If no except clause matches the exception, the search for an exception -handler continues in the surrounding code and on the invocation stack. -\footnote{The exception is propogated to the invocation stack only if -there is no \keyword{finally} clause that negates the exception.} - -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 \keyword{try} statement -raised the exception). - -When a matching except clause is found, the exception is assigned to -the target specified 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.) - -Before an except clause's suite is executed, details about the -exception are stored in the \module{sys}\refbimodindex{sys} module -and can be access via \function{sys.exc_info()}. \function{sys.exc_info()} -returns a 3-tuple consisting of: \code{exc_type} receives -the object identifying the exception; \code{exc_value} receives -the exception's parameter; \code{exc_traceback} receives a -traceback object\obindex{traceback} (see section~\ref{traceback}) -identifying the point in the program where the exception occurred. -\function{sys.exc_info()} values are restored to their previous values -(before the call) when returning from a function that handled an exception. - -The optional \keyword{else} clause is executed if and when control -flows off the end of the \keyword{try} clause.\footnote{ - Currently, control ``flows off the end'' except in the case of an - exception or the execution of a \keyword{return}, - \keyword{continue}, or \keyword{break} statement. -} Exceptions in the \keyword{else} clause are not handled by the -preceding \keyword{except} clauses. -\kwindex{else} -\stindex{return} -\stindex{break} -\stindex{continue} - -If \keyword{finally} is present, it specifies a `cleanup' handler. The -\keyword{try} clause is executed, including any \keyword{except} and -\keyword{else} clauses. If an exception occurs in any of the clauses -and is not handled, the exception is temporarily saved. The -\keyword{finally} clause is executed. If there is a saved exception, -it is re-raised at the end of the \keyword{finally} clause. -If the \keyword{finally} clause raises another exception or -executes a \keyword{return} or \keyword{break} statement, the saved -exception is lost. The exception information is not available to the -program during execution of the \keyword{finally} clause. -\kwindex{finally} - -When a \keyword{return}, \keyword{break} or \keyword{continue} statement is -executed in the \keyword{try} suite of a \keyword{try}...\keyword{finally} -statement, the \keyword{finally} clause is also executed `on the way out.' A -\keyword{continue} statement is illegal in the \keyword{finally} clause. -(The reason is a problem with the current implementation --- this -restriction may be lifted in the future). -\stindex{return} -\stindex{break} -\stindex{continue} - -Additional information on exceptions can be found in -section~\ref{exceptions}, and information on using the \keyword{raise} -statement to generate exceptions may be found in section~\ref{raise}. - - -\section{The \keyword{with} statement\label{with}} -\stindex{with} - -\versionadded{2.5} - -The \keyword{with} statement is used to wrap the execution of a block -with methods defined by a context manager (see -section~\ref{context-managers}). This allows common -\keyword{try}...\keyword{except}...\keyword{finally} usage patterns to -be encapsulated for convenient reuse. - -\begin{productionlist} - \production{with_stmt} - {"with" \token{expression} ["as" \token{target}] ":" \token{suite}} -\end{productionlist} - -The execution of the \keyword{with} statement proceeds as follows: - -\begin{enumerate} - -\item The context expression is evaluated to obtain a context manager. - -\item The context manager's \method{__enter__()} method is invoked. - -\item If a target was included in the \keyword{with} -statement, the return value from \method{__enter__()} is assigned to it. - -\note{The \keyword{with} statement guarantees that if the -\method{__enter__()} method returns without an error, then -\method{__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 5 below.} - -\item The suite is executed. - -\item The context manager's \method{__exit__()} method is invoked. If -an exception caused the suite to be exited, its type, value, and -traceback are passed as arguments to \method{__exit__()}. Otherwise, -three \constant{None} arguments are supplied. - -If the suite was exited due to an exception, and the return -value from the \method{__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 \keyword{with} -statement. - -If the suite was exited for any reason other than an exception, the -return value from \method{__exit__()} is ignored, and execution proceeds -at the normal location for the kind of exit that was taken. - -\end{enumerate} - -\begin{notice} -In Python 2.5, the \keyword{with} statement is only allowed -when the \code{with_statement} feature has been enabled. It will always -be enabled in Python 2.6. This \code{__future__} import statement can -be used to enable the feature: - -\begin{verbatim} -from __future__ import with_statement -\end{verbatim} -\end{notice} - -\begin{seealso} - \seepep{0343}{The "with" statement} - {The specification, background, and examples for the - Python \keyword{with} statement.} -\end{seealso} - -\section{Function definitions\label{function}} -\indexii{function}{definition} -\stindex{def} - -A function definition defines a user-defined function object (see -section~\ref{types}): -\obindex{user-defined function} -\obindex{function} - -\begin{productionlist} - \production{funcdef} - {[\token{decorators}] "def" \token{funcname} "(" [\token{parameter_list}] ")" - ["->" \token{expression}]? - ":" \token{suite}} - \production{decorators} - {\token{decorator}+} - \production{decorator} - {"@" \token{dotted_name} ["(" [\token{argument_list} [","]] ")"] NEWLINE} - \production{dotted_name} - {\token{identifier} ("." \token{identifier})*} - \production{parameter_list} - {(\token{defparameter} ",")*} - \productioncont{(~~"*" [\token{parameter}] ("," \token{defparameter})*} - \productioncont{ [, "**" \token{parameter}]} - \productioncont{ | "**" \token{parameter}} - \productioncont{ | \token{defparameter} [","] )} - \production{parameter} - {\token{identifier} [":" \token{expression}]} - \production{defparameter} - {\token{parameter} ["=" \token{expression}]} - \production{funcname} - {\token{identifier}} -\end{productionlist} - -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. -\indexii{function}{name} -\indexii{name}{binding} - -The function definition does not execute the function body; this gets -executed only when the function is called. - -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: - -\begin{verbatim} -@f1(arg) -@f2 -def func(): pass -\end{verbatim} - -is equivalent to: - -\begin{verbatim} -def func(): pass -func = f1(arg)(f2(func)) -\end{verbatim} - -When one or more parameters have the form \var{parameter} -\code{=} \var{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 -``\code{*}'' must also have a default value --- this is a syntactic -restriction that is not expressed by the grammar. -\indexiii{default}{parameter}{value} - -\strong{Default parameter values are evaluated when the function -definition is executed.} This means that the expression is evaluated -once, when the function is defined, and that that 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 \code{None} as the default, and explicitly test for it in -the body of the function, e.g.: - -\begin{verbatim} -def whats_on_the_telly(penguin=None): - if penguin is None: - penguin = [] - penguin.append("property of the zoo") - return penguin -\end{verbatim} - -Function call semantics are described in more detail in -section~\ref{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 ``\code{*identifier}'' -is present, it is initialized to a tuple receiving any excess -positional parameters, defaulting to the empty tuple. If the form -``\code{**identifier}'' is present, it is initialized to a new -dictionary receiving any excess keyword arguments, defaulting to a -new empty dictionary. Parameters after ``\code{*}'' or ``\code{*identifier}'' -are keyword-only parameters and may only be passed used keyword arguments. - -Parameters may have annotations of the form ``\code{: expression}'' -following the parameter name. Any parameter may have an annotation even -those of the form \code{*identifier} or \code{**identifier}. -Functions may have ``return'' annotation of the form ``\code{-> 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 \member{__annotations__} -attribute of the function object. -\indexii{function}{annotations} - -It is also possible to create anonymous functions (functions not bound -to a name), for immediate use in expressions. This uses lambda forms, -described in section~\ref{lambda}. Note that the lambda form is -merely a shorthand for a simplified function definition; a function -defined in a ``\keyword{def}'' statement can be passed around or -assigned to another name just like a function defined by a lambda -form. The ``\keyword{def}'' form is actually more powerful since it -allows the execution of multiple statements and annotations. -\indexii{lambda}{form} - -\strong{Programmer's note:} Functions are first-class objects. A -``\code{def}'' form 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~\ref{naming} for details. - - -\section{Class definitions\label{class}} -\indexii{class}{definition} -\stindex{class} - -A class definition defines a class object (see section~\ref{types}): -\obindex{class} - -\begin{productionlist} - \production{classdef} - {"class" \token{classname} [\token{inheritance}] ":" - \token{suite}} - \production{inheritance} - {"(" [\token{expression_list}] ")"} - \production{classname} - {\token{identifier}} -\end{productionlist} - -A class definition is an executable statement. It first evaluates the -inheritance list, if present. Each item in the inheritance list -should evaluate to a class object or class type which allows -subclassing. The class's suite is then executed -in a new execution frame (see section~\ref{naming}), using a newly -created local namespace and the original global namespace. -(Usually, the suite contains only function definitions.) When the -class's suite finishes execution, its execution frame is discarded but -its local namespace is saved. 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. -\index{inheritance} -\indexii{class}{name} -\indexii{name}{binding} -\indexii{execution}{frame} - -\strong{Programmer's note:} Variables defined in the class definition -are class variables; they are shared by all instances. To define -instance variables, they must be given a value in the -\method{__init__()} method or in another method. Both class and -instance variables are accessible through the notation -``\code{self.name}'', and an instance variable hides a class variable -with the same name when accessed in this way. Class variables with -immutable values can be used as defaults for instance variables. -For new-style classes, descriptors can be used to create instance -variables with different implementation details. |