[ python-Bugs-1156412 ] add documentation for __new__

[SourceForge.net]

Bugs item #1156412, was opened at 2005-03-04 03:00
Message generated for change (Comment added) made by orenti
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1156412&group_id=5470

Category: Documentation
Group: Python 2.5
Status: Open
Resolution: None
Priority: 5
Submitted By: Steven Bethard (bediviere)
Assigned to: Nobody/Anonymous (nobody)
Summary: add documentation for __new__

Initial Comment:
3.3.1 Basic customization does not document __new__. 
Proposed addition:

__new__(cls[, ...])

Called to create a new instance of the class.  __new__
is a staticmethod (special-cased so you need not
declare it as such) that takes the class to be created
as the first argument.  The remaining arguments are
those passed to the class constructor expression. The
return value of __new__ should be the new object instance.

Typical usage is to create a new instance of the class
by invoking the superclass's __new__ method using
"super(BaseClass, cls).__new__([...])" with appropriate
arguments, modifying the returned instance if
necessary, and then returning it.  If the returned
value is an instance of "cls" (the first argument to
__new__), its __init__ will be invoked.

Note that you need not return an instance of "cls", but
if you don't, the new instance's __init__ method will
not be invoked.

The __new__ staticmethod is intended mainly to allow
modification of immutable types like int, long, float,
str and tuple.

----------------------------------------------------------------------

Comment By: Oren Tirosh (orenti)
Date: 2005-03-04 18:05

Message:
Logged In: YES 
user_id=562624

"The __new__ staticmethod is intended mainly to allow
modification of immutable types like int, long, float,
str and tuple."

You might like to rephrase that. It gives the impression
that __new__ somehow makes it possible to modify the value
of an immutable object. In fact, it only allows customized
creation of new instances.


----------------------------------------------------------------------

Comment By: Steven Bethard (bediviere)
Date: 2005-03-04 16:11

Message:
Logged In: YES 
user_id=945502

Yup, type_call in typeobject.c special-cases this behavior.
 See also
http://sourceforge.net/tracker/?func=detail&aid=1123716&group_id=5470&atid=105470

----------------------------------------------------------------------

Comment By: Nick Coghlan (ncoghlan)
Date: 2005-03-04 15:53

Message:
Logged In: YES 
user_id=1038590

Looks reasonable to me - but does CPython actually currently
follow those rules regarding when __init__ is and isn't invoked?

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1156412&group_id=5470