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