[Python-Dev] slots, properties, descriptors, and pydoc

[John Belmonte]

Hello,

I'd like to make some observations and proposals about pydoc regarding 
slots, properties, and descriptors in general.

Given this program:

     class CountingDescriptor(object):

         def __init__(self, doc=None):
             self.val = 0
             self.__doc__ = doc

         def __get__(self, obj, objtype):
             self.val += 1
             return self.val


     class Foo(object):
         __slots__ = {'bar': 'slot doc test'}

         counter = CountingDescriptor(doc='descriptor doc test')

         def _set_counter_multiple(self, val):
             print 'I hear you want to set me to %s?' % val

         counter_multiple = property(
             lambda self: self.counter*2,
             _set_counter_multiple,
             doc='property doc test'
         )

     print help(Foo)


The output is:

     Help on class Foo in module __main__:

     class Foo(__builtin__.object)
      |  Properties defined here:
      |
      |  counter_multiple
      |      property doc test
      |
      |      lambdaself
      |
      |      <set> = _set_counter_multiple(self, val)
      |
      |  ------------------------------------------------------------
      |  Data and other attributes defined here:
      |
      |  __slots__ = {'bar': 'slot doc test'}
      |
      |  bar = <member 'bar' of 'Foo' objects>
      |
      |  counter = 2


Observations (in order from least to most arguable :-):

     1) pydoc's property display doesn't handle lambda well

     2) pydoc doesn't show the doc string of general descriptors

     3) Using dictionary values as a way to set the doc string of slots, 
as suggested in Guido's "Unifying types and classes", has not been 
implemented.  Currently there is no way to set a doc string on a 
descriptor generated by __slots__.  Even if you could, pydoc would not 
display it, according to #2.

     4) pydoc is displaying implementation details of properties (set 
and get method names, etc.).  Such details should probably not be 
displayed, similar to underbar-prefixed method and data attributes.

Proposals:

     1) remove property-specific handling from pydoc

     2) extend pydoc with descriptor-specific handling.  In a section 
called "Descriptors defined here", list each attribute name, with 
associated doc string if it exists.

     3) extend the __slots__ handler to set the descriptor's doc string 
to dictionary values if the slot's value is a dictionary.  This is the 
only Python change being proposed.

     4) have pydoc make a special case for the display of __slots__. 
Alternatives:
         A) don't display __slots__ if the value is a dictionary.  The 
display of __slots__ is redundant, because all items are displayed 
according to #2.
         B) if for some reason distinguishing slots from other 
descriptors is essential, then always display __slots__, but normalize 
it to a list of attribute names (show only dictionary keys, etc.)


With these changes, the new output of the example would be:

     Help on class Foo in module __main__:

     class Foo(__builtin__.object)
      |  Descriptors defined here:
      |
      |  bar
      |      slot doc test
      |
      |  counter
      |      descriptor doc test
      |
      |  counter_multiple
      |      property doc test



I'd be willing to work on a PEP.  If these issues are covered in or 
conflict with an existing PEP, please let me know.

Thanks,
-John


-- 
http:// if  ile.org/