wxPython/wxPython/lib/PyCrust/wxd/decorator.py

   1 """Decorator utility for documentation and shell scripting."""
   2
   3 __author__ = "Patrick K. O'Brien <pobrien@orbtech.com>"
   4 __cvsid__ = "$Id$"
   5 __revision__ = "$Revision$"[11:-2]
   6
   7
   8 import inspect
   9
  10 try:
  11     True
  12 except NameError:
  13     True = 1==1
  14     False = 1==0
  15
  16 def decorate(real, decoration):
  17     """Decorate real module with docstrings from decoration module."""
  18     realdict = real.__dict__
  19     for item in decoration.__dict__.values():
  20         if inspect.isclass(item):
  21             decorateClass(item, realdict)
  22         elif inspect.isfunction(item):
  23             decorateFunction(item, realdict)
  24
  25 def decorateClass(item, realdict):
  26     classname = item.__name__
  27     if not classname.startswith('wx'):
  28         classname = 'wx' + classname
  29     try:
  30         wxclass = realdict[classname]
  31     except:
  32         print classname
  33     else:
  34         if item.__doc__:
  35             wxclass.__doc__ = item.__doc__
  36         # Get attributes from only the item's local dictionary!
  37         for attrname, attr in item.__dict__.items():
  38             # If the attribute has a docstring, and the wx class has a
  39             # matching attribute.
  40             if hasattr(attr, '__doc__') and hasattr(wxclass, attrname):
  41                 if inspect.isfunction(attr):
  42                     # Class methods are functions.
  43                     doc = getdoc(attr, drop=True)
  44                     # Is getattr() okay, or do we want to only look in
  45                     # the wxclass.__dict__ and wxclassPtr.__dict__?
  46                     wxattr = getattr(wxclass, attrname)
  47                     # Our class code may be defined incorrectly, and
  48                     # the wxattr may not actually be a class method,
  49                     # but that's okay because the following attempt
  50                     # will simply fail.
  51                     try:
  52                         func = wxattr.im_func
  53                         func.__doc__ = doc
  54                     except:
  55                         pass
  56
  57 def decorateFunction(item, realdict):
  58     funcname = item.__name__
  59     if funcname in realdict.keys():
  60         func = realdict[funcname]
  61         doc = getdoc(item, drop=False)
  62         try:
  63             # Built-in functions have a read-only docstring. :-(
  64             func.__doc__ = doc
  65         except:
  66             # print funcname
  67             pass
  68
  69 def getdoc(attr, drop=False):
  70     """Return a docstring for attr, which should be a method."""
  71     doc = ''
  72     if attr.__doc__:
  73         doc = inspect.getdoc(attr).strip()
  74     name = attr.__name__
  75     # tip is a string with name(argspec), like: "SetLabel(label)"
  76     tip = ''
  77     argspec = apply(inspect.formatargspec, inspect.getargspec(attr))
  78     # The first parameter to a method is a reference to an instance,
  79     # usually coded as "self", and is usually passed automatically by
  80     # Python and therefore we want to drop it.
  81     temp = argspec.split(',')
  82     if len(temp) == 1:  # No other arguments.
  83         argspec = '()'
  84     elif drop:  # Drop the first argument.
  85         argspec = '(' + ','.join(temp[1:]).lstrip()
  86     else:
  87         argspec = ','.join(temp).lstrip()
  88     tip = name + argspec
  89     firstline = doc.split('\n')[0].lstrip()
  90     if tip != firstline:
  91         doc = '%s\n\n%s' % (tip, doc)
  92     return doc