[ python-Bugs-1156412 ] add documentation for __new__

[SourceForge.net]

Bugs item #1156412, was opened at 2005-03-03 22:00
Message generated for change (Comment added) made by gward
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: Greg Ward (gward)
Date: 2005-03-05 11:34

Message:
Logged In: YES 
user_id=14422

Here's an alternative text -- a bit tighter, hopefully a tad
more accurate and clearer:

__new__(cls[, ...])

Called to create a new instance of class 'cls'.  __new__()
is a static method (special-cased so you need not declare it
as such) that takes the class to create an instance of as
the first argument.  The remaining arguments are those
passed to the object 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(currentclass, cls).__new__([...])" with appropriate
arguments, modifying the returned instance if necessary, and
then returning it.  If the returned value is an instance of
'cls', its __init__() will be invoked like
"__init__(self[, ...])", where the extra arguments are the
same as were passed to __new__().

You do need not to return an instance of 'cls', but if you
do not, the new instance's __init__() method will not be
invoked.

__new__() is intended mainly to allow subclasses of
immutable types (like int, str, or tuple) to customize
instance creation.


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

Comment By: Greg Ward (gward)
Date: 2005-03-05 11:11

Message:
Logged In: YES 
user_id=14422

I think that last paragraph can be written even more concisely:

"The __new__ staticmethod is intended mainly to allow
subclasses of immutable types (like int, str, or tuple) to
customize instance creation."

Also, the usual convention when talking about methods and
functions is to write "__new__()", not "__new__".  At least
that's how the 2.3.3 language ref which I have on my PC looks.

Finally, this bug is in the "Python 2.5" group -- surely
there's no harm in checking this in to the 2.4 docs and
merging forward?

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

Comment By: Nick Coghlan (ncoghlan)
Date: 2005-03-04 23:02

Message:
Logged In: YES 
user_id=1038590

Close, but the phrasing's a bit awkward. Getting rid of the
commas seems to fix that:

"The __new__ staticmethod is intended mainly to allow you to
customize instance creation in a subclass of an immutable
type (like int, long, float, complex, str, unicode, or tuple)."

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

Comment By: Steven Bethard (bediviere)
Date: 2005-03-04 15:19

Message:
Logged In: YES 
user_id=945502

Good point.  How about:

"The __new__ staticmethod is intended mainly to allow you,
in a subclass of an immutable type (like int, long, float,
complex, str, unicode, or tuple), to customize instance
creation."

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

Comment By: Oren Tirosh (orenti)
Date: 2005-03-04 13: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 11: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 10: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