>>> 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)

Sorry, forgot to say that the above is at best counterintuitive and not
documented anywhere...

This is because datetime does all its initialization in __new__ instead
of __init__.

But that isn't documented anywhere...

It's not documented for any immutable type. This should be fixed.

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.

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.

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?

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.

Probably also wouldn't go amiss to put some notes near the docs for common immutable types that people might subclass: datetime, maybe tuple?

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

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

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

Thanks for the patch, Raymond! ✨ 🍰 ✨