[issue1734] documentation on metaclasses is incomplete and misleading

[L. Peter Deutsch]

L. Peter Deutsch added the comment:

Please reopen this issue as a documentation bug.

The documentation for __new__ in section 3.4.1 says:

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

The documentation for metaclasses in 3.4.3 says nothing about __new__
vs. __init__. It says the metaclass will be "called" for class creation,
and it says the metaclass can be any "callable". This would imply the
use of __call__ rather than __new__ or __init__.

I think 3.4.1 should say:

__new__() is intended mainly to allow subclasses of immutable types
(like int, str, or tuple) to customize instance creation. It is also
used for custom metaclasses (q.v.).

I think 3.4.3 should be reviewed in its entirety to replace the
misleading language about "called" and "callable" with language that
explicitly mentions __new__.

----------
title: no effect if metaclass modifies dict -> documentation on metaclasses is incomplete and misleading

__________________________________
Tracker <report at bugs.python.org>
<http://bugs.python.org/issue1734>
__________________________________