Should Python documentation for __class__ be improved?

[Tom Funk]

This is my *last* post regarding this UserList thing. Promise! <g>

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.

When I started playing around with __class__ in interactive mode I began  
to see the light:

  >>> ul=UserList.UserList([0,1,2,3,4])
  >>> ul
  [0, 1, 2, 3, 4]
  >>> ul.__class__
  <class UserList.UserList at 1731e50>
  >>> type(ul)
  <type 'instance'>
  >>> type(ul.__class__)
  <type 'class'>
  >>> type(ul.__class__())
  <type 'instance'>
  >>> ul.__class__()
  []
  >>> ul.__class__([9,8,7,6]))
  [9, 8, 7, 6]
  >>> type(ul.__class__([9,8,7,6]))
  <type 'instance'>
  >>> ul2 = ul.__class__()
  []
  >>> ul2.__class__ # note same location as above!
  <class UserList.UserList at 1731e50> 
  >>> type(ul2.__class__)
  <type 'class'
  >>> ul2.__class__ is ul2.__class__  # are they the same object??
  1 
  >>> # apparently so

So, what __class__ *really* is, is: 

  o  a reference to where the class itself is imported 
     into the current name space.  
  o  that reference is callable and 
  o  when called it creates a new instance of the class  
     i.e., 

         c=Class(arg,...) 

      is the same as 

         c=self.__class__(arg,...)

(Pretty cool stuff, Guido! :-)

However, the docs are vague on all of this.  Here are the only references 
I could find for __class__ (I used the Win32 HTML help for Python version 
1.5.2):

_Python Library Reference_

   "2.1.8 Special Attributes"

     __class__ 

        The class to which a class instance belongs. 

_Python Reference Manual_ 

   "3.2 The standard type hierarchy"

      __class__ is the instance's class

_Python Tutorial_

   "9.7.1 Exceptions Can Be Classes" 

      There are two new valid (semantic) forms for the raise statement: 

         raise Class, instance
         raise instance

       In the first form, instance must be an instance of Class 
       or of a class derived from it. The second form is a shorthand 
       for 

          raise instance.__class__, instance

(this hints at the significance of __class__)

The final clue came from Mark Lutz' _Programming Python_ (O'Reilly & 
Assoc., (c) 1996), page 333:

   "The __class__ special attribute is a reference to a class's
    instance's class object -- the one that the instance was 
    formed from."

Bingo!

And Marks shows, indirectly, on the previous page that __class__ is 
callable:

  myclass = self.__class__ # instance's (lowest) class object
  myclass(new)             # attach/run instance of my class


(Way to go, Mark!)  

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.

It took me an hour worth of digging (I should have gone to _Programming 
Python_ first <wink>) to find out what that one line of code was doing.  
I wonder if anyone else has met the same fate.
    
Thanks for listening, folks.

-- 
-=< tom >=-
Thomas D. Funk                           |       "Software is the lever
Software Engineering Consultant          | Archimedes was searching for"
Advanced Systems Design, Tallahassee FL. |