Lib/inspect.py

   1 # -*- coding: iso-8859-1 -*-
   2 """Get useful information from live Python objects.
   3
   4 This module encapsulates the interface provided by the internal special
   5 attributes (func_*, co_*, im_*, tb_*, etc.) in a friendlier fashion.
   6 It also provides some help for examining source code and class layout.
   7
   8 Here are some of the useful functions provided by this module:
   9
  10     ismodule(), isclass(), ismethod(), isfunction(), isgeneratorfunction(),
  11         isgenerator(), istraceback(), isframe(), iscode(), isbuiltin(),
  12         isroutine() - check object types
  13     getmembers() - get members of an object that satisfy a given condition
  14
  15     getfile(), getsourcefile(), getsource() - find an object's source code
  16     getdoc(), getcomments() - get documentation on an object
  17     getmodule() - determine the module that an object came from
  18     getclasstree() - arrange classes so as to represent their hierarchy
  19
  20     getargspec(), getargvalues() - get info about function arguments
  21     formatargspec(), formatargvalues() - format an argument spec
  22     getouterframes(), getinnerframes() - get info about frames
  23     currentframe() - get the current stack frame
  24     stack(), trace() - get info about frames on the stack or in a traceback
  25 """
  26
  27 # This module is in the public domain.  No warranties.
  28
  29 __author__ = 'Ka-Ping Yee <ping@lfw.org>'
  30 __date__ = '1 Jan 2001'
  31
  32 import sys
  33 import os
  34 import types
  35 import string
  36 import re
  37 import dis
  38 import imp
  39 import tokenize
  40 import linecache
  41 from operator import attrgetter
  42 from collections import namedtuple
  43
  44 # These constants are from Include/code.h.
  45 CO_OPTIMIZED, CO_NEWLOCALS, CO_VARARGS, CO_VARKEYWORDS = 0x1, 0x2, 0x4, 0x8
  46 CO_NESTED, CO_GENERATOR, CO_NOFREE = 0x10, 0x20, 0x40
  47 # See Include/object.h
  48 TPFLAGS_IS_ABSTRACT = 1 << 20
  49
  50 # ----------------------------------------------------------- type-checking
  51 def ismodule(object):
  52     """Return true if the object is a module.
  53
  54     Module objects provide these attributes:
  55         __doc__         documentation string
  56         __file__        filename (missing for built-in modules)"""
  57     return isinstance(object, types.ModuleType)
  58
  59 def isclass(object):
  60     """Return true if the object is a class.
  61
  62     Class objects provide these attributes:
  63         __doc__         documentation string
  64         __module__      name of module in which this class was defined"""
  65     return isinstance(object, (type, types.ClassType))
  66
  67 def ismethod(object):
  68     """Return true if the object is an instance method.
  69
  70     Instance method objects provide these attributes:
  71         __doc__         documentation string
  72         __name__        name with which this method was defined
  73         im_class        class object in which this method belongs
  74         im_func         function object containing implementation of method
  75         im_self         instance to which this method is bound, or None"""
  76     return isinstance(object, types.MethodType)
  77
  78 def ismethoddescriptor(object):
  79     """Return true if the object is a method descriptor.
  80
  81     But not if ismethod() or isclass() or isfunction() are true.
  82
  83     This is new in Python 2.2, and, for example, is true of int.__add__.
  84     An object passing this test has a __get__ attribute but not a __set__
  85     attribute, but beyond that the set of attributes varies.  __name__ is
  86     usually sensible, and __doc__ often is.
  87
  88     Methods implemented via descriptors that also pass one of the other
  89     tests return false from the ismethoddescriptor() test, simply because
  90     the other tests promise more -- you can, e.g., count on having the
  91     im_func attribute (etc) when an object passes ismethod()."""
  92     return (hasattr(object, "__get__")
  93             and not hasattr(object, "__set__") # else it's a data descriptor
  94             and not ismethod(object)           # mutual exclusion
  95             and not isfunction(object)
  96             and not isclass(object))
  97
  98 def isdatadescriptor(object):
  99     """Return true if the object is a data descriptor.
 100
 101     Data descriptors have both a __get__ and a __set__ attribute.  Examples are
 102     properties (defined in Python) and getsets and members (defined in C).
 103     Typically, data descriptors will also have __name__ and __doc__ attributes
 104     (properties, getsets, and members have both of these attributes), but this
 105     is not guaranteed."""
 106     return (hasattr(object, "__set__") and hasattr(object, "__get__"))
 107
 108 if hasattr(types, 'MemberDescriptorType'):
 109     # CPython and equivalent
 110     def ismemberdescriptor(object):
 111         """Return true if the object is a member descriptor.
 112
 113         Member descriptors are specialized descriptors defined in extension
 114         modules."""
 115         return isinstance(object, types.MemberDescriptorType)
 116 else:
 117     # Other implementations
 118     def ismemberdescriptor(object):
 119         """Return true if the object is a member descriptor.
 120
 121         Member descriptors are specialized descriptors defined in extension
 122         modules."""
 123         return False
 124
 125 if hasattr(types, 'GetSetDescriptorType'):
 126     # CPython and equivalent
 127     def isgetsetdescriptor(object):
 128         """Return true if the object is a getset descriptor.
 129
 130         getset descriptors are specialized descriptors defined in extension
 131         modules."""
 132         return isinstance(object, types.GetSetDescriptorType)
 133 else:
 134     # Other implementations
 135     def isgetsetdescriptor(object):
 136         """Return true if the object is a getset descriptor.
 137
 138         getset descriptors are specialized descriptors defined in extension
 139         modules."""
 140         return False
 141
 142 def isfunction(object):
 143     """Return true if the object is a user-defined function.
 144
 145     Function objects provide these attributes:
 146         __doc__         documentation string
 147         __name__        name with which this function was defined
 148         func_code       code object containing compiled function bytecode
 149         func_defaults   tuple of any default values for arguments
 150         func_doc        (same as __doc__)
 151         func_globals    global namespace in which this function was defined
 152         func_name       (same as __name__)"""
 153     return isinstance(object, types.FunctionType)
 154
 155 def isgeneratorfunction(object):
 156     """Return true if the object is a user-defined generator function.
 157
 158     Generator function objects provides same attributes as functions.
 159
 160     See isfunction.__doc__ for attributes listing."""
 161     return bool((isfunction(object) or ismethod(object)) and
 162                 object.func_code.co_flags & CO_GENERATOR)
 163
 164 def isgenerator(object):
 165     """Return true if the object is a generator.
 166
 167     Generator objects provide these attributes:
 168         __iter__        defined to support interation over container
 169         close           raises a new GeneratorExit exception inside the
 170                         generator to terminate the iteration
 171         gi_code         code object
 172         gi_frame        frame object or possibly None once the generator has
 173                         been exhausted
 174         gi_running      set to 1 when generator is executing, 0 otherwise
 175         next            return the next item from the container
 176         send            resumes the generator and "sends" a value that becomes
 177                         the result of the current yield-expression
 178         throw           used to raise an exception inside the generator"""
 179     return isinstance(object, types.GeneratorType)
 180
 181 def istraceback(object):
 182     """Return true if the object is a traceback.
 183
 184     Traceback objects provide these attributes:
 185         tb_frame        frame object at this level
 186         tb_lasti        index of last attempted instruction in bytecode
 187         tb_lineno       current line number in Python source code
 188         tb_next         next inner traceback object (called by this level)"""
 189     return isinstance(object, types.TracebackType)
 190
 191 def isframe(object):
 192     """Return true if the object is a frame object.
 193
 194     Frame objects provide these attributes:
 195         f_back          next outer frame object (this frame's caller)
 196         f_builtins      built-in namespace seen by this frame
 197         f_code          code object being executed in this frame
 198         f_exc_traceback traceback if raised in this frame, or None
 199         f_exc_type      exception type if raised in this frame, or None
 200         f_exc_value     exception value if raised in this frame, or None
 201         f_globals       global namespace seen by this frame
 202         f_lasti         index of last attempted instruction in bytecode
 203         f_lineno        current line number in Python source code
 204         f_locals        local namespace seen by this frame
 205         f_restricted    0 or 1 if frame is in restricted execution mode
 206         f_trace         tracing function for this frame, or None"""
 207     return isinstance(object, types.FrameType)
 208
 209 def iscode(object):
 210     """Return true if the object is a code object.
 211
 212     Code objects provide these attributes:
 213         co_argcount     number of arguments (not including * or ** args)
 214         co_code         string of raw compiled bytecode
 215         co_consts       tuple of constants used in the bytecode
 216         co_filename     name of file in which this code object was created
 217         co_firstlineno  number of first line in Python source code
 218         co_flags        bitmap: 1=optimized | 2=newlocals | 4=*arg | 8=**arg
 219         co_lnotab       encoded mapping of line numbers to bytecode indices
 220         co_name         name with which this code object was defined
 221         co_names        tuple of names of local variables
 222         co_nlocals      number of local variables
 223         co_stacksize    virtual machine stack space required
 224         co_varnames     tuple of names of arguments and local variables"""
 225     return isinstance(object, types.CodeType)
 226
 227 def isbuiltin(object):
 228     """Return true if the object is a built-in function or method.
 229
 230     Built-in functions and methods provide these attributes:
 231         __doc__         documentation string
 232         __name__        original name of this function or method
 233         __self__        instance to which a method is bound, or None"""
 234     return isinstance(object, types.BuiltinFunctionType)
 235
 236 def isroutine(object):
 237     """Return true if the object is any kind of function or method."""
 238     return (isbuiltin(object)
 239             or isfunction(object)
 240             or ismethod(object)
 241             or ismethoddescriptor(object))
 242
 243 def isgenerator(object):
 244     """Return true if the object is a generator object."""
 245     return isinstance(object, types.GeneratorType)
 246
 247 def isabstract(object):
 248     """Return true if the object is an abstract base class (ABC)."""
 249     return isinstance(object, type) and object.__flags__ & TPFLAGS_IS_ABSTRACT
 250
 251 def getmembers(object, predicate=None):
 252     """Return all members of an object as (name, value) pairs sorted by name.
 253     Optionally, only return members that satisfy a given predicate."""
 254     results = []
 255     for key in dir(object):
 256         try:
 257             value = getattr(object, key)
 258         except AttributeError:
 259             continue
 260         if not predicate or predicate(value):
 261             results.append((key, value))
 262     results.sort()
 263     return results
 264
 265 Attribute = namedtuple('Attribute', 'name kind defining_class object')
 266
 267 def classify_class_attrs(cls):
 268     """Return list of attribute-descriptor tuples.
 269
 270     For each name in dir(cls), the return list contains a 4-tuple
 271     with these elements:
 272
 273         0. The name (a string).
 274
 275         1. The kind of attribute this is, one of these strings:
 276                'class method'    created via classmethod()
 277                'static method'   created via staticmethod()
 278                'property'        created via property()
 279                'method'          any other flavor of method
 280                'data'            not a method
 281
 282         2. The class which defined this attribute (a class).
 283
 284         3. The object as obtained directly from the defining class's
 285            __dict__, not via getattr.  This is especially important for
 286            data attributes:  C.data is just a data object, but
 287            C.__dict__['data'] may be a data descriptor with additional
 288            info, like a __doc__ string.
 289     """
 290
 291     mro = getmro(cls)
 292     names = dir(cls)
 293     result = []
 294     for name in names:
 295         # Get the object associated with the name.
 296         # Getting an obj from the __dict__ sometimes reveals more than
 297         # using getattr.  Static and class methods are dramatic examples.
 298         if name in cls.__dict__:
 299             obj = cls.__dict__[name]
 300         else:
 301             obj = getattr(cls, name)
 302
 303         # Figure out where it was defined.
 304         homecls = getattr(obj, "__objclass__", None)
 305         if homecls is None:
 306             # search the dicts.
 307             for base in mro:
 308                 if name in base.__dict__:
 309                     homecls = base
 310                     break
 311
 312         # Get the object again, in order to get it from the defining
 313         # __dict__ instead of via getattr (if possible).
 314         if homecls is not None and name in homecls.__dict__:
 315             obj = homecls.__dict__[name]
 316
 317         # Also get the object via getattr.
 318         obj_via_getattr = getattr(cls, name)
 319
 320         # Classify the object.
 321         if isinstance(obj, staticmethod):
 322             kind = "static method"
 323         elif isinstance(obj, classmethod):
 324             kind = "class method"
 325         elif isinstance(obj, property):
 326             kind = "property"
 327         elif (ismethod(obj_via_getattr) or
 328               ismethoddescriptor(obj_via_getattr)):
 329             kind = "method"
 330         else:
 331             kind = "data"
 332
 333         result.append(Attribute(name, kind, homecls, obj))
 334
 335     return result
 336
 337 # ----------------------------------------------------------- class helpers
 338 def _searchbases(cls, accum):
 339     # Simulate the "classic class" search order.
 340     if cls in accum:
 341         return
 342     accum.append(cls)
 343     for base in cls.__bases__:
 344         _searchbases(base, accum)
 345
 346 def getmro(cls):
 347     "Return tuple of base classes (including cls) in method resolution order."
 348     if hasattr(cls, "__mro__"):
 349         return cls.__mro__
 350     else:
 351         result = []
 352         _searchbases(cls, result)
 353         return tuple(result)
 354
 355 # -------------------------------------------------- source code extraction
 356 def indentsize(line):
 357     """Return the indent size, in spaces, at the start of a line of text."""
 358     expline = string.expandtabs(line)
 359     return len(expline) - len(string.lstrip(expline))
 360
 361 def getdoc(object):
 362     """Get the documentation string for an object.
 363
 364     All tabs are expanded to spaces.  To clean up docstrings that are
 365     indented to line up with blocks of code, any whitespace than can be
 366     uniformly removed from the second line onwards is removed."""
 367     try:
 368         doc = object.__doc__
 369     except AttributeError:
 370         return None
 371     if not isinstance(doc, types.StringTypes):
 372         return None
 373     return cleandoc(doc)
 374
 375 def cleandoc(doc):
 376     """Clean up indentation from docstrings.
 377
 378     Any whitespace that can be uniformly removed from the second line
 379     onwards is removed."""
 380     try:
 381         lines = string.split(string.expandtabs(doc), '\n')
 382     except UnicodeError:
 383         return None
 384     else:
 385         # Find minimum indentation of any non-blank lines after first line.
 386         margin = sys.maxint
 387         for line in lines[1:]:
 388             content = len(string.lstrip(line))
 389             if content:
 390                 indent = len(line) - content
 391                 margin = min(margin, indent)
 392         # Remove indentation.
 393         if lines:
 394             lines[0] = lines[0].lstrip()
 395         if margin < sys.maxint:
 396             for i in range(1, len(lines)): lines[i] = lines[i][margin:]
 397         # Remove any trailing or leading blank lines.
 398         while lines and not lines[-1]:
 399             lines.pop()
 400         while lines and not lines[0]:
 401             lines.pop(0)
 402         return string.join(lines, '\n')
 403
 404 def getfile(object):
 405     """Work out which source or compiled file an object was defined in."""
 406     if ismodule(object):
 407         if hasattr(object, '__file__'):
 408             return object.__file__
 409         raise TypeError('arg is a built-in module')
 410     if isclass(object):
 411         object = sys.modules.get(object.__module__)
 412         if hasattr(object, '__file__'):
 413             return object.__file__
 414         raise TypeError('arg is a built-in class')
 415     if ismethod(object):
 416         object = object.im_func
 417     if isfunction(object):
 418         object = object.func_code
 419     if istraceback(object):
 420         object = object.tb_frame
 421     if isframe(object):
 422         object = object.f_code
 423     if iscode(object):
 424         return object.co_filename
 425     raise TypeError('arg is not a module, class, method, '
 426                     'function, traceback, frame, or code object')
 427
 428 ModuleInfo = namedtuple('ModuleInfo', 'name suffix mode module_type')
 429
 430 def getmoduleinfo(path):
 431     """Get the module name, suffix, mode, and module type for a given file."""
 432     filename = os.path.basename(path)
 433     suffixes = map(lambda info:
 434                    (-len(info[0]), info[0], info[1], info[2]),
 435                     imp.get_suffixes())
 436     suffixes.sort() # try longest suffixes first, in case they overlap
 437     for neglen, suffix, mode, mtype in suffixes:
 438         if filename[neglen:] == suffix:
 439             return ModuleInfo(filename[:neglen], suffix, mode, mtype)
 440
 441 def getmodulename(path):
 442     """Return the module name for a given file, or None."""
 443     info = getmoduleinfo(path)
 444     if info: return info[0]
 445
 446 def getsourcefile(object):
 447     """Return the Python source file an object was defined in, if it exists."""
 448     filename = getfile(object)
 449     if string.lower(filename[-4:]) in ('.pyc', '.pyo'):
 450         filename = filename[:-4] + '.py'
 451     for suffix, mode, kind in imp.get_suffixes():
 452         if 'b' in mode and string.lower(filename[-len(suffix):]) == suffix:
 453             # Looks like a binary file.  We want to only return a text file.
 454             return None
 455     if os.path.exists(filename):
 456         return filename
 457     # only return a non-existent filename if the module has a PEP 302 loader
 458     if hasattr(getmodule(object, filename), '__loader__'):
 459         return filename
 460
 461 def getabsfile(object, _filename=None):
 462     """Return an absolute path to the source or compiled file for an object.
 463
 464     The idea is for each object to have a unique origin, so this routine
 465     normalizes the result as much as possible."""
 466     if _filename is None:
 467         _filename = getsourcefile(object) or getfile(object)
 468     return os.path.normcase(os.path.abspath(_filename))
 469
 470 modulesbyfile = {}
 471 _filesbymodname = {}
 472
 473 def getmodule(object, _filename=None):
 474     """Return the module an object was defined in, or None if not found."""
 475     if ismodule(object):
 476         return object
 477     if hasattr(object, '__module__'):
 478         return sys.modules.get(object.__module__)
 479     # Try the filename to modulename cache
 480     if _filename is not None and _filename in modulesbyfile:
 481         return sys.modules.get(modulesbyfile[_filename])
 482     # Try the cache again with the absolute file name
 483     try:
 484         file = getabsfile(object, _filename)
 485     except TypeError:
 486         return None
 487     if file in modulesbyfile:
 488         return sys.modules.get(modulesbyfile[file])
 489     # Update the filename to module name cache and check yet again
 490     # Copy sys.modules in order to cope with changes while iterating
 491     for modname, module in sys.modules.items():
 492         if ismodule(module) and hasattr(module, '__file__'):
 493             f = module.__file__
 494             if f == _filesbymodname.get(modname, None):
 495                 # Have already mapped this module, so skip it
 496                 continue
 497             _filesbymodname[modname] = f
 498             f = getabsfile(module)
 499             # Always map to the name the module knows itself by
 500             modulesbyfile[f] = modulesbyfile[
 501                 os.path.realpath(f)] = module.__name__
 502     if file in modulesbyfile:
 503         return sys.modules.get(modulesbyfile[file])
 504     # Check the main module
 505     main = sys.modules['__main__']
 506     if not hasattr(object, '__name__'):
 507         return None
 508     if hasattr(main, object.__name__):
 509         mainobject = getattr(main, object.__name__)
 510         if mainobject is object:
 511             return main
 512     # Check builtins
 513     builtin = sys.modules['__builtin__']
 514     if hasattr(builtin, object.__name__):
 515         builtinobject = getattr(builtin, object.__name__)
 516         if builtinobject is object:
 517             return builtin
 518
 519 def findsource(object):
 520     """Return the entire source file and starting line number for an object.
 521
 522     The argument may be a module, class, method, function, traceback, frame,
 523     or code object.  The source code is returned as a list of all the lines
 524     in the file and the line number indexes a line in that list.  An IOError
 525     is raised if the source code cannot be retrieved."""
 526     file = getsourcefile(object) or getfile(object)
 527     module = getmodule(object, file)
 528     if module:
 529         lines = linecache.getlines(file, module.__dict__)
 530     else:
 531         lines = linecache.getlines(file)
 532     if not lines:
 533         raise IOError('could not get source code')
 534
 535     if ismodule(object):
 536         return lines, 0
 537
 538     if isclass(object):
 539         name = object.__name__
 540         pat = re.compile(r'^(\s*)class\s*' + name + r'\b')
 541         # make some effort to find the best matching class definition:
 542         # use the one with the least indentation, which is the one
 543         # that's most probably not inside a function definition.
 544         candidates = []
 545         for i in range(len(lines)):
 546             match = pat.match(lines[i])
 547             if match:
 548                 # if it's at toplevel, it's already the best one
 549                 if lines[i][0] == 'c':
 550                     return lines, i
 551                 # else add whitespace to candidate list
 552                 candidates.append((match.group(1), i))
 553         if candidates:
 554             # this will sort by whitespace, and by line number,
 555             # less whitespace first
 556             candidates.sort()
 557             return lines, candidates[0][1]
 558         else:
 559             raise IOError('could not find class definition')
 560
 561     if ismethod(object):
 562         object = object.im_func
 563     if isfunction(object):
 564         object = object.func_code
 565     if istraceback(object):
 566         object = object.tb_frame
 567     if isframe(object):
 568         object = object.f_code
 569     if iscode(object):
 570         if not hasattr(object, 'co_firstlineno'):
 571             raise IOError('could not find function definition')
 572         lnum = object.co_firstlineno - 1
 573         pat = re.compile(r'^(\s*def\s)|(.*(?<!\w)lambda(:|\s))|^(\s*@)')
 574         while lnum > 0:
 575             if pat.match(lines[lnum]): break
 576             lnum = lnum - 1
 577         return lines, lnum
 578     raise IOError('could not find code object')
 579
 580 def getcomments(object):
 581     """Get lines of comments immediately preceding an object's source code.
 582
 583     Returns None when source can't be found.
 584     """
 585     try:
 586         lines, lnum = findsource(object)
 587     except (IOError, TypeError):
 588         return None
 589
 590     if ismodule(object):
 591         # Look for a comment block at the top of the file.
 592         start = 0
 593         if lines and lines[0][:2] == '#!': start = 1
 594         while start < len(lines) and string.strip(lines[start]) in ('', '#'):
 595             start = start + 1
 596         if start < len(lines) and lines[start][:1] == '#':
 597             comments = []
 598             end = start
 599             while end < len(lines) and lines[end][:1] == '#':
 600                 comments.append(string.expandtabs(lines[end]))
 601                 end = end + 1
 602             return string.join(comments, '')
 603
 604     # Look for a preceding block of comments at the same indentation.
 605     elif lnum > 0:
 606         indent = indentsize(lines[lnum])
 607         end = lnum - 1
 608         if end >= 0 and string.lstrip(lines[end])[:1] == '#' and \
 609             indentsize(lines[end]) == indent:
 610             comments = [string.lstrip(string.expandtabs(lines[end]))]
 611             if end > 0:
 612                 end = end - 1
 613                 comment = string.lstrip(string.expandtabs(lines[end]))
 614                 while comment[:1] == '#' and indentsize(lines[end]) == indent:
 615                     comments[:0] = [comment]
 616                     end = end - 1
 617                     if end < 0: break
 618                     comment = string.lstrip(string.expandtabs(lines[end]))
 619             while comments and string.strip(comments[0]) == '#':
 620                 comments[:1] = []
 621             while comments and string.strip(comments[-1]) == '#':
 622                 comments[-1:] = []
 623             return string.join(comments, '')
 624
 625 class EndOfBlock(Exception): pass
 626
 627 class BlockFinder:
 628     """Provide a tokeneater() method to detect the end of a code block."""
 629     def __init__(self):
 630         self.indent = 0
 631         self.islambda = False
 632         self.started = False
 633         self.passline = False
 634         self.last = 1
 635
 636     def tokeneater(self, type, token, srow_scol, erow_ecol, line):
 637         srow, scol = srow_scol
 638         erow, ecol = erow_ecol
 639         if not self.started:
 640             # look for the first "def", "class" or "lambda"
 641             if token in ("def", "class", "lambda"):
 642                 if token == "lambda":
 643                     self.islambda = True
 644                 self.started = True
 645             self.passline = True    # skip to the end of the line
 646         elif type == tokenize.NEWLINE:
 647             self.passline = False   # stop skipping when a NEWLINE is seen
 648             self.last = srow
 649             if self.islambda:       # lambdas always end at the first NEWLINE
 650                 raise EndOfBlock
 651         elif self.passline:
 652             pass
 653         elif type == tokenize.INDENT:
 654             self.indent = self.indent + 1
 655             self.passline = True
 656         elif type == tokenize.DEDENT:
 657             self.indent = self.indent - 1
 658             # the end of matching indent/dedent pairs end a block
 659             # (note that this only works for "def"/"class" blocks,
 660             #  not e.g. for "if: else:" or "try: finally:" blocks)
 661             if self.indent <= 0:
 662                 raise EndOfBlock
 663         elif self.indent == 0 and type not in (tokenize.COMMENT, tokenize.NL):
 664             # any other token on the same indentation level end the previous
 665             # block as well, except the pseudo-tokens COMMENT and NL.
 666             raise EndOfBlock
 667
 668 def getblock(lines):
 669     """Extract the block of code at the top of the given list of lines."""
 670     blockfinder = BlockFinder()
 671     try:
 672         tokenize.tokenize(iter(lines).next, blockfinder.tokeneater)
 673     except (EndOfBlock, IndentationError):
 674         pass
 675     return lines[:blockfinder.last]
 676
 677 def getsourcelines(object):
 678     """Return a list of source lines and starting line number for an object.
 679
 680     The argument may be a module, class, method, function, traceback, frame,
 681     or code object.  The source code is returned as a list of the lines
 682     corresponding to the object and the line number indicates where in the
 683     original source file the first line of code was found.  An IOError is
 684     raised if the source code cannot be retrieved."""
 685     lines, lnum = findsource(object)
 686
 687     if ismodule(object): return lines, 0
 688     else: return getblock(lines[lnum:]), lnum + 1
 689
 690 def getsource(object):
 691     """Return the text of the source code for an object.
 692
 693     The argument may be a module, class, method, function, traceback, frame,
 694     or code object.  The source code is returned as a single string.  An
 695     IOError is raised if the source code cannot be retrieved."""
 696     lines, lnum = getsourcelines(object)
 697     return string.join(lines, '')
 698
 699 # --------------------------------------------------- class tree extraction
 700 def walktree(classes, children, parent):
 701     """Recursive helper function for getclasstree()."""
 702     results = []
 703     classes.sort(key=attrgetter('__module__', '__name__'))
 704     for c in classes:
 705         results.append((c, c.__bases__))
 706         if c in children:
 707             results.append(walktree(children[c], children, c))
 708     return results
 709
 710 def getclasstree(classes, unique=0):
 711     """Arrange the given list of classes into a hierarchy of nested lists.
 712
 713     Where a nested list appears, it contains classes derived from the class
 714     whose entry immediately precedes the list.  Each entry is a 2-tuple
 715     containing a class and a tuple of its base classes.  If the 'unique'
 716     argument is true, exactly one entry appears in the returned structure
 717     for each class in the given list.  Otherwise, classes using multiple
 718     inheritance and their descendants will appear multiple times."""
 719     children = {}
 720     roots = []
 721     for c in classes:
 722         if c.__bases__:
 723             for parent in c.__bases__:
 724                 if not parent in children:
 725                     children[parent] = []
 726                 children[parent].append(c)
 727                 if unique and parent in classes: break
 728         elif c not in roots:
 729             roots.append(c)
 730     for parent in children:
 731         if parent not in classes:
 732             roots.append(parent)
 733     return walktree(roots, children, None)
 734
 735 # ------------------------------------------------ argument list extraction
 736 Arguments = namedtuple('Arguments', 'args varargs keywords')
 737
 738 def getargs(co):
 739     """Get information about the arguments accepted by a code object.
 740
 741     Three things are returned: (args, varargs, varkw), where 'args' is
 742     a list of argument names (possibly containing nested lists), and
 743     'varargs' and 'varkw' are the names of the * and ** arguments or None."""
 744
 745     if not iscode(co):
 746         raise TypeError('arg is not a code object')
 747
 748     nargs = co.co_argcount
 749     names = co.co_varnames
 750     args = list(names[:nargs])
 751     step = 0
 752
 753     # The following acrobatics are for anonymous (tuple) arguments.
 754     for i in range(nargs):
 755         if args[i][:1] in ('', '.'):
 756             stack, remain, count = [], [], []
 757             while step < len(co.co_code):
 758                 op = ord(co.co_code[step])
 759                 step = step + 1
 760                 if op >= dis.HAVE_ARGUMENT:
 761                     opname = dis.opname[op]
 762                     value = ord(co.co_code[step]) + ord(co.co_code[step+1])*256
 763                     step = step + 2
 764                     if opname in ('UNPACK_TUPLE', 'UNPACK_SEQUENCE'):
 765                         remain.append(value)
 766                         count.append(value)
 767                     elif opname == 'STORE_FAST':
 768                         stack.append(names[value])
 769
 770                         # Special case for sublists of length 1: def foo((bar))
 771                         # doesn't generate the UNPACK_TUPLE bytecode, so if
 772                         # `remain` is empty here, we have such a sublist.
 773                         if not remain:
 774                             stack[0] = [stack[0]]
 775                             break
 776                         else:
 777                             remain[-1] = remain[-1] - 1
 778                             while remain[-1] == 0:
 779                                 remain.pop()
 780                                 size = count.pop()
 781                                 stack[-size:] = [stack[-size:]]
 782                                 if not remain: break
 783                                 remain[-1] = remain[-1] - 1
 784                             if not remain: break
 785             args[i] = stack[0]
 786
 787     varargs = None
 788     if co.co_flags & CO_VARARGS:
 789         varargs = co.co_varnames[nargs]
 790         nargs = nargs + 1
 791     varkw = None
 792     if co.co_flags & CO_VARKEYWORDS:
 793         varkw = co.co_varnames[nargs]
 794     return Arguments(args, varargs, varkw)
 795
 796 ArgSpec = namedtuple('ArgSpec', 'args varargs keywords defaults')
 797
 798 def getargspec(func):
 799     """Get the names and default values of a function's arguments.
 800
 801     A tuple of four things is returned: (args, varargs, varkw, defaults).
 802     'args' is a list of the argument names (it may contain nested lists).
 803     'varargs' and 'varkw' are the names of the * and ** arguments or None.
 804     'defaults' is an n-tuple of the default values of the last n arguments.
 805     """
 806
 807     if ismethod(func):
 808         func = func.im_func
 809     if not isfunction(func):
 810         raise TypeError('arg is not a Python function')
 811     args, varargs, varkw = getargs(func.func_code)
 812     return ArgSpec(args, varargs, varkw, func.func_defaults)
 813
 814 ArgInfo = namedtuple('ArgInfo', 'args varargs keywords locals')
 815
 816 def getargvalues(frame):
 817     """Get information about arguments passed into a particular frame.
 818
 819     A tuple of four things is returned: (args, varargs, varkw, locals).
 820     'args' is a list of the argument names (it may contain nested lists).
 821     'varargs' and 'varkw' are the names of the * and ** arguments or None.
 822     'locals' is the locals dictionary of the given frame."""
 823     args, varargs, varkw = getargs(frame.f_code)
 824     return ArgInfo(args, varargs, varkw, frame.f_locals)
 825
 826 def joinseq(seq):
 827     if len(seq) == 1:
 828         return '(' + seq[0] + ',)'
 829     else:
 830         return '(' + string.join(seq, ', ') + ')'
 831
 832 def strseq(object, convert, join=joinseq):
 833     """Recursively walk a sequence, stringifying each element."""
 834     if type(object) in (list, tuple):
 835         return join(map(lambda o, c=convert, j=join: strseq(o, c, j), object))
 836     else:
 837         return convert(object)
 838
 839 def formatargspec(args, varargs=None, varkw=None, defaults=None,
 840                   formatarg=str,
 841                   formatvarargs=lambda name: '*' + name,
 842                   formatvarkw=lambda name: '**' + name,
 843                   formatvalue=lambda value: '=' + repr(value),
 844                   join=joinseq):
 845     """Format an argument spec from the 4 values returned by getargspec.
 846
 847     The first four arguments are (args, varargs, varkw, defaults).  The
 848     other four arguments are the corresponding optional formatting functions
 849     that are called to turn names and values into strings.  The ninth
 850     argument is an optional function to format the sequence of arguments."""
 851     specs = []
 852     if defaults:
 853         firstdefault = len(args) - len(defaults)
 854     for i, arg in enumerate(args):
 855         spec = strseq(arg, formatarg, join)
 856         if defaults and i >= firstdefault:
 857             spec = spec + formatvalue(defaults[i - firstdefault])
 858         specs.append(spec)
 859     if varargs is not None:
 860         specs.append(formatvarargs(varargs))
 861     if varkw is not None:
 862         specs.append(formatvarkw(varkw))
 863     return '(' + string.join(specs, ', ') + ')'
 864
 865 def formatargvalues(args, varargs, varkw, locals,
 866                     formatarg=str,
 867                     formatvarargs=lambda name: '*' + name,
 868                     formatvarkw=lambda name: '**' + name,
 869                     formatvalue=lambda value: '=' + repr(value),
 870                     join=joinseq):
 871     """Format an argument spec from the 4 values returned by getargvalues.
 872
 873     The first four arguments are (args, varargs, varkw, locals).  The
 874     next four arguments are the corresponding optional formatting functions
 875     that are called to turn names and values into strings.  The ninth
 876     argument is an optional function to format the sequence of arguments."""
 877     def convert(name, locals=locals,
 878                 formatarg=formatarg, formatvalue=formatvalue):
 879         return formatarg(name) + formatvalue(locals[name])
 880     specs = []
 881     for i in range(len(args)):
 882         specs.append(strseq(args[i], convert, join))
 883     if varargs:
 884         specs.append(formatvarargs(varargs) + formatvalue(locals[varargs]))
 885     if varkw:
 886         specs.append(formatvarkw(varkw) + formatvalue(locals[varkw]))
 887     return '(' + string.join(specs, ', ') + ')'
 888
 889 # -------------------------------------------------- stack frame extraction
 890
 891 Traceback = namedtuple('Traceback', 'filename lineno function code_context index')
 892
 893 def getframeinfo(frame, context=1):
 894     """Get information about a frame or traceback object.
 895
 896     A tuple of five things is returned: the filename, the line number of
 897     the current line, the function name, a list of lines of context from
 898     the source code, and the index of the current line within that list.
 899     The optional second argument specifies the number of lines of context
 900     to return, which are centered around the current line."""
 901     if istraceback(frame):
 902         lineno = frame.tb_lineno
 903         frame = frame.tb_frame
 904     else:
 905         lineno = frame.f_lineno
 906     if not isframe(frame):
 907         raise TypeError('arg is not a frame or traceback object')
 908
 909     filename = getsourcefile(frame) or getfile(frame)
 910     if context > 0:
 911         start = lineno - 1 - context//2
 912         try:
 913             lines, lnum = findsource(frame)
 914         except IOError:
 915             lines = index = None
 916         else:
 917             start = max(start, 1)
 918             start = max(0, min(start, len(lines) - context))
 919             lines = lines[start:start+context]
 920             index = lineno - 1 - start
 921     else:
 922         lines = index = None
 923
 924     return Traceback(filename, lineno, frame.f_code.co_name, lines, index)
 925
 926 def getlineno(frame):
 927     """Get the line number from a frame object, allowing for optimization."""
 928     # FrameType.f_lineno is now a descriptor that grovels co_lnotab
 929     return frame.f_lineno
 930
 931 def getouterframes(frame, context=1):
 932     """Get a list of records for a frame and all higher (calling) frames.
 933
 934     Each record contains a frame object, filename, line number, function
 935     name, a list of lines of context, and index within the context."""
 936     framelist = []
 937     while frame:
 938         framelist.append((frame,) + getframeinfo(frame, context))
 939         frame = frame.f_back
 940     return framelist
 941
 942 def getinnerframes(tb, context=1):
 943     """Get a list of records for a traceback's frame and all lower frames.
 944
 945     Each record contains a frame object, filename, line number, function
 946     name, a list of lines of context, and index within the context."""
 947     framelist = []
 948     while tb:
 949         framelist.append((tb.tb_frame,) + getframeinfo(tb, context))
 950         tb = tb.tb_next
 951     return framelist
 952
 953 currentframe = sys._getframe
 954
 955 def stack(context=1):
 956     """Return a list of records for the stack above the caller's frame."""
 957     return getouterframes(sys._getframe(1), context)
 958
 959 def trace(context=1):
 960     """Return a list of records for the stack below the current exception."""
 961     return getinnerframes(sys.exc_info()[2], context)