summaryrefslogtreecommitdiffstats
path: root/Doc/ref/ref6.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Doc/ref/ref6.tex')
-rw-r--r--Doc/ref/ref6.tex224
1 files changed, 141 insertions, 83 deletions
diff --git a/Doc/ref/ref6.tex b/Doc/ref/ref6.tex
index 80e9a71..1c5f332 100644
--- a/Doc/ref/ref6.tex
+++ b/Doc/ref/ref6.tex
@@ -7,6 +7,7 @@ by semicolons. The syntax for simple statements is:
\begin{verbatim}
simple_stmt: expression_stmt
+ | assert_stmt
| assignment_stmt
| pass_stmt
| del_stmt
@@ -26,22 +27,23 @@ simple_stmt: expression_stmt
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}):
+\code{None}). Other uses of expression statements are allowed and
+occasionally useful. The syntax for an expression statement is:
\begin{verbatim}
-expression_stmt: condition_list
+expression_stmt: expression_list
\end{verbatim}
-An expression statement evaluates the condition list (which may be a
-single condition).
+An expression statement evaluates the expression list (which may be a
+single expression).
\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.)
+to a string using the built-in \function{repr()}\bifuncindex{repr}
+function and the resulting string is written to standard output (see
+section \ref{print}) on a line by itself. (Expression statements
+yielding None are not written, so that procedure calls do not cause
+any output.)
\ttindex{None}
\indexii{string}{conversion}
\index{output}
@@ -49,6 +51,41 @@ are syntactically equivalent to expressions, do not cause any output.)
\indexii{writing}{values}
\indexii{procedure}{call}
+\section{Assert statements}\stindex{assert}
+
+Assert statements are a convenient way to insert debugging
+assertions\indexii{debugging}{assertions} into a program:
+
+\begin{verbatim}
+assert_statement: "assert" expression ["," expression]
+\end{verbatim}
+
+The simple form, ``\code{assert expression}'', is equivalent to
+
+\begin{verbatim}
+if __debug__:
+ if not expression: raise AssertionError
+\end{verbatim}
+
+The extended form, ``\code{assert expression1, expression2}'', is
+equivalent to
+
+\begin{verbatim}
+if __debug__:
+ if not expression1: raise AssertionError, expression2
+\end{verbatim}
+
+These equivalences assume that \code{__debug__}\ttindex{__debug__} and
+\code{AssertionError}\exindex{AssertionError} refer to the built-in
+variables with those names. In the current implementation, the
+built-in variable \code{__debug__} is 1 under normal circumstances, 0
+when optimization is requested (command line option -O). The current
+code generator emits no code for an assert statement when optimization
+is requested at compile time. Note that it is unnecessary to include
+the source code for the expression that failed in the error message;
+it will be displayed as part of the stack trace.
+
+
\section{Assignment statements}
\indexii{assignment}{statement}
@@ -91,14 +128,17 @@ follows.
\begin{itemize}
\item
-If the target list is a single target: the object is assigned to that
+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.
+If the target list is a comma-separated list of targets: The object
+must be a sequence with the same number of items as the there are
+targets in the target list, and the items are assigned, from left to
+right, to the corresponding targets. (This rule is relaxed as of
+Python 1.5; in earlier versions, the object had to be a tuple. Since
+strings are sequences, an assignment like ``\code{a, b = "xy"}'' is
+now legal as long as the string has the right length.)
\end{itemize}
@@ -114,27 +154,26 @@ If the target is an identifier (name):
\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.
+code block: the name is bound to the object in the current local
+namespace.
\stindex{global}
\item
-Otherwise: the name is bound to the object in the current global name
-space.
+Otherwise: the name is bound to the object in the current global
+namespace.
\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.
+The name is rebound if it was already bound. This may cause the
+reference count for the object previously bound to the name to reach
+zero, causing the object to be deallocated and its
+destructor\index{destructor} (if it has one) to be called.
\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.
+If the target is a target list enclosed in parentheses or in square
+brackets: The object must be a sequence with the same number of items
+as there are targets in the target list, 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
@@ -148,12 +187,12 @@ attribute; if it cannot perform the assignment, it raises an exception
\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.
+object (e.g., a list) or a mapping object (e.g., a dictionary). Next,
+the subscript expression is evaluated.
\indexii{subscription}{assignment}
\obindex{mutable}
-If the primary is a mutable sequence object (a list), the subscript
+If the primary is a mutable sequence object (e.g., 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
@@ -163,7 +202,7 @@ sequence cannot add new items to a list).
\obindex{sequence}
\obindex{list}
-If the primary is a mapping (dictionary) object, the subscript must
+If the primary is a mapping object (e.g., a dictionary), 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
@@ -174,7 +213,7 @@ key with the same value existed).
\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
+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
@@ -195,10 +234,10 @@ 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.
-\code{a, b = b, a} swaps two variables), overlaps within the
+between the left-hand side and the right-hand side are `safe' (e.g.,
+``\code{a, b = b, a}'' swaps two variables), overlaps \emph{within} the
collection of assigned-to variables are not safe! For instance, the
-following program prints \code{[0, 2]}:
+following program prints ``\code{[0, 2]}'':
\begin{verbatim}
x = [0, 1]
@@ -243,7 +282,7 @@ 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
+from the local or global namespace, depending on whether the name
occurs in a \keyword{global} statement in the same code block.
\stindex{global}
\indexii{unbinding}{name}
@@ -258,18 +297,18 @@ right type (but even this is determined by the sliced object).
\stindex{print}
\begin{verbatim}
-print_stmt: "print" [ condition ("," condition)* [","] ]
+print_stmt: "print" [ expression ("," expression)* [","] ]
\end{verbatim}
-\keyword{print} evaluates each condition in turn and writes the resulting
+\keyword{print} evaluates each expression 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 \character{\\n}; or (3) when the last write operation on standard
+line. This is the case (1) when no characters have yet been written
+to standard output, (2) when the last character written to standard
+output is \character{\\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.)
@@ -283,10 +322,9 @@ contains just the keyword \keyword{print}.
\indexii{newline}{suppression}
Standard output is defined as the file object named \code{stdout}
-in the built-in module \module{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.)
+in the built-in module \module{sys}. If no such object exists, or if
+it does not have a \method{write()} method, a \exception{RuntimeError}
+exception is raised.
\indexii{standard}{output}
\refbimodindex{sys}
\ttindex{stdout}
@@ -296,7 +334,7 @@ standard output instead, but this is not safe, and should be fixed.)
\stindex{return}
\begin{verbatim}
-return_stmt: "return" [condition_list]
+return_stmt: "return" [expression_list]
\end{verbatim}
\keyword{return} may only occur syntactically nested in a function
@@ -304,14 +342,14 @@ 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}
+If an expression list is present, it is evaluated, else \code{None}
is substituted.
-\keyword{return} leaves the current function call with the condition
+\keyword{return} leaves the current function call with the expression
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
+with a \keyword{finally} clause, that \keyword{finally} clause is executed
before really leaving the function.
\kwindex{finally}
@@ -319,15 +357,18 @@ before really leaving the function.
\stindex{raise}
\begin{verbatim}
-raise_stmt: "raise" condition ["," condition ["," condition]]
+raise_stmt: "raise" [expression ["," expression ["," expression]]]
\end{verbatim}
-\keyword{raise} evaluates its first condition, which must yield
-a string, class, or instance object. If there is a second condition,
+If no expressions are present, \keyword{raise} re-raises the last
+expression that was raised in the current scope.
+
+Otherwose, \keyword{raise} evaluates its first expression, which must yield
+a string, class, or instance object. If there is a second expression,
this is evaluated, else \code{None} is substituted. If the first
-condition is a class object, then the second condition must be an
+expression is a class object, then the second expression 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
+expression is an instance object, the second expression must be
\code{None}.
\index{exception}
\indexii{raising}{exception}
@@ -339,7 +380,7 @@ 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
+If a third object is present, and it is 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
@@ -361,7 +402,7 @@ within that loop.
\indexii{loop}{statement}
It terminates the nearest enclosing loop, skipping the optional
-else clause if the loop has one.
+\keyword{else} clause if the loop has one.
\kwindex{else}
If a \keyword{for} loop is terminated by \keyword{break}, the loop control
@@ -369,7 +410,7 @@ 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
+with a \keyword{finally} clause, that \keyword{finally} clause is executed
before really leaving the loop.
\kwindex{finally}
@@ -382,45 +423,45 @@ continue_stmt: "continue"
\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 except clause.}
+\keyword{try} statement within that loop.\footnote{It may
+occur within an \keyword{except} or \keyword{else} clause. The
+restriction on occurring in the \keyword{try} clause is implementer's
+laziness and will eventually be lifted.}
+It continues with the next cycle of the nearest enclosing loop.
\stindex{for}
\stindex{while}
\indexii{loop}{statement}
\kwindex{finally}
-It continues with the next cycle of the nearest enclosing loop.
-
\section{The \keyword{import} statement} \label{import}
\stindex{import}
\begin{verbatim}
-import_stmt: "import" identifier ("," identifier)*
- | "from" identifier "import" identifier ("," identifier)*
- | "from" identifier "import" "*"
+import_stmt: "import" module ("," module)*
+ | "from" module "import" identifier ("," identifier)*
+ | "from" module "import" "*"
+module: (identifier ".")* identifier
\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).
+namespace (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.
+identifier in the list. The form with \keyword{from} performs step
+(1) once, and then performs step (2) repeatedly.
\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
+indexed by module name. This table 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.)
+definition is started. When a module is found, it is loaded. Details
+of the module searching and loading process are implementation and
+platform specific. It generally involves searching for a ``built-in''
+module with the given name and then searching a list of locations
+given as \code{sys.path}.
\ttindex{modules}
\ttindex{sys.modules}
\indexii{module}{name}
@@ -447,19 +488,19 @@ 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
+local namespace to the module object, and then goes on to import the
+next identifier, if any. The \keyword{from} form 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,
+local namespace 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 (\code{*}), all names defined in the module are bound,
except those beginning with an underscore(\code{_}).
\indexii{name}{binding}
\exindex{ImportError}
-Names bound by import statements may not occur in \keyword{global}
-statements in the same scope.
+Names bound by \keyword{import} statements may not occur in
+\keyword{global} statements in the same scope.
\stindex{global}
The \keyword{from} form with \code{*} may only occur in a module scope.
@@ -471,6 +512,21 @@ restrictions, but programs should not abuse this freedom, as future
implementations may enforce them or silently change the meaning of the
program.)
+\strong{Hierarchical module names:}\indexiii{hierarchical}{module names}
+when the module names contains one or more dots, the module search
+path is carried out differently. The sequence of identifiers up to
+the last dot is used to find a ``package''\index{packages}; the final
+identifier is then searched inside the package. A package is
+generally a subdirectory of a directory on \code{sys.path} that has a
+file \file{__init__.py}.\ttindex{__init__.py}
+%
+[XXX Can't be bothered to spell this out right now; see the URL
+http://www.python.org/doc/essays/packages.html for more details, also
+about how the module search works from inside a package.]
+
+[XXX Also should mention __import__().]
+\bifuncindex{__import__}
+
\section{The \keyword{global} statement} \label{global}
\stindex{global}
@@ -497,7 +553,8 @@ 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
+\strong{Programmer's note:}
+the \keyword{global} is a directive to the parser. 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 \emph{containing}
@@ -539,7 +596,8 @@ may add a reference to the dictionary of the built-in module
\ttindex{__builtins__}
\refbimodindex{__builtin__}
-Hints: dynamic evaluation of expressions is supported by the built-in
+\strong{Programmer's hints:}
+dynamic evaluation of expressions is supported by the built-in
function \function{eval()}. The built-in functions
\function{globals()} and \function{locals()} return the current global
and local dictionary, respectively, which may be useful to pass around