--- Python-Docs-2.4/./ref/ref3.tex	2004-08-13 03:12:43.000000000 +0900
+++ Python-Docs-2.5/./ref/ref3.tex	2006-09-02 11:45:43.000000000 +0900
@@ -24,7 +24,8 @@
 object's type, under certain controlled conditions.  Until this manual
 undergoes extensive revision, it must now be taken as authoritative
 only regarding ``classic classes'', that are still the default, for
-compatibility purposes, in Python 2.2 and 2.3.}
+compatibility purposes, in Python 2.2 and 2.3.  For more information,
+see \url{http://www.python.org/doc/newstyle.html}.}
 An object's type determines the operations that the object
 supports (e.g., ``does it have a length?'') and also defines the
 possible values for objects of that type.  The
@@ -165,7 +166,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 +327,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}
@@ -409,8 +411,9 @@
 Displays'').
 
 The extension modules \module{dbm}\refstmodindex{dbm},
-\module{gdbm}\refstmodindex{gdbm}, \module{bsddb}\refstmodindex{bsddb}
-provide additional examples of mapping types.
+\module{gdbm}\refstmodindex{gdbm}, and
+\module{bsddb}\refstmodindex{bsddb} provide additional examples of
+mapping types.
 
 \end{description} % Mapping types
 
@@ -450,7 +453,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 +607,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
@@ -759,7 +762,7 @@
 (call it~\class{C}) of the instance for which the attribute reference
 was initiated or one of its bases,
 it is transformed into a bound user-defined method object whose
-\member{im_class} attribute is~\class{C} whose \member{im_self} attribute
+\member{im_class} attribute is~\class{C} and whose \member{im_self} attribute
 is the instance. Static method and class method objects are also
 transformed, as if they had been retrieved from class~\class{C};
 see above under ``Classes''. See section~\ref{descriptors} for
@@ -917,14 +920,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}
@@ -1027,7 +1032,49 @@
 
 \end{description} % Types
 
+%=========================================================================
+\section{New-style and classic classes}
 
+Classes and instances come in two flavors: old-style or classic, and new-style.  
+
+Up to Python 2.1, old-style classes were the only flavour available to the
+user.  The concept of (old-style) class is unrelated to the concept of type: if
+\var{x} is an instance of an old-style class, then \code{x.__class__}
+designates the class of \var{x}, but \code{type(x)} is always \code{<type
+'instance'>}.  This reflects the fact that all old-style instances,
+independently of their class, are implemented with a single built-in type,
+called \code{instance}.
+
+New-style classes were introduced in Python 2.2 to unify classes and types.  A
+new-style class neither more nor less than a user-defined type.  If \var{x} is
+an instance of a new-style class, then \code{type(x)} is the same as
+\code{x.__class__}.
+
+The major motivation for introducing new-style classes is to provide a unified
+object model with a full meta-model.  It also has a number of immediate
+benefits, like the ability to subclass most built-in types, or the introduction
+of "descriptors", which enable computed properties.
+
+For compatibility reasons, classes are still old-style by default.  New-style
+classes are created by specifying another new-style class (i.e.\ a type) as a
+parent class, or the "top-level type" \class{object} if no other parent is
+needed.  The behaviour of new-style classes differs from that of old-style
+classes in a number of important details in addition to what \function{type}
+returns.  Some of these changes are fundamental to the new object model, like
+the way special methods are invoked.  Others are "fixes" that could not be
+implemented before for compatibility concerns, like the method resolution order
+in case of multiple inheritance.
+
+This manual is not up-to-date with respect to new-style classes.  For now,
+please see \url{http://www.python.org/doc/newstyle.html} for more information.
+
+The plan is to eventually drop old-style classes, leaving only the semantics of
+new-style classes.  This change will probably only be feasible in Python 3.0.
+\index{class}{new-style}
+\index{class}{classic}
+\index{class}{old-style}
+
+%=========================================================================
 \section{Special method names\label{specialnames}}
 
 A class can implement certain operations that are invoked by special
@@ -1037,7 +1084,9 @@
 classes to define their own behavior with respect to language
 operators.  For instance, if a class defines
 a method named \method{__getitem__()}, and \code{x} is an instance of
-this class, then \code{x[i]} is equivalent to
+this class, then \code{x[i]} is equivalent\footnote{This, and other
+statements, are only roughly true for instances of new-style
+classes.} to
 \code{x.__getitem__(i)}.  Except where mentioned, attempts to execute
 an operation raise an exception when no appropriate method is defined.
 \withsubitem{(mapping object method)}{\ttindex{__getitem__()}}
@@ -1052,6 +1101,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 +1254,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
@@ -1229,6 +1307,11 @@
 since the dictionary implementation requires that a key's hash value
 is immutable (if the object's hash value changes, it will be in the
 wrong hash bucket).
+
+\versionchanged[\method{__hash__()} may now also return a long
+integer object; the 32-bit integer is then derived from the hash
+of that object]{2.5}
+
 \withsubitem{(object method)}{\ttindex{__cmp__()}}
 \end{methoddesc}
 
@@ -1306,8 +1389,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
@@ -1328,7 +1412,7 @@
 
 \begin{methoddesc}[object]{__get__}{self, instance, owner}
 Called to get the attribute of the owner class (class attribute access)
-or of an instance of that class (instance attribute acces).
+or of an instance of that class (instance attribute access).
 \var{owner} is always the owner class, while \var{instance} is the
 instance that the attribute was accessed through, or \code{None} when
 the attribute is accessed through the \var{owner}.  This method should
@@ -1626,6 +1710,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.}
@@ -1794,8 +1880,8 @@
 called to implement the binary arithmetic operations (\code{+},
 \code{-}, \code{*}, \code{//}, \code{\%},
 \function{divmod()}\bifuncindex{divmod},
-\function{pow()}\bifuncindex{pow}, \code{**}, \code{<}\code{<},
-\code{>}\code{>}, \code{\&}, \code{\^}, \code{|}).  For instance, to
+\function{pow()}\bifuncindex{pow}, \code{**}, \code{<<},
+\code{>>}, \code{\&}, \code{\^}, \code{|}).  For instance, to
 evaluate the expression \var{x}\code{+}\var{y}, where \var{x} is an
 instance of a class that has an \method{__add__()} method,
 \code{\var{x}.__add__(\var{y})} is called.  The \method{__divmod__()}
@@ -1805,6 +1891,9 @@
 \method{__pow__()} should be defined to accept an optional third
 argument if the ternary version of the built-in
 \function{pow()}\bifuncindex{pow} function is to be supported.
+
+If one of those methods does not support the operation with the
+supplied arguments, it should return \code{NotImplemented}.
 \end{methoddesc}
 
 \begin{methoddesc}[numeric object]{__div__}{self, other}
@@ -1834,16 +1923,31 @@
 called to implement the binary arithmetic operations (\code{+},
 \code{-}, \code{*}, \code{/}, \code{\%},
 \function{divmod()}\bifuncindex{divmod},
-\function{pow()}\bifuncindex{pow}, \code{**}, \code{<}\code{<},
-\code{>}\code{>}, \code{\&}, \code{\^}, \code{|}) with reflected
+\function{pow()}\bifuncindex{pow}, \code{**}, \code{<<},
+\code{>>}, \code{\&}, \code{\^}, \code{|}) with reflected
 (swapped) operands.  These functions are only called if the left
-operand does not support the corresponding operation.  For instance,
-to evaluate the expression \var{x}\code{-}\var{y}, where \var{y} is an
-instance of a class that has an \method{__rsub__()} method,
-\code{\var{y}.__rsub__(\var{x})} is called.  Note that ternary
+operand does not support the corresponding operation and the
+operands are of different types.\footnote{
+    For operands of the same type, it is assumed that if the
+    non-reflected method (such as \method{__add__()}) fails the
+    operation is not supported, which is why the reflected method
+    is not called.} 
+For instance, to evaluate the expression \var{x}\code{-}\var{y},
+where \var{y} is an instance of a class that has an
+\method{__rsub__()} method, \code{\var{y}.__rsub__(\var{x})}
+is called if \code{\var{x}.__sub__(\var{y})} returns
+\var{NotImplemented}.
+
+Note that ternary
 \function{pow()}\bifuncindex{pow} will not try calling
 \method{__rpow__()} (the coercion rules would become too
 complicated).
+
+\note{If the right operand's type is a subclass of the left operand's
+      type and that subclass provides the reflected method for the
+      operation, this method will be called before the left operand's
+      non-reflected method.  This behavior allows subclasses to
+      override their ancestors' operations.}
 \end{methoddesc}
 
 \begin{methoddesc}[numeric object]{__iadd__}{self, other}
@@ -1861,7 +1965,7 @@
 \methodline[numeric object]{__ior__}{self, other}
 These methods are called to implement the augmented arithmetic
 operations (\code{+=}, \code{-=}, \code{*=}, \code{/=}, \code{\%=},
-\code{**=}, \code{<}\code{<=}, \code{>}\code{>=}, \code{\&=},
+\code{**=}, \code{<<=}, \code{>>=}, \code{\&=},
 \code{\textasciicircum=}, \code{|=}).  These methods should attempt to do the
 operation in-place (modifying \var{self}) and return the result (which
 could be, but does not have to be, \var{self}).  If a specific method
@@ -1870,7 +1974,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}
@@ -1901,6 +2005,13 @@
 \function{hex()}\bifuncindex{hex}.  Should return a string value.
 \end{methoddesc}
 
+\begin{methoddesc}[numeric object]{__index__}{self}
+Called to implement \function{operator.index()}.  Also called whenever
+Python needs an integer object (such as in slicing).  Must return an
+integer (int or long).
+\versionadded{2.5}
+\end{methoddesc}
+
 \begin{methoddesc}[numeric object]{__coerce__}{self, other}
 Called to implement ``mixed-mode'' numeric arithmetic.  Should either
 return a 2-tuple containing \var{self} and \var{other} converted to
@@ -1953,10 +2064,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
 
@@ -1969,14 +2080,15 @@
 \item
 
 Exception to the previous item: if the left operand is an instance of
-a built-in type or a new-style class, and the right operand is an
-instance of a proper subclass of that type or class, the right
-operand's \method{__rop__()} method is tried \emph{before} the left
-operand's \method{__op__()} method.  This is done so that a subclass can
-completely override binary operators.  Otherwise, the left operand's
-__op__ method would always accept the right operand: when an instance
-of a given class is expected, an instance of a subclass of that class
-is always acceptable.
+a built-in type or a new-style class, and the right operand is an instance
+of a proper subclass of that type or class and overrides the base's
+\method{__rop__()} method, the right operand's \method{__rop__()} method
+is tried \emph{before} the left operand's \method{__op__()} method.
+
+This is done so that a subclass can completely override binary operators.
+Otherwise, the left operand's \method{__op__()} method would always
+accept the right operand: when an instance of a given class is expected,
+an instance of a subclass of that class is always acceptable.
 
 \item
 
@@ -2022,3 +2134,55 @@
 \function{coerce()} function.
 
 \end{itemize}
+
+\subsection{With Statement Context Managers\label{context-managers}}
+
+\versionadded{2.5}
+
+A \dfn{context manager} is an object that defines the runtime
+context to be established when executing a \keyword{with}
+statement. The context manager handles the entry into,
+and the exit from, the desired runtime context for the execution
+of the block of code.  Context managers are normally invoked using
+the \keyword{with} statement (described in section~\ref{with}), but
+can also be used by directly invoking their methods.
+
+\stindex{with}
+\index{context manager}
+
+Typical uses of context managers include saving and
+restoring various kinds of global state, locking and unlocking
+resources, closing opened files, etc.
+
+For more information on context managers, see
+``\ulink{Context Types}{../lib/typecontextmanager.html}'' in the
+\citetitle[../lib/lib.html]{Python Library Reference}.
+
+\begin{methoddesc}[context manager]{__enter__}{self}
+Enter the runtime context related to this object. The \keyword{with}
+statement will bind this method's return value to the target(s)
+specified in the \keyword{as} clause of the statement, if any.
+\end{methoddesc}
+
+\begin{methoddesc}[context manager]{__exit__}
+{self, exc_type, exc_value, traceback}
+Exit the runtime context related to this object. The parameters
+describe the exception that caused the context to be exited. If
+the context was exited without an exception, all three arguments
+will be \constant{None}.
+
+If an exception is supplied, and the method wishes to suppress the
+exception (i.e., prevent it from being propagated), it should return a
+true value. Otherwise, the exception will be processed normally upon
+exit from this method.
+
+Note that \method{__exit__} methods should not reraise the passed-in
+exception; this is the caller's responsibility.
+\end{methoddesc}
+
+\begin{seealso}
+  \seepep{0343}{The "with" statement}
+         {The specification, background, and examples for the
+          Python \keyword{with} statement.}
+\end{seealso}
+
