Should Python documentation for __class__ be improved?

[Remco Gerlich]

Tom Funk wrote in comp.lang.python:
> While tracking down the UserList problems I've previously discussed I ran 
> across this line of code in UserList.__getslice__():
> 
>     userlist = self.__class__()
> 
> I'd never seen this idiom before and I wasn't sure exactly what was going 
> on.  So I started tearing up the Python docs looking for an explanation.  
> 
> 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.

Well, it's not really 'callable'. __class__ *is* just an attribute. It's
just a reference to a class. And you can make an instance of a class.

class A:
   pass
   
a = A()

Now A == a.__class__.

So, obviously,
x = A()
now means the same thing as
x = a.__class__()

It's never explained that you can make an instance of __class__, since you
can make an instance of any class, and this one isn't any different. It's
slightly confusing that making a class instance looks like a function call.

-- 
Remco Gerlich,  scarblac at pino.selwerd.nl
  Murphy's Rules, "I sense... golden arches":
   In Original D&D, some swords had the ability to 'detect meal and what
   kind.'