In the following, dir(Node) should include the name 'z', and Node.z
should be 'Node'. However, dir(Node) does not include 'z', and Node.z is
undefined (AttributeError). This is directly contrary to the Python
documentation, which says "metaclasses can modify dict".

class MetaNode(type):
    def __init__(cls, name, bases, cdict):
        cdict['z'] = name
        type.__init__(name, bases, cdict)
class Node(object):
    __metaclass__ = MetaNode

print dir(Node)
print Node.z

When designing a metaclass, you should override __new__, not __init__:

class MetaNode(type):
   def __new__(cls, name, bases, cdict):
       cdict['z'] = name
       return type.__new__(cls, name, bases, cdict)

class Node(object):
   __metaclass__ = MetaNode

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__.

I'll look into it.

Actually, "called" and "callable" are OK, if the documentation says
somewhere that the normal effect of "calling" a type object is to invoke
__new__. The places I looked first (sections 3.1, 3.3, and 3.4.1) do not
say this. 5.3.4 does say that the result of calling a class object is a
new instance of that class, but it doesn't mention __new__. So perhaps
it would OK to just add something like the following to 3.4.3:

Note that if a metaclass is a subclass of <code>type</code>, it should
override <code>__new__</code>, not <code>__call__</code>.

This should now be appropriately explained in the trunk, r59837. I also
added an example of using __new__ in a metaclass.