[Tutor] Set/get doc strings of ALL attributes?

[pan at uchicago.edu]

Hi there,

I've been wondering if there's a way to set/get doc string
for ALL elements of a class (but not just the __doc__ of
function/method).

I ended writing a class BaseObject for this purpose. It stores doc 
strings of variables (that is, the <name> that is assigned to a 
class using myclass.name). When asking for all docs, doc strings 
are collected from 3 different sources:

1) property __doc__;
2) the variables mentioned above;
3) function/method __doc__;

It seems to work well. My questions:

A) Will the above approach be able to cover all elements 
   such that an automatic documentation mechinsm can be
   programmed?

B) Is there any other better way to do this?

C) I intend to use this class as the base class for all 
   other subclass. Will this kind of design cause any problem 
   in any class inherited from it?

Thx in advance.
pan


Here's the code:

class BaseObject(object):
  '''An extention of class object, have the capacity of storing/retrieving
     doc string for variables. Doc strings are retrievd from 3 different
     elements: variable (name), property, and method (or function). See
     the code in getDoc() for how to retrieve them.
  '''
  def __init__(self):
     object.__init__(self)
     self.__docs__ ={'__docs__':'An internal dict storing doc'
     ' string of variables. Write: setattr(name, val, doc) or'
     ' setDoc(name, doc), read: getDoc(name) or getDocs().'
     ' Defined in class BaseObject.'}
     
  def setattr(self, name, val, doc=None):
     '''setattr(name, val, doc=None): set value and doc string 
      of a variable <name>. If doc=None, doc is not changed
      Defined in class BaseObject.''' 

     if doc!=None: self.__docs__[name] = doc
     self.__setattr__(name,val)
     return self
    
  def setDoc(self, name, doc, checkName=1):
      '''setDoc(name, doc, checkName=1): Set doc string of variable.
       Defined in class BaseObject.'''
      
      if checkName and (name not in self.__dict__):
         pass
      else:
         self.__docs__[name] = doc

  def getDoc(self, name):
      '''getDoc(name): get the doc string of <name>.
         Defined in BaseObject.'''
      
      fromProperty = lambda x: self.__class__.__dict__[x].__doc__
      fromVariable = lambda x: self.__docs__[x]
      fromMethod   = lambda x: getattr(self, x).__doc__.strip().replace('\n','')
          
      try:
          txt = fromProperty(name)
      except:
          try:
              txt = fromVariable(name)
          except:
              try:
                  txt = fromMethod(name)
              except:
                  txt = ''

      if txt==None or txt=='':
         return txt
      else:
        return re.sub('\s+', ' ', txt)
      
  def getDocs(self):
      '''getDocs(): return a dict representing the doc strings
         of all attributes(variables, properties, functions,
         methods...) of this class. Defined in BaseObject.''' 
      
      dic = {}
      for x in dir(self):
          if not x.startswith('_'):
             dic[x] = self.getDoc(x)
      return dic

  
class MyObj(BaseObject):
    def __init__(self):
        BaseObject.__init__(self)
        self.setattr('name', 'myobj', 'this is my obj')
        self._size=10
    def setSize(self, size): self._size=size
    def getSize(self): return self._size
    size= property(getSize, setSize, None, 'Size of the object')

def test():
    mo = MyObj()
    x = mo.getDocs()
    print x
 
text()