# [Python-checkins] python/dist/src/Doc/ref ref1.tex, 1.14, 1.14.8.1 ref2.tex, 1.37.2.2, 1.37.2.3 ref3.tex, 1.92.2.2, 1.92.2.3 ref4.tex, 1.33.2.2, 1.33.2.3 ref5.tex, 1.64.2.2, 1.64.2.3 ref6.tex, 1.55.2.2, 1.55.2.3 ref7.tex, 1.34.2.2, 1.34.2.3

jhylton@users.sourceforge.net jhylton at users.sourceforge.net
Sun Oct 16 07:24:32 CEST 2005

Update of /cvsroot/python/python/dist/src/Doc/ref
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv27718/Doc/ref

Modified Files:
Tag: ast-branch
ref1.tex ref2.tex ref3.tex ref4.tex ref5.tex ref6.tex ref7.tex
Log Message:
Merge head to branch (for the last time)

Index: ref1.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/ref/ref1.tex,v
retrieving revision 1.14
retrieving revision 1.14.8.1
diff -u -d -r1.14 -r1.14.8.1
--- ref1.tex	28 Nov 2001 07:26:15 -0000	1.14
+++ ref1.tex	16 Oct 2005 05:23:58 -0000	1.14.8.1
@@ -21,7 +21,7 @@
reference document --- the implementation may change, and other
implementations of the same language may work differently.  On the
other hand, there is currently only one Python implementation in
-widespread use (although a second one now exists!), and
+widespread use (although alternate implementations exist), and
its particular quirks are sometimes worth being mentioned, especially
where the implementation imposes additional limitations.  Therefore,
you'll find short implementation notes'' sprinkled throughout the
@@ -34,6 +34,56 @@
with the language definition.

+\section{Alternate Implementations\label{implementations}}
+
+Though there is one Python implementation which is by far the most
+popular, there are some alternate implementations which are of
+particular interest to different audiences.
+
+Known implementations include:
+
+\begin{itemize}
+\item[CPython]
+This is the original and most-maintained implementation of Python,
+written in C.  New language features generally appear here first.
+
+\item[Jython]
+Python implemented in Java.  This implementation can be used as a
+scripting language for Java applications, or can be used to create
+applications using the Java class libraries.  It is also often used to
+
+\item[Python for .NET]
+This implementation actually uses the CPython implementation, but is a
+managed .NET application and makes .NET libraries available.  This was
+
+\item[IronPython]
+An alternate Python for\ .NET.  Unlike Python.NET, this is a complete
+Python implementation that generates IL, and compiles Python code
+directly to\ .NET assemblies.  It was created by Jim Hugunin, the
+IronPython website}{http://workspaces.gotdotnet.com/ironpython}.
+
+\item[PyPy]
+An implementation of Python written in Python; even the bytecode
+interpreter is written in Python.  This is executed using CPython as
+the underlying interpreter.  One of the goals of the project is to
+encourage experimentation with the language itself by making it easier
+to modify the interpreter (since it is written in Python).  Additional
+information is available on \ulink{the PyPy project's home
+page}{http://codespeak.net/pypy/}.
+\end{itemize}
+
+Each of these implementations varies in some way from the language as
+documented in this manual, or introduces specific information beyond
+what's covered in the standard Python documentation.  Please refer to
+the implementation-specific documentation to determine what else you
+need to know about the specific implementation you're using.
+
+
\section{Notation\label{notation}}

The descriptions of lexical analysis and syntax use a modified BNF
@@ -43,10 +93,10 @@
\index{syntax}
\index{notation}

-\begin{verbatim}
-name:           lc_letter (lc_letter | "_")*
-lc_letter:      "a"..."z"
-\end{verbatim}
+\begin{productionlist}
+  \production{name}{\token{lc_letter} (\token{lc_letter} | "_")*}
+  \production{lc_letter}{"a"..."z"}
+\end{productionlist}

The first line says that a \code{name} is an \code{lc_letter} followed by
a sequence of zero or more \code{lc_letter}s and underscores.  An
@@ -55,7 +105,7 @@
names defined in lexical and grammar rules in this document.)

Each rule begins with a name (which is the name defined by the rule)
-and a colon.  A vertical bar (\code{|}) is used to separate
+and \code{::=}.  A vertical bar (\code{|}) is used to separate
alternatives; it is the least binding operator in this notation.  A
star (\code{*}) means zero or more repetitions of the preceding item;
likewise, a plus (\code{+}) means one or more repetitions, and a

Index: ref2.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/ref/ref2.tex,v
retrieving revision 1.37.2.2
retrieving revision 1.37.2.3
diff -u -d -r1.37.2.2 -r1.37.2.3
--- ref2.tex	7 Jan 2005 06:57:33 -0000	1.37.2.2
+++ ref2.tex	16 Oct 2005 05:23:58 -0000	1.37.2.3
@@ -54,11 +54,18 @@

\subsection{Physical lines\label{physical}}

-A physical line ends in whatever the current platform's convention is
-for terminating lines.  On \UNIX, this is the \ASCII{} LF (linefeed)
-character.  On Windows, it is the \ASCII{} sequence CR LF (return
-followed by linefeed).  On Macintosh, it is the \ASCII{} CR (return)
-character.
+A physical line is a sequence of characters terminated by an end-of-line
+sequence.  In source files, any of the standard platform line
+termination sequences can be used - the \UNIX form using \ASCII{} LF
+(linefeed), the Windows form using the \ASCII{} sequence CR LF (return
+followed by linefeed), or the Macintosh form using the \ASCII{} CR
+(return) character.  All of these forms can be used equally, regardless
+of platform.
+
+When embedding Python, source code strings should be passed to Python
+APIs using the standard C conventions for newline characters (the
+\code{\e n} character, representing \ASCII{} LF, is the line
+terminator).

@@ -342,7 +349,7 @@

\item[\code{__*__}]
System-defined names.  These names are defined by the interpreter
-  and it's implementation (including the standard library);
+  and its implementation (including the standard library);
applications should not expect to define additional names using this
convention.  The set of names of this class defined by Python may be
extended in future versions.

Index: ref3.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/ref/ref3.tex,v
retrieving revision 1.92.2.2
retrieving revision 1.92.2.3
diff -u -d -r1.92.2.2 -r1.92.2.3
--- ref3.tex	7 Jan 2005 06:57:33 -0000	1.92.2.2
+++ ref3.tex	16 Oct 2005 05:23:58 -0000	1.92.2.3
@@ -165,7 +165,8 @@

\begin{description}
\item[Integers]
-These represent elements from the mathematical set of whole numbers.
+These represent elements from the mathematical set of integers
+(positive and negative).
\obindex{integer}

There are three types of integers:
@@ -325,7 +326,7 @@
\function{ord()}\bifuncindex{ord} convert between code units and
nonnegative integers representing the Unicode ordinals as defined in
the Unicode Standard 3.0. Conversion from and to other encodings are
-possible through the Unicode method \method{encode} and the built-in
+possible through the Unicode method \method{encode()} and the built-in
function \function{unicode()}.\bifuncindex{unicode}
\obindex{unicode}
\index{character}
@@ -450,7 +451,7 @@
\lineiii{__module__}{The name of the module the function was defined
in, or \code{None} if unavailable.}{Writable}

-  \lineiii{func_defaults}{Atuple containing default argument values
+  \lineiii{func_defaults}{A tuple containing default argument values
for those arguments that have defaults, or \code{None} if no
arguments have a default value}{Writable}

@@ -604,7 +605,7 @@
have reached the end of the set of values to be returned.

\item[Built-in functions]
-A built-in function object is a wrapper around a \C{} function.  Examples
+A built-in function object is a wrapper around a C function.  Examples
of built-in functions are \function{len()} and \function{math.sin()}
(\module{math} is a standard built-in module).
The number and type of the arguments are
@@ -917,14 +918,16 @@
\ttindex{f_builtins}
\ttindex{f_restricted}}

-Special writable attributes: \member{f_trace}, if not \code{None}, is a
-function called at the start of each source code line (this is used by
-the debugger); \member{f_exc_type}, \member{f_exc_value},
-\member{f_exc_traceback} represent the most recent exception caught in
-this frame; \member{f_lineno} is the current line number of the frame
---- writing to this from within a trace function jumps to the given line
-(only for the bottom-most frame).  A debugger can implement a Jump
-command (aka Set Next Statement) by writing to f_lineno.
+Special writable attributes: \member{f_trace}, if not \code{None}, is
+a function called at the start of each source code line (this is used
+by the debugger); \member{f_exc_type}, \member{f_exc_value},
+\member{f_exc_traceback} represent the last exception raised in the
+parent frame provided another exception was ever raised in the current
+frame (in all other cases they are None); \member{f_lineno} is the
+current line number of the frame --- writing to this from within a
+trace function jumps to the given line (only for the bottom-most
+frame).  A debugger can implement a Jump command (aka Set Next
+Statement) by writing to f_lineno.
\withsubitem{(frame attribute)}{
\ttindex{f_trace}
\ttindex{f_exc_type}
@@ -1052,6 +1055,35 @@

\subsection{Basic customization\label{customization}}

+\begin{methoddesc}[object]{__new__}{cls\optional{, \moreargs}}
+Called to create a new instance of class \var{cls}.  \method{__new__()}
+is a static method (special-cased so you need not declare it as such)
+that takes the class of which an instance was requested as its first
+argument.  The remaining arguments are those passed to the object
+constructor expression (the call to the class).  The return value of
+\method{__new__()} should be the new object instance (usually an
+instance of \var{cls}).
+
+Typical implementations create a new instance of the class by invoking
+the superclass's \method{__new__()} method using
+\samp{super(\var{currentclass}, \var{cls}).__new__(\var{cls}[, ...])}
+with appropriate arguments and then modifying the newly-created instance
+as necessary before returning it.
+
+If \method{__new__()} returns an instance of \var{cls}, then the new
+instance's \method{__init__()} method will be invoked like
+\samp{__init__(\var{self}[, ...])}, where \var{self} is the new instance
+and the remaining arguments are the same as were passed to
+\method{__new__()}.
+
+If \method{__new__()} does not return an instance of \var{cls}, then the
+new instance's \method{__init__()} method will not be invoked.
+
+\method{__new__()} is intended mainly to allow subclasses of
+immutable types (like int, str, or tuple) to customize instance
+creation.
+\end{methoddesc}
+
\begin{methoddesc}[object]{__init__}{self\optional{, \moreargs}}
Called\indexii{class}{constructor} when the instance is created.  The
arguments are those passed to the class constructor expression.  If a
@@ -1176,8 +1208,8 @@

There are no implied relationships among the comparison operators.
The truth of \code{\var{x}==\var{y}} does not imply that \code{\var{x}!=\var{y}}
-is false.  Accordingly, when defining \method{__eq__}, one should also
-define \method{__ne__} so that the operators will behave as expected.
+is false.  Accordingly, when defining \method{__eq__()}, one should also
+define \method{__ne__()} so that the operators will behave as expected.

There are no reflected (swapped-argument) versions of these methods
(to be used when the left argument does not support the operation but
@@ -1306,8 +1338,9 @@

\begin{methoddesc}[object]{__getattribute__}{self, name}
Called unconditionally to implement attribute accesses for instances
-of the class. If the class also defines \method{__getattr__}, it will
-never be called (unless called explicitly).
+of the class. If the class also defines \method{__getattr__()}, the latter
+will not be called unless \method{__getattribute__()} either calls it
+explicitly or raises an \exception{AttributeError}.
This method should return the (computed) attribute
value or raise an \exception{AttributeError} exception.
In order to avoid infinite recursion in this method, its
@@ -1626,6 +1659,8 @@
raised; if of a value outside the set of indexes for the sequence
(after any special interpretation of negative values),
\exception{IndexError} should be raised.
+For mapping types, if \var{key} is missing (not in the container),
+\exception{KeyError} should be raised.
\note{\keyword{for} loops expect that an
\exception{IndexError} will be raised for illegal indexes to allow
proper detection of the end of the sequence.}
@@ -1870,7 +1905,7 @@
\var{x}\code{+=}\var{y}, where \var{x} is an instance of a class that
called.  If \var{x} is an instance of a class that does not define a
\code{\var{y}.__radd__(\var{x})} are considered, as with the
evaluation of \var{x}\code{+}\var{y}.
\end{methoddesc}
@@ -1953,10 +1988,10 @@

Below, \method{__op__()} and \method{__rop__()} are used to signify
the generic method names corresponding to an operator;
-\method{__iop__} is used for the corresponding in-place operator.  For
+\method{__iop__()} is used for the corresponding in-place operator.  For
example, for the operator \code{+}', \method{__add__()} and
\method{__radd__()} are used for the left and right variant of the
-binary operator, and \method{__iadd__} for the in-place variant.
+binary operator, and \method{__iadd__()} for the in-place variant.

\item

Index: ref4.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/ref/ref4.tex,v
retrieving revision 1.33.2.2
retrieving revision 1.33.2.3
diff -u -d -r1.33.2.2 -r1.33.2.3
--- ref4.tex	7 Jan 2005 06:57:34 -0000	1.33.2.2
+++ ref4.tex	16 Oct 2005 05:23:58 -0000	1.33.2.3
@@ -182,16 +182,20 @@
\exception{SystemExit}\withsubitem{(built-in
exception)}{\ttindex{SystemExit}}.

-Exceptions are identified by class instances.
-Selection of a matching except clause is based on object identity.
-The \keyword{except} clause must reference the same class or a base
-class of it.
+Exceptions are identified by class instances.  The \keyword{except}
+clause is selected depending on the class of the instance: it must
+reference the class of the instance or a base class thereof.  The

-When an exception is raised, an object (maybe \code{None}) is passed
-as the exception's \emph{value}; this object does not affect the
-selection of an exception handler, but is passed to the selected
-exception handler as additional information.  For class exceptions,
-this object must be an instance of the exception class being raised.
+Exceptions can also be identified by strings, in which case the
+\keyword{except} clause is selected by object identity.  An arbitrary
+value can be raised along with the identifying string which can be
+passed to the handler.
+
+\deprecated{2.5}{String exceptions should not be used in new code.
+They will not be supported in a future version of Python.  Old code
+should be rewritten to use class exceptions instead.}

\begin{notice}[warning]
Messages to exceptions are not part of the Python API.  Their contents may

Index: ref5.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/ref/ref5.tex,v
retrieving revision 1.64.2.2
retrieving revision 1.64.2.3
diff -u -d -r1.64.2.2 -r1.64.2.3
--- ref5.tex	7 Jan 2005 06:57:34 -0000	1.64.2.2
+++ ref5.tex	16 Oct 2005 05:23:58 -0000	1.64.2.3
@@ -960,7 +960,7 @@
object is a member of a set if the set is a sequence and contains an
element equal to that object.  However, it is possible for an object
to support membership tests without being a sequence.  In particular,
-dictionaries support memership testing as a nicer way of spelling
+dictionaries support membership testing as a nicer way of spelling
\code{\var{key} in \var{dict}}; other mapping types may follow suit.

For the list and tuple types, \code{\var{x} in \var{y}} is true if and
@@ -1021,9 +1021,9 @@

In the context of Boolean operations, and also when expressions are
used by control flow statements, the following values are interpreted
-as false: \code{None}, numeric zero of all types, empty sequences
-(strings, tuples and lists), and empty mappings (dictionaries).  All
-other values are interpreted as true.
+as false: \code{False}, \code{None}, numeric zero of all types, and empty
+strings and containers (including strings, tuples, lists, dictionaries,
+sets and frozensets).  All other values are interpreted as true.

The operator \keyword{not} yields \code{True} if its argument is false,
\code{False} otherwise.

Index: ref6.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/ref/ref6.tex,v
retrieving revision 1.55.2.2
retrieving revision 1.55.2.3
diff -u -d -r1.55.2.2 -r1.55.2.3
--- ref6.tex	7 Jan 2005 06:57:34 -0000	1.55.2.2
+++ ref6.tex	16 Oct 2005 05:23:58 -0000	1.55.2.3
@@ -204,12 +204,12 @@
\item
If the target is a subscription: The primary expression in the
reference is evaluated.  It should yield either a mutable sequence
-object (e.g., a list) or a mapping object (e.g., a dictionary).  Next,
+object (such as a list) or a mapping object (such as a dictionary). Next,
the subscript expression is evaluated.
\indexii{subscription}{assignment}
\obindex{mutable}

-If the primary is a mutable sequence object (e.g., a list), the subscript
+If the primary is a mutable sequence object (such as 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
@@ -219,7 +219,7 @@
\obindex{sequence}
\obindex{list}

-If the primary is a mapping object (e.g., a dictionary), the subscript must
+If the primary is a mapping object (such as 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
@@ -230,7 +230,7 @@

\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 (such as 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
@@ -251,7 +251,7 @@
messages.)

WARNING: Although the definition of assignment implies that overlaps
-between the left-hand side and the right-hand side are safe' (e.g.,
+between the left-hand side and the right-hand side are safe' (for example
\samp{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 \samp{[0, 2]}:
@@ -523,8 +523,10 @@
\end{productionlist}

If no expressions are present, \keyword{raise} re-raises the last
-expression that was active in the current scope.  If no exception is
-active in the current scope, an exception is raised indicating this error.
+exception that was active in the current scope.  If no exception is
+active in the current scope, a \exception{TypeError} exception is
+raised indicating that this is an error (if running under IDLE, a
\index{exception}
\indexii{raising}{exception}

@@ -601,7 +603,7 @@

\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{It may
+\keyword{finally} 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 implementor's
laziness and will eventually be lifted.}
@@ -872,7 +874,12 @@
a code object.  If it is a string, the string is parsed as a suite of
Python statements which is then executed (unless a syntax error
occurs).  If it is an open file, the file is parsed until \EOF{} and
-executed.  If it is a code object, it is simply executed.
+executed.  If it is a code object, it is simply executed.  In all
+cases, the code that's executed is expected to be be valid as file
+input (see section~\ref{file-input}, File input'').  Be aware that
+the \keyword{return} and \keyword{yield} statements may not be used
+outside of function definitions even within the context of code passed
+to the \keyword{exec} statement.

In all cases, if the optional parts are omitted, the code is executed
in the current scope.  If only the first expression after \keyword{in}

Index: ref7.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/ref/ref7.tex,v
retrieving revision 1.34.2.2
retrieving revision 1.34.2.3
diff -u -d -r1.34.2.2 -r1.34.2.3
--- ref7.tex	7 Jan 2005 06:57:34 -0000	1.34.2.2
+++ ref7.tex	16 Oct 2005 05:23:58 -0000	1.34.2.3
@@ -223,11 +223,11 @@
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
-that are classes) it is a base class of 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.
+is the class or a base class of the exception object, a tuple
+containing an item compatible with the exception, or, in the
+(deprecated) case of string exceptions, is the raised string itself
+(note that the object identities must match, i.e. it must be the same
+string object, not just a string with the same value).
\kwindex{except}

If no except clause matches the exception, the search for an exception
@@ -239,14 +239,14 @@
on the call stack (it is treated as if the entire \keyword{try} statement
raised the exception).

-When a matching except clause is found, the exception's parameter is
-assigned to the target specified in that except clause, if present,
-and the except clause's suite is executed.  All except clauses must
-have an executable block.  When the end of this block
-is reached, execution continues normally after the entire try
-statement.  (This means that if two nested handlers exist for the same
-exception, and the exception occurs in the try clause of the inner
-handler, the outer handler will not handle the exception.)
+When a matching except clause is found, the exception is assigned to
+the target specified in that except clause, if present, and the except
+clause's suite is executed.  All except clauses must have an
+executable block.  When the end of this block is reached, execution
+continues normally after the entire try statement.  (This means that
+if two nested handlers exist for the same exception, and the exception
+occurs in the try clause of the inner handler, the outer handler will
+not handle the exception.)

Before an except clause's suite is executed, details about the
exception are assigned to three variables in the
@@ -323,6 +323,8 @@
{\token{decorator}+}
\production{decorator}
{"@" \token{dotted_name} ["(" [\token{argument_list} [","]] ")"] NEWLINE}
+  \production{dotted_name}
+             {\token{identifier} ("." \token{identifier})*}
\production{parameter_list}
{(\token{defparameter} ",")*}
\productioncont{(~~"*" \token{identifier} [, "**" \token{identifier}]}
@@ -439,7 +441,7 @@
{"class" \token{classname} [\token{inheritance}] ":"
\token{suite}}
\production{inheritance}
-             {"(" \token{expression_list} ")"}
+             {"(" [\token{expression_list}] ")"}
\production{classname}
{\token{identifier}}
\end{productionlist}

`