wxPython/wx/py/introspect.py

   1 """Provides a variety of introspective-type support functions for
   2 things like call tips and command auto completion."""
   3
   4 __author__ = "Patrick K. O'Brien <pobrien@orbtech.com>"
   5 __cvsid__ = "$Id$"
   6 __revision__ = "$Revision$"[11:-2]
   7
   8 from __future__ import nested_scopes
   9
  10 import cStringIO
  11 import inspect
  12 import sys
  13 import tokenize
  14 import types
  15
  16 try:
  17     True
  18 except NameError:
  19     True = 1==1
  20     False = 1==0
  21
  22 def getAutoCompleteList(command='', locals=None, includeMagic=1,
  23                         includeSingle=1, includeDouble=1):
  24     """Return list of auto-completion options for command.
  25
  26     The list of options will be based on the locals namespace."""
  27     attributes = []
  28     # Get the proper chunk of code from the command.
  29     root = getRoot(command, terminator='.')
  30     try:
  31         if locals is not None:
  32             object = eval(root, locals)
  33         else:
  34             object = eval(root)
  35     except:
  36         pass
  37     else:
  38         attributes = getAttributeNames(object, includeMagic,
  39                                        includeSingle, includeDouble)
  40     return attributes
  41
  42 def getAttributeNames(object, includeMagic=1, includeSingle=1,
  43                       includeDouble=1):
  44     """Return list of unique attributes, including inherited, for object."""
  45     attributes = []
  46     dict = {}
  47     if not hasattrAlwaysReturnsTrue(object):
  48         # Add some attributes that don't always get picked up.  If
  49         # they don't apply, they'll get filtered out at the end.
  50         attributes += ['__bases__', '__class__', '__dict__', '__name__',
  51                        'func_closure', 'func_code', 'func_defaults',
  52                        'func_dict', 'func_doc', 'func_globals', 'func_name']
  53     if includeMagic:
  54         try: attributes += object._getAttributeNames()
  55         except: pass
  56     # Get all attribute names.
  57     attrdict = getAllAttributeNames(object)
  58     for attrlist in attrdict.values():
  59         attributes += attrlist
  60     # Remove duplicates from the attribute list.
  61     for item in attributes:
  62         dict[item] = None
  63     attributes = dict.keys()
  64     attributes.sort(lambda x, y: cmp(x.upper(), y.upper()))
  65     if not includeSingle:
  66         attributes = filter(lambda item: item[0]!='_' \
  67                             or item[1]=='_', attributes)
  68     if not includeDouble:
  69         attributes = filter(lambda item: item[:2]!='__', attributes)
  70     # Make sure we haven't picked up any bogus attributes somehow.
  71     attributes = [attribute for attribute in attributes \
  72                   if hasattr(object, attribute)]
  73     return attributes
  74
  75 def hasattrAlwaysReturnsTrue(object):
  76     return hasattr(object, 'bogu5_123_aTTri8ute')
  77
  78 def getAllAttributeNames(object):
  79     """Return dict of all attributes, including inherited, for an object.
  80
  81     Recursively walk through a class and all base classes.
  82     """
  83     attrdict = {}  # (object, technique, count): [list of attributes]
  84     # !!!
  85     # Do Not use hasattr() as a test anywhere in this function,
  86     # because it is unreliable with remote objects: xmlrpc, soap, etc.
  87     # They always return true for hasattr().
  88     # !!!
  89     try:
  90         # Yes, this can fail if object is an instance of a class with
  91         # __str__ (or __repr__) having a bug or raising an
  92         # exception. :-(
  93         key = str(object)
  94     except:
  95         key = 'anonymous'
  96     # Wake up sleepy objects - a hack for ZODB objects in "ghost" state.
  97     wakeupcall = dir(object)
  98     del wakeupcall
  99     # Get attributes available through the normal convention.
 100     attributes = dir(object)
 101     attrdict[(key, 'dir', len(attributes))] = attributes
 102     # Get attributes from the object's dictionary, if it has one.
 103     try:
 104         attributes = object.__dict__.keys()
 105         attributes.sort()
 106     except:  # Must catch all because object might have __getattr__.
 107         pass
 108     else:
 109         attrdict[(key, '__dict__', len(attributes))] = attributes
 110     # For a class instance, get the attributes for the class.
 111     try:
 112         klass = object.__class__
 113     except:  # Must catch all because object might have __getattr__.
 114         pass
 115     else:
 116         if klass is object:
 117             # Break a circular reference. This happens with extension
 118             # classes.
 119             pass
 120         else:
 121             attrdict.update(getAllAttributeNames(klass))
 122     # Also get attributes from any and all parent classes.
 123     try:
 124         bases = object.__bases__
 125     except:  # Must catch all because object might have __getattr__.
 126         pass
 127     else:
 128         if isinstance(bases, types.TupleType):
 129             for base in bases:
 130                 if type(base) is types.TypeType:
 131                     # Break a circular reference. Happens in Python 2.2.
 132                     pass
 133                 else:
 134                     attrdict.update(getAllAttributeNames(base))
 135     return attrdict
 136
 137 def getCallTip(command='', locals=None):
 138     """For a command, return a tuple of object name, argspec, tip text.
 139
 140     The call tip information will be based on the locals namespace."""
 141     calltip = ('', '', '')  # object name, argspec, tip text.
 142     # Get the proper chunk of code from the command.
 143     root = getRoot(command, terminator='(')
 144     try:
 145         if locals is not None:
 146             object = eval(root, locals)
 147         else:
 148             object = eval(root)
 149     except:
 150         return calltip
 151     name = ''
 152     object, dropSelf = getBaseObject(object)
 153     try:
 154         name = object.__name__
 155     except AttributeError:
 156         pass
 157     tip1 = ''
 158     argspec = ''
 159     if inspect.isbuiltin(object):
 160         # Builtin functions don't have an argspec that we can get.
 161         pass
 162     elif inspect.isfunction(object):
 163         # tip1 is a string like: "getCallTip(command='', locals=None)"
 164         argspec = apply(inspect.formatargspec, inspect.getargspec(object))
 165         if dropSelf:
 166             # The first parameter to a method is a reference to an
 167             # instance, usually coded as "self", and is usually passed
 168             # automatically by Python; therefore we want to drop it.
 169             temp = argspec.split(',')
 170             if len(temp) == 1:  # No other arguments.
 171                 argspec = '()'
 172             else:  # Drop the first argument.
 173                 argspec = '(' + ','.join(temp[1:]).lstrip()
 174         tip1 = name + argspec
 175     doc = ''
 176     if callable(object):
 177         try:
 178             doc = inspect.getdoc(object)
 179         except:
 180             pass
 181     if doc:
 182         # tip2 is the first separated line of the docstring, like:
 183         # "Return call tip text for a command."
 184         # tip3 is the rest of the docstring, like:
 185         # "The call tip information will be based on ... <snip>
 186         firstline = doc.split('\n')[0].lstrip()
 187         if tip1 == firstline:
 188             tip1 = ''
 189         else:
 190             tip1 += '\n\n'
 191         docpieces = doc.split('\n\n')
 192         tip2 = docpieces[0]
 193         tip3 = '\n\n'.join(docpieces[1:])
 194         tip = '%s%s\n\n%s' % (tip1, tip2, tip3)
 195     else:
 196         tip = tip1
 197     calltip = (name, argspec[1:-1], tip.strip())
 198     return calltip
 199
 200 def getRoot(command, terminator=None):
 201     """Return the rightmost root portion of an arbitrary Python command.
 202
 203     Return only the root portion that can be eval()'d without side
 204     effects.  The command would normally terminate with a '(' or
 205     '.'. The terminator and anything after the terminator will be
 206     dropped."""
 207     command = command.split('\n')[-1]
 208     if command.startswith(sys.ps2):
 209         command = command[len(sys.ps2):]
 210     command = command.lstrip()
 211     command = rtrimTerminus(command, terminator)
 212     tokens = getTokens(command)
 213     if not tokens:
 214         return ''
 215     if tokens[-1][0] is tokenize.ENDMARKER:
 216         # Remove the end marker.
 217         del tokens[-1]
 218     if not tokens:
 219         return ''
 220     if terminator == '.' and \
 221            (tokens[-1][1] <> '.' or tokens[-1][0] is not tokenize.OP):
 222         # Trap decimals in numbers, versus the dot operator.
 223         return ''
 224     else:
 225         # Strip off the terminator.
 226         if terminator and command.endswith(terminator):
 227             size = 0 - len(terminator)
 228             command = command[:size]
 229     command = command.rstrip()
 230     tokens = getTokens(command)
 231     tokens.reverse()
 232     line = ''
 233     start = None
 234     prefix = ''
 235     laststring = '.'
 236     emptyTypes = ('[]', '()', '{}')
 237     for token in tokens:
 238         tokentype = token[0]
 239         tokenstring = token[1]
 240         line = token[4]
 241         if tokentype is tokenize.ENDMARKER:
 242             continue
 243         if tokentype in (tokenize.NAME, tokenize.STRING, tokenize.NUMBER) \
 244         and laststring != '.':
 245             # We've reached something that's not part of the root.
 246             if prefix and line[token[3][1]] != ' ':
 247                 # If it doesn't have a space after it, remove the prefix.
 248                 prefix = ''
 249             break
 250         if tokentype in (tokenize.NAME, tokenize.STRING, tokenize.NUMBER) \
 251         or (tokentype is tokenize.OP and tokenstring == '.'):
 252             if prefix:
 253                 # The prefix isn't valid because it comes after a dot.
 254                 prefix = ''
 255                 break
 256             else:
 257                 # start represents the last known good point in the line.
 258                 start = token[2][1]
 259         elif len(tokenstring) == 1 and tokenstring in ('[({])}'):
 260             # Remember, we're working backwords.
 261             # So prefix += tokenstring would be wrong.
 262             if prefix in emptyTypes and tokenstring in ('[({'):
 263                 # We've already got an empty type identified so now we
 264                 # are in a nested situation and we can break out with
 265                 # what we've got.
 266                 break
 267             else:
 268                 prefix = tokenstring + prefix
 269         else:
 270             # We've reached something that's not part of the root.
 271             break
 272         laststring = tokenstring
 273     if start is None:
 274         start = len(line)
 275     root = line[start:]
 276     if prefix in emptyTypes:
 277         # Empty types are safe to be eval()'d and introspected.
 278         root = prefix + root
 279     return root
 280
 281 def getTokens(command):
 282     """Return list of token tuples for command."""
 283     command = str(command)  # In case the command is unicode, which fails.
 284     f = cStringIO.StringIO(command)
 285     # tokens is a list of token tuples, each looking like:
 286     # (type, string, (srow, scol), (erow, ecol), line)
 287     tokens = []
 288     # Can't use list comprehension:
 289     #   tokens = [token for token in tokenize.generate_tokens(f.readline)]
 290     # because of need to append as much as possible before TokenError.
 291     try:
 292 ##        This code wasn't backward compatible with Python 2.1.3.
 293 ##
 294 ##        for token in tokenize.generate_tokens(f.readline):
 295 ##            tokens.append(token)
 296
 297         # This works with Python 2.1.3 (with nested_scopes).
 298         def eater(*args):
 299             tokens.append(args)
 300         tokenize.tokenize_loop(f.readline, eater)
 301     except tokenize.TokenError:
 302         # This is due to a premature EOF, which we expect since we are
 303         # feeding in fragments of Python code.
 304         pass
 305     return tokens
 306
 307 def rtrimTerminus(command, terminator=None):
 308     """Return command minus anything that follows the final terminator."""
 309     if terminator:
 310         pieces = command.split(terminator)
 311         if len(pieces) > 1:
 312             command = terminator.join(pieces[:-1]) + terminator
 313     return command
 314
 315 def getBaseObject(object):
 316     """Return base object and dropSelf indicator for an object."""
 317     if inspect.isbuiltin(object):
 318         # Builtin functions don't have an argspec that we can get.
 319         dropSelf = 0
 320     elif inspect.ismethod(object):
 321         # Get the function from the object otherwise
 322         # inspect.getargspec() complains that the object isn't a
 323         # Python function.
 324         try:
 325             if object.im_self is None:
 326                 # This is an unbound method so we do not drop self
 327                 # from the argspec, since an instance must be passed
 328                 # as the first arg.
 329                 dropSelf = 0
 330             else:
 331                 dropSelf = 1
 332             object = object.im_func
 333         except AttributeError:
 334             dropSelf = 0
 335     elif inspect.isclass(object):
 336         # Get the __init__ method function for the class.
 337         constructor = getConstructor(object)
 338         if constructor is not None:
 339             object = constructor
 340             dropSelf = 1
 341         else:
 342             dropSelf = 0
 343     elif callable(object):
 344         # Get the __call__ method instead.
 345         try:
 346             object = object.__call__.im_func
 347             dropSelf = 1
 348         except AttributeError:
 349             dropSelf = 0
 350     else:
 351         dropSelf = 0
 352     return object, dropSelf
 353
 354 def getConstructor(object):
 355     """Return constructor for class object, or None if there isn't one."""
 356     try:
 357         return object.__init__.im_func
 358     except AttributeError:
 359         for base in object.__bases__:
 360             constructor = getConstructor(base)
 361             if constructor is not None:
 362                 return constructor
 363     return None