Skip to content

C
cpython
Commit 5399d68c authored by Guido van Rossum's avatar Guido van Rossum
Browse files
Options

Changes copied from the FrameMaker version. Not too much.

parent 56c2013d
Hide whitespace changes
Inline Side-by-side
Showing with 112 additions and 108 deletions
Doc/ref/ref7.tex
View file @ 5399d68c
......@@ -11,8 +11,8 @@ traditional control flow constructs. \keyword{try} specifies exception
handlers and/or cleanup code for a group of statements. Function and
class definitions are also syntactically compound statements.
Compound statements consist of one or more `clauses'. A clause
consists of a header and a `suite'. The clause headers of a
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
......@@ -48,15 +48,13 @@ statement: stmt_list NEWLINE | compound_stmt
stmt_list: simple_stmt (";" simple_stmt)* [";"]
\end{verbatim}
Note that statements always end in a \code{NEWLINE} possibly followed
by a \code{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 \keyword{else}' problem is solved in Python by requiring
nested \keyword{if} statements to be indented).
Note that statements always end in a
\code{NEWLINE}\index{NEWLINE token} possibly followed by a
\code{DEDENT}.\index{DEDENT token} Also note that optional
continuation clauses always begin with a keyword that cannot start a
statement, thus there are no ambiguities (the `dangling
\keyword{else}' problem is solved in Python by requiring nested
\keyword{if} statements to be indented).
\indexii{dangling}{else}
The formatting of the grammar rules in the following sections places
......@@ -68,16 +66,16 @@ each clause on a separate line for clarity.
The \keyword{if} statement is used for conditional execution:
\begin{verbatim}
if_stmt: "if" condition ":" suite
("elif" condition ":" suite)*
if_stmt: "if" expression ":" suite
("elif" expression ":" suite)*
["else" ":" suite]
\end{verbatim}
It selects exactly one of the suites by evaluating the conditions one
It selects exactly one of the suites by evaluating the expressions one
by one until one is found to be true (see section \ref{Booleans} for
the definition of true and false); then that suite is executed (and no
other part of the \keyword{if} statement is executed or evaluated). If
all conditions are false, the suite of the \keyword{else} clause, if
all expressions are false, the suite of the \keyword{else} clause, if
present, is executed.
\kwindex{elif}
\kwindex{else}
......@@ -86,16 +84,16 @@ present, is executed.
\stindex{while}
\indexii{loop}{statement}
The \keyword{while} statement is used for repeated execution as long as a
condition is true:
The \keyword{while} statement is used for repeated execution as long
as an expression is true:
\begin{verbatim}
while_stmt: "while" condition ":" suite
while_stmt: "while" expression ":" 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
This repeatedly tests the expression and, if it is true, executes the
first suite; if the expression is false (which may be the first time it
is tested) the suite of the \keyword{else} clause, if present, is
executed and the loop terminates.
\kwindex{else}
......@@ -103,7 +101,7 @@ executed and the loop terminates.
A \keyword{break} statement executed in the first suite terminates the
loop without executing the \keyword{else} clause's suite. A
\keyword{continue} statement executed in the first suite skips the rest
of the suite and goes back to testing the condition.
of the suite and goes back to testing the expression.
\stindex{break}
\stindex{continue}
......@@ -116,11 +114,11 @@ sequence (string, tuple or list):
\obindex{sequence}
\begin{verbatim}
for_stmt: "for" target_list "in" condition_list ":" suite
for_stmt: "for" target_list "in" expression_list ":" suite
["else" ":" suite]
\end{verbatim}
The condition list is evaluated once; it should yield a sequence. The
The expression 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
......@@ -144,12 +142,10 @@ not affect the next item assigned to it.
The target list is not deleted when the loop is finished, but if the
sequence is empty, it will not have been assigned to at all by the
loop.
Hint: the built-in function \function{range()} returns a sequence of
integers suitable to emulate the effect of Pascal's
loop. Hint: the built-in function \function{range()} returns a
sequence of integers suitable to emulate the effect of Pascal's
\code{for i := a to b do};
e.g. \code{range(3)} returns the list \code{[0, 1, 2]}.
e.g., \code{range(3)} returns the list \code{[0, 1, 2]}.
\bifuncindex{range}
\indexii{Pascal}{language}
......@@ -164,7 +160,7 @@ 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.
copy using a slice of the whole sequence, e.g.,
\index{loop!over mutable sequence}
\index{mutable sequence!loop over}
......@@ -182,7 +178,7 @@ 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)+
("except" [expression ["," target]] ":" suite)+
["else" ":" suite]
try_fin_stmt: "try" ":" suite
"finally" ":" suite
......@@ -190,17 +186,18 @@ try_fin_stmt: "try" ":" suite
There are two forms of \keyword{try} statement:
\keyword{try}...\keyword{except} and
\keyword{try}...\keyword{finally}. These forms cannot be mixed.
\keyword{try}...\keyword{finally}. These forms cannot be mixed (but
they can be nested in each other).
The \keyword{try}...\keyword{except} form specifies one or more
exception handlers
(the \keyword{except} clauses). When no exception occurs in the
\keyword{try} clause, no exception handler is executed. When an
exception occurs in the \keyword{try} suite, a search for an exception
handler is started. This inspects the except clauses in turn until
one is found that matches the exception. A condition-less except
handler is started. This search inspects the except clauses in turn until
one is found that matches the exception. An expression-less except
clause, if present, must be last; it matches any exception. For an
except clause with a condition, that condition is evaluated, and the
except clause with an expression, that expression is evaluated, and the
clause matches the exception if the resulting object is ``compatible''
with the exception. An object is compatible with an exception if it
is either the object that identifies the exception, or (for exceptions
......@@ -213,7 +210,7 @@ object, not just an object with the same value.
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
If the evaluation of an expression 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 \keyword{try} statement
......@@ -234,6 +231,13 @@ exception are assigned to three variables in the \module{sys} module:
\code{sys.exc_traceback} receives a traceback object (see section
\ref{traceback}) identifying the point in the program where the
exception occurred.
These details are also available through the \function{sys.exc_info()}
function, which returns a tuple \code{(exc_type,} \code{exc_value,}
\code{exc_traceback)}. Use of the corresponding variables is
deprecated in favor of this function, since their use is unsafe in a
threaded program. As of Python 1.5, the variables are restored to
their previous values (before the call) when returning from a function
that handled an exception.
\refbimodindex{sys}
\ttindex{exc_type}
\ttindex{exc_value}
......@@ -252,12 +256,14 @@ The \keyword{try}...\keyword{finally} form specifies a `cleanup' handler. The
\keyword{finally} clause is executed, and then the saved exception is
re-raised. If the \keyword{finally} clause raises another exception or
executes a \keyword{return}, \keyword{break} or \keyword{continue} statement,
the saved exception is lost.
the saved exception is lost. The exception information is not
available to the program during execution of the \keyword{finally}
clause.
\kwindex{finally}
When a \keyword{return} or \keyword{break} statement is executed in the
\keyword{try} suite of a \keyword{try}...\keyword{finally} statement, the
\keyword{finally} clause is also executed `on the way out'. A
\keyword{finally} clause is also executed `on the way out.' A
\keyword{continue} statement is illegal in the \keyword{try} clause. (The
reason is a problem with the current implementation --- this
restriction may be lifted in the future).
......@@ -269,9 +275,7 @@ restriction may be lifted in the future).
\indexii{function}{definition}
A function definition defines a user-defined function object (see
section \ref{types}):\footnote{The new syntax to receive arbitrary
keyword arguments is not yet documented in this manual. See chapter
12 of the Tutorial.}
section \ref{types}):
\obindex{user-defined function}
\obindex{function}
......@@ -280,90 +284,81 @@ funcdef: "def" funcname "(" [parameter_list] ")" ":" suite
parameter_list: (defparameter ",")* ("*" identifier [, "**" identifier]
| "**" identifier
| defparameter [","])
defparameter: parameter ["=" condition]
defparameter: parameter ["=" expression]
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
the function name in the current local namespace to a function object
(a wrapper around the executable code for the function). This
function object contains a reference to the current global name space
as the global name space to be used when the function is called.
function object contains a reference to the current global namespace
as the global namespace to be used when the function is called.
\indexii{function}{name}
\indexii{name}{binding}
The function definition does not execute the function body; this gets
executed only when the function is called.
When one or more top-level parameters have the form \var{parameter \code{=}
condition}, the function is said to have ``default parameter values''.
Default parameter values are evaluated when the function definition is
executed. For a parameter with a default value, the correponding
argument may be omitted from a call, in which case the parameter's
default value is substituted. If a parameter has a default value, all
following parameters must also have a default value --- this is a
syntactic restriction that is not expressed by the grammar.%
When one or more top-level parameters have the form \var{parameter}
\code{=} \var{expression}, the function is said to have ``default
parameter values.'' \strong{Default parameter values are evaluated
when the function definition is executed.} For a parameter with a
default value, the corresponding argument may be omitted from a call,
in which case the parameter's default value is substituted. If a
parameter has a default value, all following parameters must also have
a default value --- this is a syntactic restriction that is not
expressed by the grammar.%
\footnote{Currently this is not checked; instead,
\code{def f(a=1, b)} is interpreted as \code{def f(a=1, b=None)}.}
\indexiii{default}{parameter}{value}
Function call semantics are described in section \ref{calls}. When a
user-defined function is called, first missing arguments for which a
default value exists are supplied; then 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 \var{N}. The first \var{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 \code{()}, 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.)
Function call semantics are described in more detail in section
\ref{calls}.
A function call always assigns values to all parameters mentioned in
the parameter list, either from position arguments, from keyword
arguments, or from default values. If the form ``\code{*identifier}''
is present, it is initialized to a tuple receiving any excess
positional parameters, defaulting to the empty tuple. If the form
``\code{**identifier}'' is present, it is initialized to a new
dictionary receiving any excess keyword arguments, defaulting to a
new empty dictionary.
It is also possible to create anonymous functions (functions not bound
to a name), for immediate use in expressions. This uses lambda forms,
described in section \ref{lambda}.
described in section \ref{lambda}. Note that the lambda form is
merely a shorthand for a simplified function definition; a function
defined in a ``\keyword{def}'' statement can be passed around or
assigned to another name just like a function defined by a lambda
form. The ``\keyword{def}'' form is actually more powerful since it
allows the execution of multiple statements.
\indexii{lambda}{form}
\strong{Programmer's note:} a ``\code{def}'' form executed inside a
function definition defines a local function that can be returned or
passed around. Because of Python's two-scope philosophy, a local
function defined in this way does not have access to the local
variables of the function that contains its definition; the same rule
applies to functions defined by a lambda form. A standard trick to
pass selected local variables into a locally defined function is to
use default argument values, like this:
\begin{verbatim}
# Return a function that returns its argument incremented by 'n'
def make_incrementer(n):
def increment(x, n=n):
return x+n
return increment
add1 = make_incrementer(1)
print add1(3) # This prints '4'
\end{verbatim}
\section{Class definitions} \label{class}
\indexii{class}{definition}
......@@ -372,7 +367,7 @@ A class definition defines a class object (see section \ref{types}):
\begin{verbatim}
classdef: "class" classname [inheritance] ":" suite
inheritance: "(" [condition_list] ")"
inheritance: "(" [expression_list] ")"
classname: identifier
\end{verbatim}
......@@ -380,14 +375,23 @@ 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.
created local namespace and the original global namespace.
(Usually, the suite contains only function definitions.) When the
class's suite finishes execution, its execution frame is discarded but
its local 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.
its local namespace is saved. A class object is then created using
the inheritance list for the base classes and the saved local
namespace for the attribute dictionary. The class name is bound to this
class object in the original local namespace.
\index{inheritance}
\indexii{class}{name}
\indexii{name}{binding}
\indexii{execution}{frame}
\strong{Programmer's note:} variables defined in the class definition
are class variables; they are shared by all instances. To define
instance variables, they must be given a value in the the
\method{__init__()} method or in another method. Both class and
instance variables are accessible through the notation
```code{self.name}'', and an instance variable hides a class variable
with the same name when accessed in this way. Class variables with
immutable values can be used as defaults for instance variables.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7