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