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