classification
Title: document immutable type subclassing via __new__
Type: Stage: needs patch
Components: Documentation, Library (Lib) Versions: Python 3.2, Python 3.3, Python 2.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: benjamin.peterson, cjw296, cvrebert, eric.araujo, georg.brandl, mloskot, r.david.murray
Priority: normal Keywords:

Created on 2008-11-26 17:08 by cjw296, last changed 2012-06-13 20:22 by cvrebert.

Messages (10)
msg76473 - (view) Author: Chris Withers (cjw296) * (Python committer) Date: 2008-11-26 17:08
>>> from datetime import datetime
>>> class defaultdatetime(datetime):
...   defaults=(2001,1,1)
...   def __init__(self,*args):
...     if not args:
...       args = self.defaults
...     datetime.__init__(self,*args)
...
>>> defaultdatetime()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: function takes at least 3 arguments (0 given)
msg76474 - (view) Author: Chris Withers (cjw296) * (Python committer) Date: 2008-11-26 17:18
Sorry, forgot to say that the above is at best counterintuitive and not
documented anywhere...
msg76475 - (view) Author: Benjamin Peterson (benjamin.peterson) * (Python committer) Date: 2008-11-26 17:23
This is because datetime does all its initialization in __new__ instead
of __init__.
msg76478 - (view) Author: Chris Withers (cjw296) * (Python committer) Date: 2008-11-26 17:41
But that isn't documented anywhere...
msg76979 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2008-12-05 08:06
It's not documented for any immutable type. This should be fixed.
msg162479 - (view) Author: Mateusz Loskot (mloskot) Date: 2012-06-07 17:16
Is this report about documenting of the concept of immutable types in Python in general or regarding existing built-in types, like datetime.datetime?

Generally, the concept of immutable type with relation to tp_new is mentioned (sneaked) here:

1) http://docs.python.org/release/3.2.2/c-api/typeobj.html

"A good rule of thumb is that for immutable types, all initialization should take place in tp_new, while for mutable types, most initialization should be deferred to tp_init."

2) http://www.python.org/dev/peps/pep-0253/

Note that for immutable object types, the initialization
cannot be done by the tp_init() slot: this would provide the Python 
user with a way to change the initialization.  Therefore, immutable
objects typically have an empty tp_init() implementation and do
all their initialization in their tp_new() slot.

IMHO, it deserves a dedicated section/chapter in the docs.
msg162695 - (view) Author: Chris Withers (cjw296) * (Python committer) Date: 2012-06-12 22:05
It's the fact that for immutable types, initialization is done in __new__ instead of __init__ that isn't documented anywhere. 

This should be Python-level rather than C-level documentation.

The example I gave in #msg76473 is confusing without docs anywhere that explain why this is.
msg162697 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2012-06-13 00:32
Actually, it is documented: http://docs.python.org/dev/reference/datamodel.html#basic-customization

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

It could certainly be better documented, but where?  The tutorial?
msg162703 - (view) Author: Mateusz Loskot (mloskot) Date: 2012-06-13 12:12
Chris Withers' note clarifies it to me, that this should be Python-level rather than C-level documentation. Then the note under __new__() in 3. Data model seems right.
Simply, I expected to have some notes in C API too

Side note: as mainly Python C API user, I expected to have it documented at C API level too.
msg162704 - (view) Author: Chris Withers (cjw296) * (Python committer) Date: 2012-06-13 12:17
Probably also wouldn't go amiss to put some notes near the docs for common immutable types that people might subclass: datetime, maybe tuple?
History
Date User Action Args
2012-06-13 20:22:52cvrebertsetnosy: + cvrebert
2012-06-13 12:17:55cjw296setmessages: + msg162704
2012-06-13 12:12:19mloskotsetmessages: + msg162703
2012-06-13 00:32:26r.david.murraysetnosy: + r.david.murray
messages: + msg162697
2012-06-12 22:05:30cjw296setmessages: + msg162695
2012-06-07 17:16:55mloskotsetmessages: + msg162479
2012-06-07 17:11:48mloskotsetnosy: + mloskot
2011-11-18 14:31:46eric.araujosetnosy: + eric.araujo
2011-11-15 19:35:02ezio.melottisetstage: needs patch
versions: + Python 3.2, Python 3.3, - Python 3.1
2010-10-29 10:07:21adminsetassignee: georg.brandl -> docs@python
2008-12-05 08:06:41georg.brandlsetmessages: + msg76979
title: datetime not subclassable in the usual way -> document immutable type subclassing via __new__
2008-11-26 17:41:31cjw296setassignee: georg.brandl
type: enhancement ->
messages: + msg76478
components: + Documentation
nosy: + georg.brandl
2008-11-26 17:23:58benjamin.petersonsetpriority: normal
type: enhancement
messages: + msg76475
nosy: + benjamin.peterson
versions: + Python 3.1, Python 2.7, - Python 2.5
2008-11-26 17:18:20cjw296setmessages: + msg76474
2008-11-26 17:08:01cjw296create