[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]

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
+create tests for Java libraries.  More information can be found at
+\ulink{the Jython website}{http://www.jython.org/}.
+
+\item[Python for .NET]
+This implementation actually uses the CPython implementation, but is a
+managed .NET application and makes .NET libraries available.  This was
+created by Brian Lloyd.  For more information, see the \ulink{Python
+for .NET home page}{http://www.zope.org/Members/Brian/PythonNet}.
+
+\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
+original creator of Jython.  For more information, see \ulink{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).
 
 
 \subsection{Comments\label{comments}}
@@ -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
 has an \method{__iadd__()} method, \code{\var{x}.__iadd__(\var{y})} is
 called.  If \var{x} is an instance of a class that does not define a
-\method{__iadd()} method, \code{\var{x}.__add__(\var{y})} and
+\method{__iadd__()} method, \code{\var{x}.__add__(\var{y})} and
 \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
+instance can be received by the handler and can carry additional
+information about the exceptional condition.
 
-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
+\exception{Queue.Empty} exception is raised instead).
 \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}