The Python Reference Manual.

1 files changed, 512 insertions, 0 deletions

diff --git a/Doc/ref6.tex b/Doc/ref6.tex
new file mode 100644
index 0000000..20c65f2
--- /dev/null
+++ b/Doc/ref6.tex
@@ -0,0 +1,512 @@
+\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
+              | exec_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
+\code{None}):
+
+\begin{verbatim}
+expression_stmt: condition_list
+\end{verbatim}
+
+An expression statement evaluates the condition list (which may be a
+single condition).
+\indexii{expression}{list}
+
+In interactive mode, if the value is not \code{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.
+(The exception for \code{None} is made so that procedure calls, which
+are syntactically equivalent to expressions, do not cause any output.)
+\ttindex{None}
+\indexii{string}{conversion}
+\index{output}
+\indexii{standard}{output}
+\indexii{writing}{values}
+\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 \keyword{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, \exception{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 \exception{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, \exception{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 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 object (e.g. a list).  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 slice with the items of the
+assigned sequence.  The length of the slice may be different from the
+length of the assigned sequence, thus changing the length of the
+target sequence, if the object allows it.
+\indexii{slicing}{assignment}
+
+\end{itemize}
+	
+(In the current 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.)
+
+WARNING: Although the definition of assignment implies that overlaps
+between the left-hand side and the right-hand side are `safe' (e.g.
+\verb@a, b = b, a@ swaps two variables), overlaps within the
+collection of assigned-to variables are not safe!  For instance, the
+following program prints \code@[0, 2]@:
+
+\begin{verbatim}
+x = [0, 1]
+i = 0
+i, x[i] = 1, 2
+print x
+\end{verbatim}
+
+
+\section{The {\tt pass} statement}
+\stindex{pass}
+
+\begin{verbatim}
+pass_stmt:      "pass"
+\end{verbatim}
+
+\keyword{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       # a 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 \keyword{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}
+
+\keyword{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 \keyword{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 \keyword{print}
+statement ends with a comma.  This is the only action if the statement
+contains just the keyword \keyword{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 \exception{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}
+\refbimodindex{sys}
+\ttindex{stdout}
+\exindex{RuntimeError}
+
+\section{The {\tt return} statement}
+\stindex{return}
+
+\begin{verbatim}
+return_stmt:    "return" [condition_list]
+\end{verbatim}
+
+\keyword{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 \code{None}
+is substituted.
+
+\keyword{return} leaves the current function call with the condition
+list (or \code{None}) as return value.
+
+When \keyword{return} passes control out of a \keyword{try} statement
+with a 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 ["," condition]]
+\end{verbatim}
+
+\keyword{raise} evaluates its first condition, which must yield
+a string, class, or instance object.  If there is a second condition,
+this is evaluated, else \code{None} is substituted.  If the first
+condition is a class object, then the second condition must be an
+instance of that class or one of its derivatives.  If the first
+condition is an instance object, the second condition must be
+\code{None}.
+\index{exception}
+\indexii{raising}{exception}
+
+If the first object is a class or string, it then raises the exception
+identified by the first object, with the second one (or \code{None})
+as its parameter.  If the first object is an instance, it raises the
+exception identified by the class of the object, with the instance as
+its parameter (and there should be no second object, or the second
+object should be \code{None}).
+
+If a third object is present, and it it not \code{None}, it should be
+a traceback object (see section \ref{traceback}), and it is
+substituted instead of the current location as the place where the
+exception occurred.  This is useful to re-raise an exception
+transparently in an except clause.
+\obindex{traceback}
+
+\section{The {\tt break} statement}
+\stindex{break}
+
+\begin{verbatim}
+break_stmt:     "break"
+\end{verbatim}
+
+\keyword{break} may only occur syntactically nested in a \keyword{for}
+or \keyword{while} loop, but not nested in a function or class definition
+within that loop.
+\stindex{for}
+\stindex{while}
+\indexii{loop}{statement}
+
+It terminates the nearest enclosing loop, skipping the optional
+else clause if the loop has one.
+\kwindex{else}
+
+If a \keyword{for} loop is terminated by \keyword{break}, the loop control
+target keeps its current value.
+\indexii{loop control}{target}
+
+When \keyword{break} passes control out of a \keyword{try} statement
+with a 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}
+
+\keyword{continue} may only occur syntactically nested in a \keyword{for} or
+\keyword{while} loop, but not nested in a function or class definition or
+\keyword{try} statement within that loop.\footnote{Except that it may
+currently occur within an {\tt except} clause.}
+\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 \keyword{import} statement occurs).
+The first form (without \keyword{from}) repeats these steps for each
+identifier in the list, the \keyword{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 \code{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 \file{.py}.  (The current
+implementation uses the list of strings \code{sys.path} as the search
+path; it is initialized from the shell environment variable
+\envvar{PYTHONPATH}, with an installation-dependent default.)
+\ttindex{modules}
+\ttindex{sys.modules}
+\indexii{module}{name}
+\indexii{built-in}{module}
+\indexii{user-defined}{module}
+\refbimodindex{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,
+\exception{ImportError} is raised.  If a file is found, it is parsed,
+yielding an executable code block.  If a syntax error occurs,
+\exception{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 \keyword{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 \keyword{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,
+\exception{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 \keyword{global}
+statements in the same scope.
+\stindex{global}
+
+The \keyword{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 \keyword{global} statement is a declaration which holds for the
+entire current code block.  It means that the listed identifiers are to be
+interpreted as globals.  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 \keyword{global}.
+\indexiii{global}{name}{binding}
+
+Names listed in a \keyword{global} statement must not be used in the same
+code block before that \keyword{global} statement is executed.
+
+Names listed in a \keyword{global} statement must not be defined as formal
+parameters or in a \keyword{for} loop control target, \keyword{class}
+definition, function definition, or \keyword{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.)
+
+Note: the \keyword{global} is a directive to the parser.  Therefore, it
+applies only to code parsed at the same time as the \keyword{global}
+statement.  In particular, a \keyword{global} statement contained in an
+\keyword{exec} statement does not affect the code block {\em containing}
+the \keyword{exec} statement, and code contained in an \keyword{exec}
+statement is unaffected by \keyword{global} statements in the code
+containing the \keyword{exec} statement.  The same applies to the
+\function{eval()}, \function{execfile()} and \function{compile()} functions.
+\stindex{exec}
+\bifuncindex{eval}
+\bifuncindex{execfile}
+\bifuncindex{compile}