summaryrefslogtreecommitdiffstats
path: root/Doc
diff options
context:
space:
mode:
authorGreg Ward <gward@python.net>2005-03-08 01:10:20 (GMT)
committerGreg Ward <gward@python.net>2005-03-08 01:10:20 (GMT)
commitff564d3391ef70e453a49d64b68a2f902c40a5b2 (patch)
treeb52b757c68b35f89c0902a8cec7d047943c835f6 /Doc
parent50682d0f78a06cff01a9b769128e30c8e0e37c0c (diff)
downloadcpython-ff564d3391ef70e453a49d64b68a2f902c40a5b2.zip
cpython-ff564d3391ef70e453a49d64b68a2f902c40a5b2.tar.gz
cpython-ff564d3391ef70e453a49d64b68a2f902c40a5b2.tar.bz2
SF #1156412: document the __new__() static method
(merge from release24-maint branch).
Diffstat (limited to 'Doc')
-rw-r--r--Doc/ref/ref3.tex29
1 files changed, 29 insertions, 0 deletions
diff --git a/Doc/ref/ref3.tex b/Doc/ref/ref3.tex
index f339676..f670ce0 100644
--- a/Doc/ref/ref3.tex
+++ b/Doc/ref/ref3.tex
@@ -1052,6 +1052,35 @@ extracting a slice may not make sense. (One example of this is the
\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