homepage

The current descrintro.html says:
"__new__ must return an object... If you return an
existing object, the constructor call will still call
its __init__ method. If you return an object of a
different class, its __init__ method will be called..."
This suggests that __new__ will call __init__ of the
object even if the object is a different type. The
code in typeobject.c disagrees with this:
static PyObject *
type_call(PyTypeObject *type, PyObject *args, PyObject
*kwds)
{
	...
	/* If the returned object is not an instance of type,
	 it won't be initialized. */
	if (!PyType_IsSubtype(obj->ob_type, type))
		return obj;
	...
}
Suggested fix:
"__new__ must return an object... If you return an
existing object, the constructor call will still call
its __init__ method unless the object is an instance of
a different class..."

Logged In: YES 
user_id=99874
I agree strongly that the docs need to be clarified.
I spent a while playing around with it and confirmed that
your reading of it appears to be correct, and your proposed
wording is simple and straightforward.
I second the request to make this change.

Documentation had several updates in these 2+ years.
Now it says:
"""
If __new__() returns an instance of cls, then the new instance’s
__init__() method will be invoked like __init__(self[, ...]), where self
is the new instance and the remaining arguments are the same as were
passed to __new__().
If __new__() does not return an instance of cls, then the new instance’s
__init__() method will not be invoked.
"""
, which is clearer.
Thanks!