This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: add documentation for __new__
Type: Stage:
Components: Documentation Versions: Python 2.4
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: gward Nosy List: bethard, gward, ncoghlan, orenti
Priority: normal Keywords:

Created on 2005-03-04 03:00 by bethard, last changed 2022-04-11 14:56 by admin. This issue is now closed.

Files
File name Uploaded Description Edit
doc-__new__.patch gward, 2005-03-06 22:27
Messages (10)
msg24457 - (view) Author: Steven Bethard (bethard) * (Python committer) Date: 2005-03-04 03:00
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.
msg24458 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2005-03-04 15:53
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?
msg24459 - (view) Author: Steven Bethard (bethard) * (Python committer) Date: 2005-03-04 16:11
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
msg24460 - (view) Author: Oren Tirosh (orenti) Date: 2005-03-04 18:05
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.
msg24461 - (view) Author: Steven Bethard (bethard) * (Python committer) Date: 2005-03-04 20:19
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."
msg24462 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2005-03-05 04:02
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)."
msg24463 - (view) Author: Greg Ward (gward) (Python committer) Date: 2005-03-05 16:11
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?
msg24464 - (view) Author: Greg Ward (gward) (Python committer) Date: 2005-03-05 16:34
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.
msg24465 - (view) Author: Steven Bethard (bethard) * (Python committer) Date: 2005-03-05 20:30
Logged In: YES 
user_id=945502

Looks pretty good to me.  Only one change:
    "super(currentclass, cls).__new__([...])"
should look like:
    "super(currentclass, cls).__new__(cls[, ...])"
Sorry I didn't catch this earlier.  But, since it's a
staticmethod, of course you need to pass 'cls' manually.
msg24466 - (view) Author: Greg Ward (gward) (Python committer) Date: 2005-03-08 01:11
Logged In: YES 
user_id=14422

OK, done.  Doc change checked in on release24-maint branch:
  Doc/ref/ref3.tex rev 1.121.2.2
and on trunk
  Doc/ref/ref3.tex rev 1.123
History
Date User Action Args
2022-04-11 14:56:10adminsetgithub: 41650
2005-03-04 03:00:36bethardcreate