[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
- Previous message: [Python-checkins] python/dist/src/Doc/texinputs underscore.sty, NONE, 1.1.2.2 howto.cls, 1.13.2.1, 1.13.2.2 manual.cls, 1.18.2.1, 1.18.2.2 python.sty, 1.96.2.2, 1.96.2.3
- Next message: [Python-checkins] python/dist/src/Doc/whatsnew whatsnew24.tex, 1.127.2.1, 1.127.2.2 whatsnew25.tex, 1.4.2.1, 1.4.2.2
- Messages sorted by:
[ date ]
[ thread ]
[ subject ]
[ author ]
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}
- Previous message: [Python-checkins] python/dist/src/Doc/texinputs underscore.sty, NONE, 1.1.2.2 howto.cls, 1.13.2.1, 1.13.2.2 manual.cls, 1.18.2.1, 1.18.2.2 python.sty, 1.96.2.2, 1.96.2.3
- Next message: [Python-checkins] python/dist/src/Doc/whatsnew whatsnew24.tex, 1.127.2.1, 1.127.2.2 whatsnew25.tex, 1.4.2.1, 1.4.2.2
- Messages sorted by:
[ date ]
[ thread ]
[ subject ]
[ author ]
More information about the Python-checkins
mailing list