PageRenderTime 5ms CodeModel.GetById 116ms app.highlight 44ms RepoModel.GetById 1ms app.codeStats 0ms

/Lib/inspect.py

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