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 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 Python source file an object was defined in, if it exists."""
 444     filename = getfile(object)
 445     if string.lower(filename[-4:]) in ('.pyc', '.pyo'):
 446         filename = filename[:-4] + '.py'
 447     for suffix, mode, kind in imp.get_suffixes():
 448         if 'b' in mode and string.lower(filename[-len(suffix):]) == suffix:
 449             # Looks like a binary file.  We want to only return a text file.
 450             return None
 451     if os.path.exists(filename):
 452         return filename
 453     # only return a non-existent filename if the module has a PEP 302 loader
 454     if hasattr(getmodule(object, filename), '__loader__'):
 455         return filename
 456
 457 def getabsfile(object, _filename=None):
 458     """Return an absolute path to the source or compiled file for an object.
 459
 460     The idea is for each object to have a unique origin, so this routine
 461     normalizes the result as much as possible."""
 462     if _filename is None:
 463         _filename = getsourcefile(object) or getfile(object)
 464     return os.path.normcase(os.path.abspath(_filename))
 465
 466 modulesbyfile = {}
 467 _filesbymodname = {}
 468
 469 def getmodule(object, _filename=None):
 470     """Return the module an object was defined in, or None if not found."""
 471     if ismodule(object):
 472         return object
 473     if hasattr(object, '__module__'):
 474         return sys.modules.get(object.__module__)
 475     # Try the filename to modulename cache
 476     if _filename is not None and _filename in modulesbyfile:
 477         return sys.modules.get(modulesbyfile[_filename])
 478     # Try the cache again with the absolute file name
 479     try:
 480         file = getabsfile(object, _filename)
 481     except TypeError:
 482         return None
 483     if file in modulesbyfile:
 484         return sys.modules.get(modulesbyfile[file])
 485     # Update the filename to module name cache and check yet again
 486     # Copy sys.modules in order to cope with changes while iterating
 487     for modname, module in sys.modules.items():
 488         if ismodule(module) and hasattr(module, '__file__'):
 489             f = module.__file__
 490             if f == _filesbymodname.get(modname, None):
 491                 # Have already mapped this module, so skip it
 492                 continue
 493             _filesbymodname[modname] = f
 494             f = getabsfile(module)
 495             # Always map to the name the module knows itself by
 496             modulesbyfile[f] = modulesbyfile[
 497                 os.path.realpath(f)] = module.__name__
 498     if file in modulesbyfile:
 499         return sys.modules.get(modulesbyfile[file])
 500     # Check the main module
 501     main = sys.modules['__main__']
 502     if not hasattr(object, '__name__'):
 503         return None
 504     if hasattr(main, object.__name__):
 505         mainobject = getattr(main, object.__name__)
 506         if mainobject is object:
 507             return main
 508     # Check builtins
 509     builtin = sys.modules['__builtin__']
 510     if hasattr(builtin, object.__name__):
 511         builtinobject = getattr(builtin, object.__name__)
 512         if builtinobject is object:
 513             return builtin
 514
 515 def findsource(object):
 516     """Return the entire source file and starting line number for an object.
 517
 518     The argument may be a module, class, method, function, traceback, frame,
 519     or code object.  The source code is returned as a list of all the lines
 520     in the file and the line number indexes a line in that list.  An IOError
 521     is raised if the source code cannot be retrieved."""
 522     file = getsourcefile(object)
 523     if not file:
 524         raise IOError('source code not available')
 525     module = getmodule(object, file)
 526     if module:
 527         lines = linecache.getlines(file, module.__dict__)
 528     else:
 529         lines = linecache.getlines(file)
 530     if not lines:
 531         raise IOError('could not get source code')
 532
 533     if ismodule(object):
 534         return lines, 0
 535
 536     if isclass(object):
 537         name = object.__name__
 538         pat = re.compile(r'^(\s*)class\s*' + name + r'\b')
 539         # make some effort to find the best matching class definition:
 540         # use the one with the least indentation, which is the one
 541         # that's most probably not inside a function definition.
 542         candidates = []
 543         for i in range(len(lines)):
 544             match = pat.match(lines[i])
 545             if match:
 546                 # if it's at toplevel, it's already the best one
 547                 if lines[i][0] == 'c':
 548                     return lines, i
 549                 # else add whitespace to candidate list
 550                 candidates.append((match.group(1), i))
 551         if candidates:
 552             # this will sort by whitespace, and by line number,
 553             # less whitespace first
 554             candidates.sort()
 555             return lines, candidates[0][1]
 556         else:
 557             raise IOError('could not find class definition')
 558
 559     if ismethod(object):
 560         object = object.im_func
 561     if isfunction(object):
 562         object = object.func_code
 563     if istraceback(object):
 564         object = object.tb_frame
 565     if isframe(object):
 566         object = object.f_code
 567     if iscode(object):
 568         if not hasattr(object, 'co_firstlineno'):
 569             raise IOError('could not find function definition')
 570         lnum = object.co_firstlineno - 1
 571         pat = re.compile(r'^(\s*def\s)|(.*(?<!\w)lambda(:|\s))|^(\s*@)')
 572         while lnum > 0:
 573             if pat.match(lines[lnum]): break
 574             lnum = lnum - 1
 575         return lines, lnum
 576     raise IOError('could not find code object')
 577
 578 def getcomments(object):
 579     """Get lines of comments immediately preceding an object's source code.
 580
 581     Returns None when source can't be found.
 582     """
 583     try:
 584         lines, lnum = findsource(object)
 585     except (IOError, TypeError):
 586         return None
 587
 588     if ismodule(object):
 589         # Look for a comment block at the top of the file.
 590         start = 0
 591         if lines and lines[0][:2] == '#!': start = 1
 592         while start < len(lines) and string.strip(lines[start]) in ('', '#'):
 593             start = start + 1
 594         if start < len(lines) and lines[start][:1] == '#':
 595             comments = []
 596             end = start
 597             while end < len(lines) and lines[end][:1] == '#':
 598                 comments.append(string.expandtabs(lines[end]))
 599                 end = end + 1
 600             return string.join(comments, '')
 601
 602     # Look for a preceding block of comments at the same indentation.
 603     elif lnum > 0:
 604         indent = indentsize(lines[lnum])
 605         end = lnum - 1
 606         if end >= 0 and string.lstrip(lines[end])[:1] == '#' and \
 607             indentsize(lines[end]) == indent:
 608             comments = [string.lstrip(string.expandtabs(lines[end]))]
 609             if end > 0:
 610                 end = end - 1
 611                 comment = string.lstrip(string.expandtabs(lines[end]))
 612                 while comment[:1] == '#' and indentsize(lines[end]) == indent:
 613                     comments[:0] = [comment]
 614                     end = end - 1
 615                     if end < 0: break
 616                     comment = string.lstrip(string.expandtabs(lines[end]))
 617             while comments and string.strip(comments[0]) == '#':
 618                 comments[:1] = []
 619             while comments and string.strip(comments[-1]) == '#':
 620                 comments[-1:] = []
 621             return string.join(comments, '')
 622
 623 class EndOfBlock(Exception): pass
 624
 625 class BlockFinder:
 626     """Provide a tokeneater() method to detect the end of a code block."""
 627     def __init__(self):
 628         self.indent = 0
 629         self.islambda = False
 630         self.started = False
 631         self.passline = False
 632         self.last = 1
 633
 634     def tokeneater(self, type, token, srow_scol, erow_ecol, line):
 635         srow, scol = srow_scol
 636         erow, ecol = erow_ecol
 637         if not self.started:
 638             # look for the first "def", "class" or "lambda"
 639             if token in ("def", "class", "lambda"):
 640                 if token == "lambda":
 641                     self.islambda = True
 642                 self.started = True
 643             self.passline = True    # skip to the end of the line
 644         elif type == tokenize.NEWLINE:
 645             self.passline = False   # stop skipping when a NEWLINE is seen
 646             self.last = srow
 647             if self.islambda:       # lambdas always end at the first NEWLINE
 648                 raise EndOfBlock
 649         elif self.passline:
 650             pass
 651         elif type == tokenize.INDENT:
 652             self.indent = self.indent + 1
 653             self.passline = True
 654         elif type == tokenize.DEDENT:
 655             self.indent = self.indent - 1
 656             # the end of matching indent/dedent pairs end a block
 657             # (note that this only works for "def"/"class" blocks,
 658             #  not e.g. for "if: else:" or "try: finally:" blocks)
 659             if self.indent <= 0:
 660                 raise EndOfBlock
 661         elif self.indent == 0 and type not in (tokenize.COMMENT, tokenize.NL):
 662             # any other token on the same indentation level end the previous
 663             # block as well, except the pseudo-tokens COMMENT and NL.
 664             raise EndOfBlock
 665
 666 def getblock(lines):
 667     """Extract the block of code at the top of the given list of lines."""
 668     blockfinder = BlockFinder()
 669     try:
 670         tokenize.tokenize(iter(lines).next, blockfinder.tokeneater)
 671     except (EndOfBlock, IndentationError):
 672         pass
 673     return lines[:blockfinder.last]
 674
 675 def getsourcelines(object):
 676     """Return a list of source lines and starting line number for an object.
 677
 678     The argument may be a module, class, method, function, traceback, frame,
 679     or code object.  The source code is returned as a list of the lines
 680     corresponding to the object and the line number indicates where in the
 681     original source file the first line of code was found.  An IOError is
 682     raised if the source code cannot be retrieved."""
 683     lines, lnum = findsource(object)
 684
 685     if ismodule(object): return lines, 0
 686     else: return getblock(lines[lnum:]), lnum + 1
 687
 688 def getsource(object):
 689     """Return the text of the source code for an object.
 690
 691     The argument may be a module, class, method, function, traceback, frame,
 692     or code object.  The source code is returned as a single string.  An
 693     IOError is raised if the source code cannot be retrieved."""
 694     lines, lnum = getsourcelines(object)
 695     return string.join(lines, '')
 696
 697 # --------------------------------------------------- class tree extraction
 698 def walktree(classes, children, parent):
 699     """Recursive helper function for getclasstree()."""
 700     results = []
 701     classes.sort(key=attrgetter('__module__', '__name__'))
 702     for c in classes:
 703         results.append((c, c.__bases__))
 704         if c in children:
 705             results.append(walktree(children[c], children, c))
 706     return results
 707
 708 def getclasstree(classes, unique=0):
 709     """Arrange the given list of classes into a hierarchy of nested lists.
 710
 711     Where a nested list appears, it contains classes derived from the class
 712     whose entry immediately precedes the list.  Each entry is a 2-tuple
 713     containing a class and a tuple of its base classes.  If the 'unique'
 714     argument is true, exactly one entry appears in the returned structure
 715     for each class in the given list.  Otherwise, classes using multiple
 716     inheritance and their descendants will appear multiple times."""
 717     children = {}
 718     roots = []
 719     for c in classes:
 720         if c.__bases__:
 721             for parent in c.__bases__:
 722                 if not parent in children:
 723                     children[parent] = []
 724                 children[parent].append(c)
 725                 if unique and parent in classes: break
 726         elif c not in roots:
 727             roots.append(c)
 728     for parent in children:
 729         if parent not in classes:
 730             roots.append(parent)
 731     return walktree(roots, children, None)
 732
 733 # ------------------------------------------------ argument list extraction
 734 Arguments = namedtuple('Arguments', 'args varargs keywords')
 735
 736 def getargs(co):
 737     """Get information about the arguments accepted by a code object.
 738
 739     Three things are returned: (args, varargs, varkw), where 'args' is
 740     a list of argument names (possibly containing nested lists), and
 741     'varargs' and 'varkw' are the names of the * and ** arguments or None."""
 742
 743     if not iscode(co):
 744         raise TypeError('{!r} is not a code object'.format(co))
 745
 746     nargs = co.co_argcount
 747     names = co.co_varnames
 748     args = list(names[:nargs])
 749     step = 0
 750
 751     # The following acrobatics are for anonymous (tuple) arguments.
 752     for i in range(nargs):
 753         if args[i][:1] in ('', '.'):
 754             stack, remain, count = [], [], []
 755             while step < len(co.co_code):
 756                 op = ord(co.co_code[step])
 757                 step = step + 1
 758                 if op >= dis.HAVE_ARGUMENT:
 759                     opname = dis.opname[op]
 760                     value = ord(co.co_code[step]) + ord(co.co_code[step+1])*256
 761                     step = step + 2
 762                     if opname in ('UNPACK_TUPLE', 'UNPACK_SEQUENCE'):
 763                         remain.append(value)
 764                         count.append(value)
 765                     elif opname == 'STORE_FAST':
 766                         stack.append(names[value])
 767
 768                         # Special case for sublists of length 1: def foo((bar))
 769                         # doesn't generate the UNPACK_TUPLE bytecode, so if
 770                         # `remain` is empty here, we have such a sublist.
 771                         if not remain:
 772                             stack[0] = [stack[0]]
 773                             break
 774                         else:
 775                             remain[-1] = remain[-1] - 1
 776                             while remain[-1] == 0:
 777                                 remain.pop()
 778                                 size = count.pop()
 779                                 stack[-size:] = [stack[-size:]]
 780                                 if not remain: break
 781                                 remain[-1] = remain[-1] - 1
 782                             if not remain: break
 783             args[i] = stack[0]
 784
 785     varargs = None
 786     if co.co_flags & CO_VARARGS:
 787         varargs = co.co_varnames[nargs]
 788         nargs = nargs + 1
 789     varkw = None
 790     if co.co_flags & CO_VARKEYWORDS:
 791         varkw = co.co_varnames[nargs]
 792     return Arguments(args, varargs, varkw)
 793
 794 ArgSpec = namedtuple('ArgSpec', 'args varargs keywords defaults')
 795
 796 def getargspec(func):
 797     """Get the names and default values of a function's arguments.
 798
 799     A tuple of four things is returned: (args, varargs, varkw, defaults).
 800     'args' is a list of the argument names (it may contain nested lists).
 801     'varargs' and 'varkw' are the names of the * and ** arguments or None.
 802     'defaults' is an n-tuple of the default values of the last n arguments.
 803     """
 804
 805     if ismethod(func):
 806         func = func.im_func
 807     if not isfunction(func):
 808         raise TypeError('{!r} is not a Python function'.format(func))
 809     args, varargs, varkw = getargs(func.func_code)
 810     return ArgSpec(args, varargs, varkw, func.func_defaults)
 811
 812 ArgInfo = namedtuple('ArgInfo', 'args varargs keywords locals')
 813
 814 def getargvalues(frame):
 815     """Get information about arguments passed into a particular frame.
 816
 817     A tuple of four things is returned: (args, varargs, varkw, locals).
 818     'args' is a list of the argument names (it may contain nested lists).
 819     'varargs' and 'varkw' are the names of the * and ** arguments or None.
 820     'locals' is the locals dictionary of the given frame."""
 821     args, varargs, varkw = getargs(frame.f_code)
 822     return ArgInfo(args, varargs, varkw, frame.f_locals)
 823
 824 def joinseq(seq):
 825     if len(seq) == 1:
 826         return '(' + seq[0] + ',)'
 827     else:
 828         return '(' + string.join(seq, ', ') + ')'
 829
 830 def strseq(object, convert, join=joinseq):
 831     """Recursively walk a sequence, stringifying each element."""
 832     if type(object) in (list, tuple):
 833         return join(map(lambda o, c=convert, j=join: strseq(o, c, j), object))
 834     else:
 835         return convert(object)
 836
 837 def formatargspec(args, varargs=None, varkw=None, defaults=None,
 838                   formatarg=str,
 839                   formatvarargs=lambda name: '*' + name,
 840                   formatvarkw=lambda name: '**' + name,
 841                   formatvalue=lambda value: '=' + repr(value),
 842                   join=joinseq):
 843     """Format an argument spec from the 4 values returned by getargspec.
 844
 845     The first four arguments are (args, varargs, varkw, defaults).  The
 846     other four arguments are the corresponding optional formatting functions
 847     that are called to turn names and values into strings.  The ninth
 848     argument is an optional function to format the sequence of arguments."""
 849     specs = []
 850     if defaults:
 851         firstdefault = len(args) - len(defaults)
 852     for i, arg in enumerate(args):
 853         spec = strseq(arg, formatarg, join)
 854         if defaults and i >= firstdefault:
 855             spec = spec + formatvalue(defaults[i - firstdefault])
 856         specs.append(spec)
 857     if varargs is not None:
 858         specs.append(formatvarargs(varargs))
 859     if varkw is not None:
 860         specs.append(formatvarkw(varkw))
 861     return '(' + string.join(specs, ', ') + ')'
 862
 863 def formatargvalues(args, varargs, varkw, locals,
 864                     formatarg=str,
 865                     formatvarargs=lambda name: '*' + name,
 866                     formatvarkw=lambda name: '**' + name,
 867                     formatvalue=lambda value: '=' + repr(value),
 868                     join=joinseq):
 869     """Format an argument spec from the 4 values returned by getargvalues.
 870
 871     The first four arguments are (args, varargs, varkw, locals).  The
 872     next four arguments are the corresponding optional formatting functions
 873     that are called to turn names and values into strings.  The ninth
 874     argument is an optional function to format the sequence of arguments."""
 875     def convert(name, locals=locals,
 876                 formatarg=formatarg, formatvalue=formatvalue):
 877         return formatarg(name) + formatvalue(locals[name])
 878     specs = []
 879     for i in range(len(args)):
 880         specs.append(strseq(args[i], convert, join))
 881     if varargs:
 882         specs.append(formatvarargs(varargs) + formatvalue(locals[varargs]))
 883     if varkw:
 884         specs.append(formatvarkw(varkw) + formatvalue(locals[varkw]))
 885     return '(' + string.join(specs, ', ') + ')'
 886
 887 # -------------------------------------------------- stack frame extraction
 888
 889 Traceback = namedtuple('Traceback', 'filename lineno function code_context index')
 890
 891 def getframeinfo(frame, context=1):
 892     """Get information about a frame or traceback object.
 893
 894     A tuple of five things is returned: the filename, the line number of
 895     the current line, the function name, a list of lines of context from
 896     the source code, and the index of the current line within that list.
 897     The optional second argument specifies the number of lines of context
 898     to return, which are centered around the current line."""
 899     if istraceback(frame):
 900         lineno = frame.tb_lineno
 901         frame = frame.tb_frame
 902     else:
 903         lineno = frame.f_lineno
 904     if not isframe(frame):
 905         raise TypeError('{!r} is not a frame or traceback object'.format(frame))
 906
 907     filename = getsourcefile(frame) or getfile(frame)
 908     if context > 0:
 909         start = lineno - 1 - context//2
 910         try:
 911             lines, lnum = findsource(frame)
 912         except IOError:
 913             lines = index = None
 914         else:
 915             start = max(start, 1)
 916             start = max(0, min(start, len(lines) - context))
 917             lines = lines[start:start+context]
 918             index = lineno - 1 - start
 919     else:
 920         lines = index = None
 921
 922     return Traceback(filename, lineno, frame.f_code.co_name, lines, index)
 923
 924 def getlineno(frame):
 925     """Get the line number from a frame object, allowing for optimization."""
 926     # FrameType.f_lineno is now a descriptor that grovels co_lnotab
 927     return frame.f_lineno
 928
 929 def getouterframes(frame, context=1):
 930     """Get a list of records for a frame and all higher (calling) frames.
 931
 932     Each record contains a frame object, filename, line number, function
 933     name, a list of lines of context, and index within the context."""
 934     framelist = []
 935     while frame:
 936         framelist.append((frame,) + getframeinfo(frame, context))
 937         frame = frame.f_back
 938     return framelist
 939
 940 def getinnerframes(tb, context=1):
 941     """Get a list of records for a traceback's frame and all lower frames.
 942
 943     Each record contains a frame object, filename, line number, function
 944     name, a list of lines of context, and index within the context."""
 945     framelist = []
 946     while tb:
 947         framelist.append((tb.tb_frame,) + getframeinfo(tb, context))
 948         tb = tb.tb_next
 949     return framelist
 950
 951 if hasattr(sys, '_getframe'):
 952     currentframe = sys._getframe
 953 else:
 954     currentframe = lambda _=None: None
 955
 956 def stack(context=1):
 957     """Return a list of records for the stack above the caller's frame."""
 958     return getouterframes(sys._getframe(1), context)
 959
 960 def trace(context=1):
 961     """Return a list of records for the stack below the current exception."""
 962     return getinnerframes(sys.exc_info()[2], context)