diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/ref/ref6.tex | 468 | ||||
| -rw-r--r-- | Doc/ref/ref7.tex | 347 | ||||
| -rw-r--r-- | Doc/ref/ref8.tex | 108 | ||||
| -rw-r--r-- | Doc/ref6.tex | 468 | ||||
| -rw-r--r-- | Doc/ref7.tex | 347 | ||||
| -rw-r--r-- | Doc/ref8.tex | 108 |
6 files changed, 1846 insertions, 0 deletions
diff --git a/Doc/ref/ref6.tex b/Doc/ref/ref6.tex new file mode 100644 index 0000000..cb257a3 --- /dev/null +++ b/Doc/ref/ref6.tex @@ -0,0 +1,468 @@ +\chapter{Simple statements} +\indexii{simple}{statement} + +Simple statements are comprised within a single logical line. +Several simple statements may occur on a single line separated +by semicolons. The syntax for simple statements is: + +\begin{verbatim} +simple_stmt: expression_stmt + | assignment_stmt + | pass_stmt + | del_stmt + | print_stmt + | return_stmt + | raise_stmt + | break_stmt + | continue_stmt + | import_stmt + | global_stmt +\end{verbatim} + +\section{Expression statements} +\indexii{expression}{statement} + +Expression statements are used (mostly interactively) to compute and +write a value, or (usually) to call a procedure (a function that +returns no meaningful result; in Python, procedures return the value +\verb\None\): + +\begin{verbatim} +expression_stmt: expression_list +\end{verbatim} + +An expression statement evaluates the expression list (which may be a +single expression). If the value is not \verb\None\, it is converted +to a string using the rules for string conversions (expressions in +reverse quotes), and the resulting string is written to standard +output (see section \ref{print}) on a line by itself. +\indexii{expression}{list} +\ttindex{None} +\indexii{string}{conversion} +\index{output} +\indexii{standard}{output} +\indexii{writing}{values} + +(The exception for \verb\None\ is made so that procedure calls, which +are syntactically equivalent to expressions, do not cause any output. +A tuple with only \verb\None\ items is written normally.) +\indexii{procedure}{call} + +\section{Assignment statements} +\indexii{assignment}{statement} + +Assignment statements are used to (re)bind names to values and to +modify attributes or items of mutable objects: +\indexii{binding}{name} +\indexii{rebinding}{name} +\obindex{mutable} +\indexii{attribute}{assignment} + +\begin{verbatim} +assignment_stmt: (target_list "=")+ expression_list +target_list: target ("," target)* [","] +target: identifier | "(" target_list ")" | "[" target_list "]" + | attributeref | subscription | slicing +\end{verbatim} + +(See section \ref{primaries} for the syntax definitions for the last +three symbols.) + +An assignment statement evaluates the expression list (remember that +this can be a single expression or a comma-separated list, the latter +yielding a tuple) and assigns the single resulting object to each of +the target lists, from left to right. +\indexii{expression}{list} + +Assignment is defined recursively depending on the form of the target +(list). When a target is part of a mutable object (an attribute +reference, subscription or slicing), the mutable object must +ultimately perform the assignment and decide about its validity, and +may raise an exception if the assignment is unacceptable. The rules +observed by various types and the exceptions raised are given with the +definition of the object types (see section \ref{types}). +\index{target} +\indexii{target}{list} + +Assignment of an object to a target list is recursively defined as +follows. +\indexiii{target}{list}{assignment} + +\begin{itemize} +\item +If the target list is a single target: the object is assigned to that +target. + +\item +If the target list is a comma-separated list of targets: the object +must be a tuple with the same number of items as the list contains +targets, and the items are assigned, from left to right, to the +corresponding targets. + +\end{itemize} + +Assignment of an object to a single target is recursively defined as +follows. + +\begin{itemize} % nested + +\item +If the target is an identifier (name): + +\begin{itemize} + +\item +If the name does not occur in a \verb\global\ statement in the current +code block: the name is bound to the object in the current local name +space. +\stindex{global} + +\item +Otherwise: the name is bound to the object in the current global name +space. + +\end{itemize} % nested + +The name is rebound if it was already bound. + +\item +If the target is a target list enclosed in parentheses: the object is +assigned to that target list as described above. + +\item +If the target is a target list enclosed in square brackets: the object +must be a list with the same number of items as the target list +contains targets, and its items are assigned, from left to right, to +the corresponding targets. + +\item +If the target is an attribute reference: The primary expression in the +reference is evaluated. It should yield an object with assignable +attributes; if this is not the case, \verb\TypeError\ is raised. That +object is then asked to assign the assigned object to the given +attribute; if it cannot perform the assignment, it raises an exception +(usually but not necessarily \verb\AttributeError\). +\indexii{attribute}{assignment} + +\item +If the target is a subscription: The primary expression in the +reference is evaluated. It should yield either a mutable sequence +(list) object or a mapping (dictionary) object. Next, the subscript +expression is evaluated. +\indexii{subscription}{assignment} +\obindex{mutable} + +If the primary is a mutable sequence object (a list), the subscript +must yield a plain integer. If it is negative, the sequence's length +is added to it. The resulting value must be a nonnegative integer +less than the sequence's length, and the sequence is asked to assign +the assigned object to its item with that index. If the index is out +of range, \verb\IndexError\ is raised (assignment to a subscripted +sequence cannot add new items to a list). +\obindex{sequence} +\obindex{list} + +If the primary is a mapping (dictionary) object, the subscript must +have a type compatible with the mapping's key type, and the mapping is +then asked to to create a key/datum pair which maps the subscript to +the assigned object. This can either replace an existing key/value +pair with the same key value, or insert a new key/value pair (if no +key with the same value existed). +\obindex{mapping} +\obindex{dictionary} + +\item +If the target is a slicing: The primary expression in the reference is +evaluated. It should yield a mutable sequence (list) object. The +assigned object should be a sequence object of the same type. Next, +the lower and upper bound expressions are evaluated, insofar they are +present; defaults are zero and the sequence's length. The bounds +should evaluate to (small) integers. If either bound is negative, the +sequence's length is added to it. The resulting bounds are clipped to +lie between zero and the sequence's length, inclusive. Finally, the +sequence object is asked to replace the items indicated by the slice +with the items of the assigned sequence. This may change the +sequence's length, if it allows it. +\indexii{slicing}{assignment} + +\end{itemize} + +(In the original implementation, the syntax for targets is taken +to be the same as for expressions, and invalid syntax is rejected +during the code generation phase, causing less detailed error +messages.) + +\section{The {\tt pass} statement} +\stindex{pass} + +\begin{verbatim} +pass_stmt: "pass" +\end{verbatim} + +\verb\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: +\indexii{null}{operation} + +\begin{verbatim} +def f(arg): pass # a function that does nothing (yet) + +class C: pass # an class with no methods (yet) +\end{verbatim} + +\section{The {\tt del} statement} +\stindex{del} + +\begin{verbatim} +del_stmt: "del" target_list +\end{verbatim} + +Deletion is recursively defined very similar to the way assignment is +defined. Rather that spelling it out in full details, here are some +hints. +\indexii{deletion}{target} +\indexiii{deletion}{target}{list} + +Deletion of a target list recursively deletes each target, from left +to right. + +Deletion of a name removes the binding of that name (which must exist) +from the local or global name space, depending on whether the name +occurs in a \verb\global\ statement in the same code block. +\stindex{global} +\indexii{unbinding}{name} + +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). +\indexii{attribute}{deletion} + +\section{The {\tt print} statement} \label{print} +\stindex{print} + +\begin{verbatim} +print_stmt: "print" [ condition ("," condition)* [","] ] +\end{verbatim} + +\verb\print\ evaluates each condition in turn and writes the resulting +object to standard output (see below). If an object is not a string, +it is first converted to a string using the rules for string +conversions. The (resulting or original) string is then written. A +space is written before each object is (converted and) written, unless +the output system believes it is positioned at the beginning of a +line. This is the case: (1) when no characters have yet been written +to standard output; or (2) when the last character written to standard +output is \verb/\n/; or (3) when the last write operation on standard +output was not a \verb\print\ statement. (In some cases it may be +functional to write an empty string to standard output for this +reason.) +\index{output} +\indexii{writing}{values} + +A \verb/"\n"/ character is written at the end, unless the \verb\print\ +statement ends with a comma. This is the only action if the statement +contains just the keyword \verb\print\. +\indexii{trailing}{comma} +\indexii{newline}{suppression} + +Standard output is defined as the file object named \verb\stdout\ +in the built-in module \verb\sys\. If no such object exists, +or if it is not a writable file, a \verb\RuntimeError\ exception is raised. +(The original implementation attempts to write to the system's original +standard output instead, but this is not safe, and should be fixed.) +\indexii{standard}{output} +\bimodindex{sys} +\ttindex{stdout} +\exindex{RuntimeError} + +\section{The {\tt return} statement} +\stindex{return} + +\begin{verbatim} +return_stmt: "return" [condition_list] +\end{verbatim} + +\verb\return\ may only occur syntactically nested in a function +definition, not within a nested class definition. +\indexii{function}{definition} +\indexii{class}{definition} + +If a condition list is present, it is evaluated, else \verb\None\ +is substituted. + +\verb\return\ leaves the current function call with the condition +list (or \verb\None\) as return value. + +When \verb\return\ passes control out of a \verb\try\ statement +with a \verb\finally\ clause, that finally clause is executed +before really leaving the function. +\kwindex{finally} + +\section{The {\tt raise} statement} +\stindex{raise} + +\begin{verbatim} +raise_stmt: "raise" condition ["," condition] +\end{verbatim} + +\verb\raise\ evaluates its first condition, which must yield +a string object. If there is a second condition, this is evaluated, +else \verb\None\ is substituted. +\index{exception} +\indexii{raising}{exception} + +It then raises the exception identified by the first object, +with the second one (or \verb\None\) as its parameter. + +\section{The {\tt break} statement} +\stindex{break} + +\begin{verbatim} +break_stmt: "break" +\end{verbatim} + +\verb\break\ may only occur syntactically nested in a \verb\for\ +or \verb\while\ loop, not nested in a function or class definition. +\stindex{for} +\stindex{while} +\indexii{loop}{statement} + +It terminates the neares enclosing loop, skipping the optional +\verb\else\ clause if the loop has one. +\kwindex{else} + +If a \verb\for\ loop is terminated by \verb\break\, the loop control +target keeps its current value. +\indexii{loop control}{target} + +When \verb\break\ passes control out of a \verb\try\ statement +with a \verb\finally\ clause, that finally clause is executed +before really leaving the loop. +\kwindex{finally} + +\section{The {\tt continue} statement} +\stindex{continue} + +\begin{verbatim} +continue_stmt: "continue" +\end{verbatim} + +\verb\continue\ may only occur syntactically nested in a \verb\for\ or +\verb\while\ loop, not nested in a function or class definition, and +not nested in the \verb\try\ clause of a \verb\try\ statement with a +\verb\finally\ clause (it may occur nested in a \verb\except\ or +\verb\finally\ clause of a \verb\try\ statement though). +\stindex{for} +\stindex{while} +\indexii{loop}{statement} +\kwindex{finally} + +It continues with the next cycle of the nearest enclosing loop. + +\section{The {\tt import} statement} \label{import} +\stindex{import} + +\begin{verbatim} +import_stmt: "import" identifier ("," identifier)* + | "from" identifier "import" identifier ("," identifier)* + | "from" identifier "import" "*" +\end{verbatim} + +Import statements are executed in two steps: (1) find a module, and +initialize it if necessary; (2) define a name or names in the local +name space (of the scope where the \verb\import\ statement occurs). +The first form (without \verb\from\) repeats these steps for each +identifier in the list, the \verb\from\ form performs them once, with +the first identifier specifying the module name. +\indexii{importing}{module} +\indexii{name}{binding} +\kwindex{from} + +The system maintains a table of modules that have been initialized, +indexed by module name. (The current implementation makes this table +accessible as \verb\sys.modules\.) When a module name is found in +this table, step (1) is finished. If not, a search for a module +definition is started. This first looks for a built-in module +definition, and if no built-in module if the given name is found, it +searches a user-specified list of directories for a file whose name is +the module name with extension \verb\".py"\. (The current +implementation uses the list of strings \verb\sys.path\ as the search +path; it is initialized from the shell environment variable +\verb\$PYTHONPATH\, with an installation-dependent default.) +\ttindex{modules} +\ttindex{sys.modules} +\indexii{module}{name} +\indexii{built-in}{module} +\indexii{user-defined}{module} +\bimodindex{sys} +\ttindex{path} +\ttindex{sys.path} +\indexii{filename}{extension} + +If a built-in module is found, its built-in initialization code is +executed and step (1) is finished. If no matching file is found, +\verb\ImportError\ is raised. If a file is found, it is parsed, +yielding an executable code block. If a syntax error occurs, +\verb\SyntaxError\ is raised. Otherwise, an empty module of the given +name is created and inserted in the module table, and then the code +block is executed in the context of this module. Exceptions during +this execution terminate step (1). +\indexii{module}{initialization} +\exindex{SyntaxError} +\exindex{ImportError} +\index{code block} + +When step (1) finishes without raising an exception, step (2) can +begin. + +The first form of \verb\import\ statement binds the module name in the +local name space to the module object, and then goes on to import the +next identifier, if any. The \verb\from\ from does not bind the +module name: it goes through the list of identifiers, looks each one +of them up in the module found in step (1), and binds the name in the +local name space to the object thus found. If a name is not found, +\verb\ImportError\ is raised. If the list of identifiers is replaced +by a star (\verb\*\), all names defined in the module are bound, +except those beginning with an underscore(\verb\_\). +\indexii{name}{binding} +\exindex{ImportError} + +Names bound by import statements may not occur in \verb\global\ +statements in the same scope. +\stindex{global} + +The \verb\from\ form with \verb\*\ may only occur in a module scope. +\kwindex{from} +\ttindex{from ... import *} + +(The current implementation does not enforce the latter two +restrictions, but programs should not abuse this freedom, as future +implementations may enforce them or silently change the meaning of the +program.) + +\section{The {\tt global} statement} \label{global} +\stindex{global} + +\begin{verbatim} +global_stmt: "global" identifier ("," identifier)* +\end{verbatim} + +The \verb\global\ statement is a declaration which holds for the +entire current scope. It means that the listed identifiers are to be +interpreted as globals. While {\em using} global names is automatic +if they are not defined in the local scope, {\em assigning} to global +names would be impossible without \verb\global\. +\indexiii{global}{name}{binding} + +Names listed in a \verb\global\ statement must not be used in the same +scope before that \verb\global\ statement is executed. + +Names listed in a \verb\global\ statement must not be defined as formal +parameters or in a \verb\for\ loop control target, \verb\class\ +definition, function definition, or \verb\import\ statement. + +(The current implementation does not enforce the latter two +restrictions, but programs should not abuse this freedom, as future +implementations may enforce them or silently change the meaning of the +program.) diff --git a/Doc/ref/ref7.tex b/Doc/ref/ref7.tex new file mode 100644 index 0000000..357bd5f --- /dev/null +++ b/Doc/ref/ref7.tex @@ -0,0 +1,347 @@ +\chapter{Compound statements} +\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 \verb\if\, \verb\while\ and \verb\for\ statements implement +traditional control flow constructs. \verb\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 \verb\if\ clause a following \verb\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 +\verb\print\ statements are executed: + +\begin{verbatim} +if x < y < z: print x; print y; print z +\end{verbatim} + +Summarizing: + +\begin{verbatim} +compound_stmt: if_stmt | while_stmt | for_stmt + | try_stmt | funcdef | classdef +suite: stmt_list NEWLINE | NEWLINE INDENT statement+ DEDENT +statement: stmt_list NEWLINE | compound_stmt +stmt_list: simple_stmt (";" simple_stmt)* [";"] +\end{verbatim} + +Note that statements always end in a \verb\NEWLINE\ possibly followed +by a \verb\DEDENT\. +\index{NEWLINE token} +\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 \verb\else\' problem is solved in Python by requiring +nested \verb\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 {\tt if} statement} +\stindex{if} + +The \verb\if\ statement is used for conditional execution: + +\begin{verbatim} +if_stmt: "if" condition ":" suite + ("elif" condition ":" suite)* + ["else" ":" suite] +\end{verbatim} + +It selects exactly one of the suites by evaluating the conditions 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 \verb\if\ statement is executed or evaluated). If +all conditions are false, the suite of the \verb\else\ clause, if +present, is executed. +\kwindex{elif} +\kwindex{else} + +\section{The {\tt while} statement} +\stindex{while} +\indexii{loop}{statement} + +The \verb\while\ statement is used for repeated execution as long as a +condition is true: + +\begin{verbatim} +while_stmt: "while" condition ":" suite + ["else" ":" suite] +\end{verbatim} + +This repeatedly tests the condition and, if it is true, executes the +first suite; if the condition is false (which may be the first time it +is tested) the suite of the \verb\else\ clause, if present, is +executed and the loop terminates. +\kwindex{else} + +A \verb\break\ statement executed in the first suite terminates the +loop without executing the \verb\else\ clause's suite. A +\verb\continue\ statement executed in the first suite skips the rest +of the suite and goes back to testing the condition. +\stindex{break} +\stindex{continue} + +\section{The {\tt for} statement} +\stindex{for} +\indexii{loop}{statement} + +The \verb\for\ statement is used to iterate over the elements of a +sequence (string, tuple or list): +\obindex{sequence} + +\begin{verbatim} +for_stmt: "for" target_list "in" condition_list ":" suite + ["else" ":" suite] +\end{verbatim} + +The condition list is evaluated once; it should yield a sequence. The +suite is then executed once for each item in the sequence, 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 \verb\else\ clause, if +present, is executed, and the loop terminates. +\kwindex{in} +\kwindex{else} +\indexii{target}{list} + +A \verb\break\ statement executed in the first suite terminates the +loop without executing the \verb\else\ clause's suite. A +\verb\continue\ statement executed in the first suite skips the rest +of the suite and continues with the next item, or with the \verb\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 \verb\range()\ returns a sequence of +integers suitable to emulate the effect of Pascal's \verb\for i := a +to b do\; e.g. \verb\range(3)\ returns the list \verb\[0, 1, 2]\. +\bifuncindex{range} +\index{Pascal} + +{\bf 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 {\tt try} statement} +\stindex{try} + +The \verb\try\ statement specifies exception handlers and/or cleanup +code for a group of statements: + +\begin{verbatim} +try_stmt: try_exc_stmt | try_fin_stmt +try_exc_stmt: "try" ":" suite + ("except" [condition ["," target]] ":" suite)+ +try_fin_stmt: "try" ":" suite + "finally" ":" suite +\end{verbatim} + +There are two forms of \verb\try\ statement: \verb\try...except\ and +\verb\try...finally\. These forms cannot be mixed. + +The \verb\try...except\ form specifies one or more exception handlers +(the \verb\except\ clauses). When no exception occurs in the +\verb\try\ clause, no exception handler is executed. When an +exception occurs in the \verb\try\ suite, a search for an exception +handler is started. This inspects the except clauses in turn until +one is found that matches the exception. A condition-less except +clause, if present, must be last; it matches any exception. For an +except clause with a condition, that condition 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 either the object that identifies the exception or it is a tuple +containing an item that is compatible with the exception. Note that +the object identities must match, i.e. it must be the same object, not +just an object 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. + +If the evaluation of a condition in the header of an except clause +raises an exception, the original search for a handler is cancelled +and a search starts for the new exception in the surrounding code and +on the call stack (it is treated as if the entire \verb\try\ statement +raised the exception). + +When a matching except clause is found, the exception's parameter is +assigned to the target specified in that except clause, if present, +and the except clause's suite is executed. When the end of this suite +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.) + +The \verb\try...finally\ form specifies a `cleanup' handler. The +\verb\try\ clause is executed. When no exception occurs, the +\verb\finally\ clause is executed. When an exception occurs in the +\verb\try\ clause, the exception is temporarily saved, the +\verb\finally\ clause is executed, and then the saved exception is +re-raised. If the \verb\finally\ clause raises another exception or +executes a \verb\return\, \verb\break\ or \verb\continue\ statement, +the saved exception is lost. +\kwindex{finally} + +When a \verb\return\ or \verb\break\ statement is executed in the +\verb\try\ suite of a \verb\try...finally\ statement, the +\verb\finally\ clause is also executed `on the way out'. A +\verb\continue\ statement is illegal in the \verb\try\ clause. (The +reason is a problem with the current implementation --- this +restriction may be lifted in the future). +\stindex{return} +\stindex{break} +\stindex{continue} + +\section{Function definitions} \label{function} +\indexii{function}{definition} + +A function definition defines a user-defined function object (see +section \ref{types}): +\obindex{user-defined function} +\obindex{function} + +\begin{verbatim} +funcdef: "def" funcname "(" [parameter_list] ")" ":" suite +parameter_list: (parameter ",")* ("*" identifier | parameter [","]) +sublist: parameter ("," parameter)* [","] +parameter: identifier | "(" sublist ")" +funcname: identifier +\end{verbatim} + +A function definition is an executable statement. Its execution binds +the function name in the current local name space to a function object +(a wrapper around the executable code for the function). This +function object contains a reference to the current global name space +as the global name space 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. + +Function call semantics are described in section \ref{calls}. When a +user-defined function is called, the arguments (a.k.a. actual +parameters) are bound to the (formal) parameters, as follows: +\indexii{function}{call} +\indexiii{user-defined}{function}{call} +\index{parameter} +\index{argument} +\indexii{parameter}{formal} +\indexii{parameter}{actual} + +\begin{itemize} + +\item +If there are no formal parameters, there must be no arguments. + +\item +If the formal parameter list does not end in a star followed by an +identifier, there must be exactly as many arguments as there are +parameters in the formal parameter list (at the top level); the +arguments are assigned to the formal parameters one by one. Note that +the presence or absence of a trailing comma at the top level in either +the formal or the actual parameter list makes no difference. The +assignment to a formal parameter is performed as if the parameter +occurs on the left hand side of an assignment statement whose right +hand side's value is that of the argument. + +\item +If the formal parameter list ends in a star followed by an identifier, +preceded by zero or more comma-followed parameters, there must be at +least as many arguments as there are parameters preceding the star. +Call this number {\em N}. The first {\em N} arguments are assigned to +the corresponding formal parameters in the way descibed above. A +tuple containing the remaining arguments, if any, is then assigned to +the identifier following the star. This variable will always be a +tuple: if there are no extra arguments, its value is \verb\()\, if +there is just one extra argument, it is a singleton tuple. +\indexii{variable length}{parameter list} + +\end{itemize} + +Note that the `variable length parameter list' feature only works at +the top level of the parameter list; individual parameters use a model +corresponding more closely to that of ordinary assignment. While the +latter model is generally preferable, because of the greater type +safety it offers (wrong-sized tuples aren't silently mistreated), +variable length parameter lists are a sufficiently accepted practice +in most programming languages that a compromise has been worked out. +(And anyway, assignment has no equivalent for empty argument lists.) + +\section{Class definitions} \label{class} +\indexii{class}{definition} + +A class definition defines a class object (see section \ref{types}): +\obindex{class} + +\begin{verbatim} +classdef: "class" classname [inheritance] ":" suite +inheritance: "(" [condition_list] ")" +classname: identifier +\end{verbatim} + +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. The class's suite is then executed +in a new execution frame (see section \ref{execframes}), using a newly +created local name space and the original global name space. +(Usually, the suite contains only function definitions.) When the +class's suite finishes execution, its execution frame is discarded but +its local name space is saved. A class object is then created using +the inheritance list for the base classes and the saved local name +space for the attribute dictionary. The class name is bound to this +class object in the original local name space. +\index{inheritance} +\indexii{class}{name} +\indexii{name}{binding} +\indexii{execution}{frame} diff --git a/Doc/ref/ref8.tex b/Doc/ref/ref8.tex new file mode 100644 index 0000000..59ef58c --- /dev/null +++ b/Doc/ref/ref8.tex @@ -0,0 +1,108 @@ +\chapter{Top-level components} + +The Python interpreter can get its input from a number of sources: +from a script passed to it as standard input or as program argument, +typed in interactively, from a module source file, etc. This chapter +gives the syntax used in these cases. +\index{interpreter} + +\section{Complete Python programs} +\index{program} + +While a language specification need not prescribe how the language +interpreter is invoked, it is useful to have a notion of a complete +Python program. A complete Python program is executed in a minimally +initialized environment: all built-in and standard modules are +available, but none have been initialized, except for \verb\sys\ +(various system services), \verb\builtin\ (built-in functions, +exceptions and \verb\None\) and \verb\__main__\. The latter is used +to provide the local and global name space for execution of the +complete program. +\bimodindex{sys} +\bimodindex{__main__} +\bimodindex{builtin} + +The syntax for a complete Python program is that for file input, +described in the next section. + +The interpreter may also be invoked in interactive mode; in this case, +it does not read and execute a complete program but reads and executes +one statement (possibly compound) at a time. The initial environment +is identical to that of a complete program; each statement is executed +in the name space of \verb\__main__\. +\index{interactive mode} + +Under {\UNIX}, a complete program can be passed to the interpreter in +three forms: with the {\bf -c} {\it string} command line option, as a +file passed as the first command line argument, or as standard input. +If the file or standard input is a tty device, the interpreter enters +interactive mode; otherwise, it executes the file as a complete +program. +\index{UNIX} +\index{command line} +\index{standard input} + +\section{File input} + +All input read from non-interactive files has the same form: + +\begin{verbatim} +file_input: (NEWLINE | statement)* +\end{verbatim} + +This syntax is used in the following situations: + +\begin{itemize} + +\item when parsing a complete Python program (from a file or from a string); + +\item when parsing a module; + +\item when parsing a string passed to \verb\exec()\; +\bifuncindex{exec} + +\item when parsing a file passed to \verb\execfile()\; +\bifuncindex{execfile} + +\end{itemize} + +\section{Interactive input} + +Input in interactive mode is parsed using the following grammar: + +\begin{verbatim} +interactive_input: [stmt_list] NEWLINE | compound_stmt NEWLINE +\end{verbatim} + +Note that a (top-level) compound statement must be followed by a blank +line in interactive mode; this is needed to help the parser detect the +end of the input. + +\section{Expression input} +\index{input} + +There are two forms of expression input. Both ignore leading +whitespace. + +The string argument to \verb\eval()\ must have the following form: +\bifuncindex{eval} + +\begin{verbatim} +eval_input: condition_list NEWLINE* +\end{verbatim} + +The input line read by \verb\input()\ must have the following form: +\bifuncindex{input} + +\begin{verbatim} +input_input: condition_list NEWLINE +\end{verbatim} + +Note: to read `raw' input line without interpretation, you can use the +built-in function \verb\raw_input()\ or the \verb\readline()\ method +of file objects. +\obindex{file} +\index{input!raw} +\index{raw input} +\bifuncindex{raw_index} +\ttindex{readline} diff --git a/Doc/ref6.tex b/Doc/ref6.tex new file mode 100644 index 0000000..cb257a3 --- /dev/null +++ b/Doc/ref6.tex @@ -0,0 +1,468 @@ +\chapter{Simple statements} +\indexii{simple}{statement} + +Simple statements are comprised within a single logical line. +Several simple statements may occur on a single line separated +by semicolons. The syntax for simple statements is: + +\begin{verbatim} +simple_stmt: expression_stmt + | assignment_stmt + | pass_stmt + | del_stmt + | print_stmt + | return_stmt + | raise_stmt + | break_stmt + | continue_stmt + | import_stmt + | global_stmt +\end{verbatim} + +\section{Expression statements} +\indexii{expression}{statement} + +Expression statements are used (mostly interactively) to compute and +write a value, or (usually) to call a procedure (a function that +returns no meaningful result; in Python, procedures return the value +\verb\None\): + +\begin{verbatim} +expression_stmt: expression_list +\end{verbatim} + +An expression statement evaluates the expression list (which may be a +single expression). If the value is not \verb\None\, it is converted +to a string using the rules for string conversions (expressions in +reverse quotes), and the resulting string is written to standard +output (see section \ref{print}) on a line by itself. +\indexii{expression}{list} +\ttindex{None} +\indexii{string}{conversion} +\index{output} +\indexii{standard}{output} +\indexii{writing}{values} + +(The exception for \verb\None\ is made so that procedure calls, which +are syntactically equivalent to expressions, do not cause any output. +A tuple with only \verb\None\ items is written normally.) +\indexii{procedure}{call} + +\section{Assignment statements} +\indexii{assignment}{statement} + +Assignment statements are used to (re)bind names to values and to +modify attributes or items of mutable objects: +\indexii{binding}{name} +\indexii{rebinding}{name} +\obindex{mutable} +\indexii{attribute}{assignment} + +\begin{verbatim} +assignment_stmt: (target_list "=")+ expression_list +target_list: target ("," target)* [","] +target: identifier | "(" target_list ")" | "[" target_list "]" + | attributeref | subscription | slicing +\end{verbatim} + +(See section \ref{primaries} for the syntax definitions for the last +three symbols.) + +An assignment statement evaluates the expression list (remember that +this can be a single expression or a comma-separated list, the latter +yielding a tuple) and assigns the single resulting object to each of +the target lists, from left to right. +\indexii{expression}{list} + +Assignment is defined recursively depending on the form of the target +(list). When a target is part of a mutable object (an attribute +reference, subscription or slicing), the mutable object must +ultimately perform the assignment and decide about its validity, and +may raise an exception if the assignment is unacceptable. The rules +observed by various types and the exceptions raised are given with the +definition of the object types (see section \ref{types}). +\index{target} +\indexii{target}{list} + +Assignment of an object to a target list is recursively defined as +follows. +\indexiii{target}{list}{assignment} + +\begin{itemize} +\item +If the target list is a single target: the object is assigned to that +target. + +\item +If the target list is a comma-separated list of targets: the object +must be a tuple with the same number of items as the list contains +targets, and the items are assigned, from left to right, to the +corresponding targets. + +\end{itemize} + +Assignment of an object to a single target is recursively defined as +follows. + +\begin{itemize} % nested + +\item +If the target is an identifier (name): + +\begin{itemize} + +\item +If the name does not occur in a \verb\global\ statement in the current +code block: the name is bound to the object in the current local name +space. +\stindex{global} + +\item +Otherwise: the name is bound to the object in the current global name +space. + +\end{itemize} % nested + +The name is rebound if it was already bound. + +\item +If the target is a target list enclosed in parentheses: the object is +assigned to that target list as described above. + +\item +If the target is a target list enclosed in square brackets: the object +must be a list with the same number of items as the target list +contains targets, and its items are assigned, from left to right, to +the corresponding targets. + +\item +If the target is an attribute reference: The primary expression in the +reference is evaluated. It should yield an object with assignable +attributes; if this is not the case, \verb\TypeError\ is raised. That +object is then asked to assign the assigned object to the given +attribute; if it cannot perform the assignment, it raises an exception +(usually but not necessarily \verb\AttributeError\). +\indexii{attribute}{assignment} + +\item +If the target is a subscription: The primary expression in the +reference is evaluated. It should yield either a mutable sequence +(list) object or a mapping (dictionary) object. Next, the subscript +expression is evaluated. +\indexii{subscription}{assignment} +\obindex{mutable} + +If the primary is a mutable sequence object (a list), the subscript +must yield a plain integer. If it is negative, the sequence's length +is added to it. The resulting value must be a nonnegative integer +less than the sequence's length, and the sequence is asked to assign +the assigned object to its item with that index. If the index is out +of range, \verb\IndexError\ is raised (assignment to a subscripted +sequence cannot add new items to a list). +\obindex{sequence} +\obindex{list} + +If the primary is a mapping (dictionary) object, the subscript must +have a type compatible with the mapping's key type, and the mapping is +then asked to to create a key/datum pair which maps the subscript to +the assigned object. This can either replace an existing key/value +pair with the same key value, or insert a new key/value pair (if no +key with the same value existed). +\obindex{mapping} +\obindex{dictionary} + +\item +If the target is a slicing: The primary expression in the reference is +evaluated. It should yield a mutable sequence (list) object. The +assigned object should be a sequence object of the same type. Next, +the lower and upper bound expressions are evaluated, insofar they are +present; defaults are zero and the sequence's length. The bounds +should evaluate to (small) integers. If either bound is negative, the +sequence's length is added to it. The resulting bounds are clipped to +lie between zero and the sequence's length, inclusive. Finally, the +sequence object is asked to replace the items indicated by the slice +with the items of the assigned sequence. This may change the +sequence's length, if it allows it. +\indexii{slicing}{assignment} + +\end{itemize} + +(In the original implementation, the syntax for targets is taken +to be the same as for expressions, and invalid syntax is rejected +during the code generation phase, causing less detailed error +messages.) + +\section{The {\tt pass} statement} +\stindex{pass} + +\begin{verbatim} +pass_stmt: "pass" +\end{verbatim} + +\verb\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: +\indexii{null}{operation} + +\begin{verbatim} +def f(arg): pass # a function that does nothing (yet) + +class C: pass # an class with no methods (yet) +\end{verbatim} + +\section{The {\tt del} statement} +\stindex{del} + +\begin{verbatim} +del_stmt: "del" target_list +\end{verbatim} + +Deletion is recursively defined very similar to the way assignment is +defined. Rather that spelling it out in full details, here are some +hints. +\indexii{deletion}{target} +\indexiii{deletion}{target}{list} + +Deletion of a target list recursively deletes each target, from left +to right. + +Deletion of a name removes the binding of that name (which must exist) +from the local or global name space, depending on whether the name +occurs in a \verb\global\ statement in the same code block. +\stindex{global} +\indexii{unbinding}{name} + +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). +\indexii{attribute}{deletion} + +\section{The {\tt print} statement} \label{print} +\stindex{print} + +\begin{verbatim} +print_stmt: "print" [ condition ("," condition)* [","] ] +\end{verbatim} + +\verb\print\ evaluates each condition in turn and writes the resulting +object to standard output (see below). If an object is not a string, +it is first converted to a string using the rules for string +conversions. The (resulting or original) string is then written. A +space is written before each object is (converted and) written, unless +the output system believes it is positioned at the beginning of a +line. This is the case: (1) when no characters have yet been written +to standard output; or (2) when the last character written to standard +output is \verb/\n/; or (3) when the last write operation on standard +output was not a \verb\print\ statement. (In some cases it may be +functional to write an empty string to standard output for this +reason.) +\index{output} +\indexii{writing}{values} + +A \verb/"\n"/ character is written at the end, unless the \verb\print\ +statement ends with a comma. This is the only action if the statement +contains just the keyword \verb\print\. +\indexii{trailing}{comma} +\indexii{newline}{suppression} + +Standard output is defined as the file object named \verb\stdout\ +in the built-in module \verb\sys\. If no such object exists, +or if it is not a writable file, a \verb\RuntimeError\ exception is raised. +(The original implementation attempts to write to the system's original +standard output instead, but this is not safe, and should be fixed.) +\indexii{standard}{output} +\bimodindex{sys} +\ttindex{stdout} +\exindex{RuntimeError} + +\section{The {\tt return} statement} +\stindex{return} + +\begin{verbatim} +return_stmt: "return" [condition_list] +\end{verbatim} + +\verb\return\ may only occur syntactically nested in a function +definition, not within a nested class definition. +\indexii{function}{definition} +\indexii{class}{definition} + +If a condition list is present, it is evaluated, else \verb\None\ +is substituted. + +\verb\return\ leaves the current function call with the condition +list (or \verb\None\) as return value. + +When \verb\return\ passes control out of a \verb\try\ statement +with a \verb\finally\ clause, that finally clause is executed +before really leaving the function. +\kwindex{finally} + +\section{The {\tt raise} statement} +\stindex{raise} + +\begin{verbatim} +raise_stmt: "raise" condition ["," condition] +\end{verbatim} + +\verb\raise\ evaluates its first condition, which must yield +a string object. If there is a second condition, this is evaluated, +else \verb\None\ is substituted. +\index{exception} +\indexii{raising}{exception} + +It then raises the exception identified by the first object, +with the second one (or \verb\None\) as its parameter. + +\section{The {\tt break} statement} +\stindex{break} + +\begin{verbatim} +break_stmt: "break" +\end{verbatim} + +\verb\break\ may only occur syntactically nested in a \verb\for\ +or \verb\while\ loop, not nested in a function or class definition. +\stindex{for} +\stindex{while} +\indexii{loop}{statement} + +It terminates the neares enclosing loop, skipping the optional +\verb\else\ clause if the loop has one. +\kwindex{else} + +If a \verb\for\ loop is terminated by \verb\break\, the loop control +target keeps its current value. +\indexii{loop control}{target} + +When \verb\break\ passes control out of a \verb\try\ statement +with a \verb\finally\ clause, that finally clause is executed +before really leaving the loop. +\kwindex{finally} + +\section{The {\tt continue} statement} +\stindex{continue} + +\begin{verbatim} +continue_stmt: "continue" +\end{verbatim} + +\verb\continue\ may only occur syntactically nested in a \verb\for\ or +\verb\while\ loop, not nested in a function or class definition, and +not nested in the \verb\try\ clause of a \verb\try\ statement with a +\verb\finally\ clause (it may occur nested in a \verb\except\ or +\verb\finally\ clause of a \verb\try\ statement though). +\stindex{for} +\stindex{while} +\indexii{loop}{statement} +\kwindex{finally} + +It continues with the next cycle of the nearest enclosing loop. + +\section{The {\tt import} statement} \label{import} +\stindex{import} + +\begin{verbatim} +import_stmt: "import" identifier ("," identifier)* + | "from" identifier "import" identifier ("," identifier)* + | "from" identifier "import" "*" +\end{verbatim} + +Import statements are executed in two steps: (1) find a module, and +initialize it if necessary; (2) define a name or names in the local +name space (of the scope where the \verb\import\ statement occurs). +The first form (without \verb\from\) repeats these steps for each +identifier in the list, the \verb\from\ form performs them once, with +the first identifier specifying the module name. +\indexii{importing}{module} +\indexii{name}{binding} +\kwindex{from} + +The system maintains a table of modules that have been initialized, +indexed by module name. (The current implementation makes this table +accessible as \verb\sys.modules\.) When a module name is found in +this table, step (1) is finished. If not, a search for a module +definition is started. This first looks for a built-in module +definition, and if no built-in module if the given name is found, it +searches a user-specified list of directories for a file whose name is +the module name with extension \verb\".py"\. (The current +implementation uses the list of strings \verb\sys.path\ as the search +path; it is initialized from the shell environment variable +\verb\$PYTHONPATH\, with an installation-dependent default.) +\ttindex{modules} +\ttindex{sys.modules} +\indexii{module}{name} +\indexii{built-in}{module} +\indexii{user-defined}{module} +\bimodindex{sys} +\ttindex{path} +\ttindex{sys.path} +\indexii{filename}{extension} + +If a built-in module is found, its built-in initialization code is +executed and step (1) is finished. If no matching file is found, +\verb\ImportError\ is raised. If a file is found, it is parsed, +yielding an executable code block. If a syntax error occurs, +\verb\SyntaxError\ is raised. Otherwise, an empty module of the given +name is created and inserted in the module table, and then the code +block is executed in the context of this module. Exceptions during +this execution terminate step (1). +\indexii{module}{initialization} +\exindex{SyntaxError} +\exindex{ImportError} +\index{code block} + +When step (1) finishes without raising an exception, step (2) can +begin. + +The first form of \verb\import\ statement binds the module name in the +local name space to the module object, and then goes on to import the +next identifier, if any. The \verb\from\ from does not bind the +module name: it goes through the list of identifiers, looks each one +of them up in the module found in step (1), and binds the name in the +local name space to the object thus found. If a name is not found, +\verb\ImportError\ is raised. If the list of identifiers is replaced +by a star (\verb\*\), all names defined in the module are bound, +except those beginning with an underscore(\verb\_\). +\indexii{name}{binding} +\exindex{ImportError} + +Names bound by import statements may not occur in \verb\global\ +statements in the same scope. +\stindex{global} + +The \verb\from\ form with \verb\*\ may only occur in a module scope. +\kwindex{from} +\ttindex{from ... import *} + +(The current implementation does not enforce the latter two +restrictions, but programs should not abuse this freedom, as future +implementations may enforce them or silently change the meaning of the +program.) + +\section{The {\tt global} statement} \label{global} +\stindex{global} + +\begin{verbatim} +global_stmt: "global" identifier ("," identifier)* +\end{verbatim} + +The \verb\global\ statement is a declaration which holds for the +entire current scope. It means that the listed identifiers are to be +interpreted as globals. While {\em using} global names is automatic +if they are not defined in the local scope, {\em assigning} to global +names would be impossible without \verb\global\. +\indexiii{global}{name}{binding} + +Names listed in a \verb\global\ statement must not be used in the same +scope before that \verb\global\ statement is executed. + +Names listed in a \verb\global\ statement must not be defined as formal +parameters or in a \verb\for\ loop control target, \verb\class\ +definition, function definition, or \verb\import\ statement. + +(The current implementation does not enforce the latter two +restrictions, but programs should not abuse this freedom, as future +implementations may enforce them or silently change the meaning of the +program.) diff --git a/Doc/ref7.tex b/Doc/ref7.tex new file mode 100644 index 0000000..357bd5f --- /dev/null +++ b/Doc/ref7.tex @@ -0,0 +1,347 @@ +\chapter{Compound statements} +\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 \verb\if\, \verb\while\ and \verb\for\ statements implement +traditional control flow constructs. \verb\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 \verb\if\ clause a following \verb\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 +\verb\print\ statements are executed: + +\begin{verbatim} +if x < y < z: print x; print y; print z +\end{verbatim} + +Summarizing: + +\begin{verbatim} +compound_stmt: if_stmt | while_stmt | for_stmt + | try_stmt | funcdef | classdef +suite: stmt_list NEWLINE | NEWLINE INDENT statement+ DEDENT +statement: stmt_list NEWLINE | compound_stmt +stmt_list: simple_stmt (";" simple_stmt)* [";"] +\end{verbatim} + +Note that statements always end in a \verb\NEWLINE\ possibly followed +by a \verb\DEDENT\. +\index{NEWLINE token} +\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 \verb\else\' problem is solved in Python by requiring +nested \verb\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 {\tt if} statement} +\stindex{if} + +The \verb\if\ statement is used for conditional execution: + +\begin{verbatim} +if_stmt: "if" condition ":" suite + ("elif" condition ":" suite)* + ["else" ":" suite] +\end{verbatim} + +It selects exactly one of the suites by evaluating the conditions 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 \verb\if\ statement is executed or evaluated). If +all conditions are false, the suite of the \verb\else\ clause, if +present, is executed. +\kwindex{elif} +\kwindex{else} + +\section{The {\tt while} statement} +\stindex{while} +\indexii{loop}{statement} + +The \verb\while\ statement is used for repeated execution as long as a +condition is true: + +\begin{verbatim} +while_stmt: "while" condition ":" suite + ["else" ":" suite] +\end{verbatim} + +This repeatedly tests the condition and, if it is true, executes the +first suite; if the condition is false (which may be the first time it +is tested) the suite of the \verb\else\ clause, if present, is +executed and the loop terminates. +\kwindex{else} + +A \verb\break\ statement executed in the first suite terminates the +loop without executing the \verb\else\ clause's suite. A +\verb\continue\ statement executed in the first suite skips the rest +of the suite and goes back to testing the condition. +\stindex{break} +\stindex{continue} + +\section{The {\tt for} statement} +\stindex{for} +\indexii{loop}{statement} + +The \verb\for\ statement is used to iterate over the elements of a +sequence (string, tuple or list): +\obindex{sequence} + +\begin{verbatim} +for_stmt: "for" target_list "in" condition_list ":" suite + ["else" ":" suite] +\end{verbatim} + +The condition list is evaluated once; it should yield a sequence. The +suite is then executed once for each item in the sequence, 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 \verb\else\ clause, if +present, is executed, and the loop terminates. +\kwindex{in} +\kwindex{else} +\indexii{target}{list} + +A \verb\break\ statement executed in the first suite terminates the +loop without executing the \verb\else\ clause's suite. A +\verb\continue\ statement executed in the first suite skips the rest +of the suite and continues with the next item, or with the \verb\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 \verb\range()\ returns a sequence of +integers suitable to emulate the effect of Pascal's \verb\for i := a +to b do\; e.g. \verb\range(3)\ returns the list \verb\[0, 1, 2]\. +\bifuncindex{range} +\index{Pascal} + +{\bf 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 {\tt try} statement} +\stindex{try} + +The \verb\try\ statement specifies exception handlers and/or cleanup +code for a group of statements: + +\begin{verbatim} +try_stmt: try_exc_stmt | try_fin_stmt +try_exc_stmt: "try" ":" suite + ("except" [condition ["," target]] ":" suite)+ +try_fin_stmt: "try" ":" suite + "finally" ":" suite +\end{verbatim} + +There are two forms of \verb\try\ statement: \verb\try...except\ and +\verb\try...finally\. These forms cannot be mixed. + +The \verb\try...except\ form specifies one or more exception handlers +(the \verb\except\ clauses). When no exception occurs in the +\verb\try\ clause, no exception handler is executed. When an +exception occurs in the \verb\try\ suite, a search for an exception +handler is started. This inspects the except clauses in turn until +one is found that matches the exception. A condition-less except +clause, if present, must be last; it matches any exception. For an +except clause with a condition, that condition 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 either the object that identifies the exception or it is a tuple +containing an item that is compatible with the exception. Note that +the object identities must match, i.e. it must be the same object, not +just an object 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. + +If the evaluation of a condition in the header of an except clause +raises an exception, the original search for a handler is cancelled +and a search starts for the new exception in the surrounding code and +on the call stack (it is treated as if the entire \verb\try\ statement +raised the exception). + +When a matching except clause is found, the exception's parameter is +assigned to the target specified in that except clause, if present, +and the except clause's suite is executed. When the end of this suite +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.) + +The \verb\try...finally\ form specifies a `cleanup' handler. The +\verb\try\ clause is executed. When no exception occurs, the +\verb\finally\ clause is executed. When an exception occurs in the +\verb\try\ clause, the exception is temporarily saved, the +\verb\finally\ clause is executed, and then the saved exception is +re-raised. If the \verb\finally\ clause raises another exception or +executes a \verb\return\, \verb\break\ or \verb\continue\ statement, +the saved exception is lost. +\kwindex{finally} + +When a \verb\return\ or \verb\break\ statement is executed in the +\verb\try\ suite of a \verb\try...finally\ statement, the +\verb\finally\ clause is also executed `on the way out'. A +\verb\continue\ statement is illegal in the \verb\try\ clause. (The +reason is a problem with the current implementation --- this +restriction may be lifted in the future). +\stindex{return} +\stindex{break} +\stindex{continue} + +\section{Function definitions} \label{function} +\indexii{function}{definition} + +A function definition defines a user-defined function object (see +section \ref{types}): +\obindex{user-defined function} +\obindex{function} + +\begin{verbatim} +funcdef: "def" funcname "(" [parameter_list] ")" ":" suite +parameter_list: (parameter ",")* ("*" identifier | parameter [","]) +sublist: parameter ("," parameter)* [","] +parameter: identifier | "(" sublist ")" +funcname: identifier +\end{verbatim} + +A function definition is an executable statement. Its execution binds +the function name in the current local name space to a function object +(a wrapper around the executable code for the function). This +function object contains a reference to the current global name space +as the global name space 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. + +Function call semantics are described in section \ref{calls}. When a +user-defined function is called, the arguments (a.k.a. actual +parameters) are bound to the (formal) parameters, as follows: +\indexii{function}{call} +\indexiii{user-defined}{function}{call} +\index{parameter} +\index{argument} +\indexii{parameter}{formal} +\indexii{parameter}{actual} + +\begin{itemize} + +\item +If there are no formal parameters, there must be no arguments. + +\item +If the formal parameter list does not end in a star followed by an +identifier, there must be exactly as many arguments as there are +parameters in the formal parameter list (at the top level); the +arguments are assigned to the formal parameters one by one. Note that +the presence or absence of a trailing comma at the top level in either +the formal or the actual parameter list makes no difference. The +assignment to a formal parameter is performed as if the parameter +occurs on the left hand side of an assignment statement whose right +hand side's value is that of the argument. + +\item +If the formal parameter list ends in a star followed by an identifier, +preceded by zero or more comma-followed parameters, there must be at +least as many arguments as there are parameters preceding the star. +Call this number {\em N}. The first {\em N} arguments are assigned to +the corresponding formal parameters in the way descibed above. A +tuple containing the remaining arguments, if any, is then assigned to +the identifier following the star. This variable will always be a +tuple: if there are no extra arguments, its value is \verb\()\, if +there is just one extra argument, it is a singleton tuple. +\indexii{variable length}{parameter list} + +\end{itemize} + +Note that the `variable length parameter list' feature only works at +the top level of the parameter list; individual parameters use a model +corresponding more closely to that of ordinary assignment. While the +latter model is generally preferable, because of the greater type +safety it offers (wrong-sized tuples aren't silently mistreated), +variable length parameter lists are a sufficiently accepted practice +in most programming languages that a compromise has been worked out. +(And anyway, assignment has no equivalent for empty argument lists.) + +\section{Class definitions} \label{class} +\indexii{class}{definition} + +A class definition defines a class object (see section \ref{types}): +\obindex{class} + +\begin{verbatim} +classdef: "class" classname [inheritance] ":" suite +inheritance: "(" [condition_list] ")" +classname: identifier +\end{verbatim} + +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. The class's suite is then executed +in a new execution frame (see section \ref{execframes}), using a newly +created local name space and the original global name space. +(Usually, the suite contains only function definitions.) When the +class's suite finishes execution, its execution frame is discarded but +its local name space is saved. A class object is then created using +the inheritance list for the base classes and the saved local name +space for the attribute dictionary. The class name is bound to this +class object in the original local name space. +\index{inheritance} +\indexii{class}{name} +\indexii{name}{binding} +\indexii{execution}{frame} diff --git a/Doc/ref8.tex b/Doc/ref8.tex new file mode 100644 index 0000000..59ef58c --- /dev/null +++ b/Doc/ref8.tex @@ -0,0 +1,108 @@ +\chapter{Top-level components} + +The Python interpreter can get its input from a number of sources: +from a script passed to it as standard input or as program argument, +typed in interactively, from a module source file, etc. This chapter +gives the syntax used in these cases. +\index{interpreter} + +\section{Complete Python programs} +\index{program} + +While a language specification need not prescribe how the language +interpreter is invoked, it is useful to have a notion of a complete +Python program. A complete Python program is executed in a minimally +initialized environment: all built-in and standard modules are +available, but none have been initialized, except for \verb\sys\ +(various system services), \verb\builtin\ (built-in functions, +exceptions and \verb\None\) and \verb\__main__\. The latter is used +to provide the local and global name space for execution of the +complete program. +\bimodindex{sys} +\bimodindex{__main__} +\bimodindex{builtin} + +The syntax for a complete Python program is that for file input, +described in the next section. + +The interpreter may also be invoked in interactive mode; in this case, +it does not read and execute a complete program but reads and executes +one statement (possibly compound) at a time. The initial environment +is identical to that of a complete program; each statement is executed +in the name space of \verb\__main__\. +\index{interactive mode} + +Under {\UNIX}, a complete program can be passed to the interpreter in +three forms: with the {\bf -c} {\it string} command line option, as a +file passed as the first command line argument, or as standard input. +If the file or standard input is a tty device, the interpreter enters +interactive mode; otherwise, it executes the file as a complete +program. +\index{UNIX} +\index{command line} +\index{standard input} + +\section{File input} + +All input read from non-interactive files has the same form: + +\begin{verbatim} +file_input: (NEWLINE | statement)* +\end{verbatim} + +This syntax is used in the following situations: + +\begin{itemize} + +\item when parsing a complete Python program (from a file or from a string); + +\item when parsing a module; + +\item when parsing a string passed to \verb\exec()\; +\bifuncindex{exec} + +\item when parsing a file passed to \verb\execfile()\; +\bifuncindex{execfile} + +\end{itemize} + +\section{Interactive input} + +Input in interactive mode is parsed using the following grammar: + +\begin{verbatim} +interactive_input: [stmt_list] NEWLINE | compound_stmt NEWLINE +\end{verbatim} + +Note that a (top-level) compound statement must be followed by a blank +line in interactive mode; this is needed to help the parser detect the +end of the input. + +\section{Expression input} +\index{input} + +There are two forms of expression input. Both ignore leading +whitespace. + +The string argument to \verb\eval()\ must have the following form: +\bifuncindex{eval} + +\begin{verbatim} +eval_input: condition_list NEWLINE* +\end{verbatim} + +The input line read by \verb\input()\ must have the following form: +\bifuncindex{input} + +\begin{verbatim} +input_input: condition_list NEWLINE +\end{verbatim} + +Note: to read `raw' input line without interpretation, you can use the +built-in function \verb\raw_input()\ or the \verb\readline()\ method +of file objects. +\obindex{file} +\index{input!raw} +\index{raw input} +\bifuncindex{raw_index} +\ttindex{readline} |