Should Python documentation for __class__ be improved?

[Martin von Loewis]

Tom Funk <_spam_sux_tdfunk at _spam_sux_nettally.com> writes:

> I found a number of references to __class__, all of which made it look as 
> though __class__ was an attribute, rather than a method (though it's not 
> technically a method either).  Nowhere did I find anything that said  
> that __class__ was callable.  Also, there are *no* examples of calling 
> __class__() anywhere in the docs.

I hope you found http://www.python.org/doc/current/ref/types.html,
which explains what "class objects" and "class instance objects" are.

> 
>   >>> ul.__class__
>   <class UserList.UserList at 1731e50>

What you may try also is

>>> UserList.UserList
<class UserList.UserList at 1731e50>

The critical thing to understand is that classes are objects in
Python, and an instance's __class__ attribute is a reference to the
class object. Class objects themselves are callable; I'm sure you
noticed that you write

>>> x=UserList.UserList()

Calling a class creates an instance. Since the __class__ attribute
*is* the class object, it is also callable.

> So, what __class__ *really* is, is: 
> 
>   o  a reference to where the class itself is imported 
>      into the current name space.  

No,

    o a reference to the class object used to create the instance.

> Is it just me, or might the documentation be expanded on this matter?  It 
> seems to me that a little more detail would be in order.

If you read the types page from the beginning to the end, you should
notice the discussion of "Class", after which " __class__ is the
instance's class" should be clear. However, if it isn't, it is
difficult for the documentation write to know how the wording should
be to make it clearer. So it would be good if you submitted improved
wording yourself <no, I won't use wink>

Regards,
Martin