classification
Title: document immutable type subclassing via __new__
Type: Stage: resolved
Components: Documentation, Library (Lib) Versions: Python 3.11, Python 3.10, Python 3.9
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: benjamin.peterson, cjw296, cvrebert, eric.araujo, georg.brandl, lukasz.langa, miss-islington, mloskot, quantum, r.david.murray, rhettinger
Priority: normal Keywords: patch

Created on 2008-11-26 17:08 by cjw296, last changed 2021-08-23 06:34 by rhettinger. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 27866 merged rhettinger, 2021-08-21 00:23
PR 27899 merged miss-islington, 2021-08-22 19:27
PR 27900 merged lukasz.langa, 2021-08-22 19:46
Messages (14)
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?
msg400099 - (view) Author: Łukasz Langa (lukasz.langa) * (Python committer) Date: 2021-08-22 19:27
New changeset eec340ea3af27887fcaac4029ebdee99f3713bff by Raymond Hettinger in branch 'main':
bpo-4442:  Document use of __new__ for subclasses of immutable types (GH-27866)
https://github.com/python/cpython/commit/eec340ea3af27887fcaac4029ebdee99f3713bff
msg400100 - (view) Author: miss-islington (miss-islington) Date: 2021-08-22 19:49
New changeset 0627918f0b69a15aa16e4ccbb5d8eaae4f6a2caf by Miss Islington (bot) in branch '3.10':
bpo-4442:  Document use of __new__ for subclasses of immutable types (GH-27866)
https://github.com/python/cpython/commit/0627918f0b69a15aa16e4ccbb5d8eaae4f6a2caf
msg400103 - (view) Author: Łukasz Langa (lukasz.langa) * (Python committer) Date: 2021-08-22 20:14
New changeset ac87b07a10e0ba2834e8de9cf0ea29a40fd882b1 by Łukasz Langa in branch '3.9':
[3.9] bpo-4442:  Document use of __new__ for subclasses of immutable types (GH-27866) (GH-27900)
https://github.com/python/cpython/commit/ac87b07a10e0ba2834e8de9cf0ea29a40fd882b1
msg400104 - (view) Author: Łukasz Langa (lukasz.langa) * (Python committer) Date: 2021-08-22 20:15
Thanks for the patch, Raymond! ✨ 🍰 ✨
History
Date User Action Args
2021-08-23 06:34:56rhettingersetassignee: docs@python -> rhettinger
2021-08-22 20:15:13lukasz.langasetstatus: open -> closed
versions: + Python 3.9, Python 3.10, Python 3.11, - Python 2.7, Python 3.2, Python 3.3
messages: + msg400104

resolution: fixed
stage: patch review -> resolved
2021-08-22 20:14:35lukasz.langasetmessages: + msg400103
2021-08-22 19:49:28miss-islingtonsetmessages: + msg400100
2021-08-22 19:46:16lukasz.langasetpull_requests: + pull_request26355
2021-08-22 19:27:14lukasz.langasetnosy: + lukasz.langa
messages: + msg400099
2021-08-22 19:27:14miss-islingtonsetnosy: + miss-islington
pull_requests: + pull_request26354
2021-08-21 00:23:11rhettingersetkeywords: + patch
nosy: + rhettinger

pull_requests: + pull_request26321
stage: needs patch -> patch review
2021-08-20 16:57:08quantumsetnosy: + quantum
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