[Python-checkins] python/dist/src/Doc/ref ref3.tex, 1.121.2.1, 1.121.2.2

[gward at users.sourceforge.net]

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

Modified Files:
      Tag: release24-maint
	ref3.tex 
Log Message:
SF #1156412: document the __new__() static method.


Index: ref3.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/ref/ref3.tex,v
retrieving revision 1.121.2.1
retrieving revision 1.121.2.2
diff -u -d -r1.121.2.1 -r1.121.2.2
--- ref3.tex	1 Jan 2005 00:34:55 -0000	1.121.2.1
+++ ref3.tex	8 Mar 2005 01:08:42 -0000	1.121.2.2
@@ -1052,6 +1052,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