[Python-Dev] slots, properties, descriptors, and pydoc (original) (raw)

John Belmonte john at neggie.net
Tue Apr 13 13:10:10 EDT 2004

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.

-John

-- http:// if ile.org/

More information about the Python-Dev mailing list