inspect.py 45.7 KB
Newer Older
1 2 3
"""Get useful information from live Python objects.

This module encapsulates the interface provided by the internal special
4
attributes (co_*, im_*, tb_*, etc.) in a friendlier fashion.
5 6 7 8
It also provides some help for examining source code and class layout.

Here are some of the useful functions provided by this module:

Christian Heimes's avatar
Christian Heimes committed
9 10 11
    ismodule(), isclass(), ismethod(), isfunction(), isgeneratorfunction(),
        isgenerator(), istraceback(), isframe(), iscode(), isbuiltin(),
        isroutine() - check object types
12 13 14 15 16 17 18
    getmembers() - get members of an object that satisfy a given condition

    getfile(), getsourcefile(), getsource() - find an object's source code
    getdoc(), getcomments() - get documentation on an object
    getmodule() - determine the module that an object came from
    getclasstree() - arrange classes so as to represent their hierarchy

19
    getargspec(), getargvalues(), getcallargs() - get info about function arguments
20
    getfullargspec() - same, with support for Python-3000 features
21 22 23 24 25 26 27 28
    formatargspec(), formatargvalues() - format an argument spec
    getouterframes(), getinnerframes() - get info about frames
    currentframe() - get the current stack frame
    stack(), trace() - get info about frames on the stack or in a traceback
"""

# This module is in the public domain.  No warranties.

Ka-Ping Yee's avatar
Ka-Ping Yee committed
29 30
__author__ = 'Ka-Ping Yee <ping@lfw.org>'
__date__ = '1 Jan 2001'
31

Christian Heimes's avatar
Christian Heimes committed
32 33 34
import sys
import os
import types
35
import itertools
Christian Heimes's avatar
Christian Heimes committed
36 37 38 39
import re
import imp
import tokenize
import linecache
40
from operator import attrgetter
41
from collections import namedtuple
42 43 44 45 46 47 48 49 50 51 52 53 54 55

# Create constants for the compiler flags in Include/code.h
# We try to get them from dis to avoid duplication, but fall
# back to hardcording so the dependency is optional
try:
    from dis import COMPILER_FLAG_NAMES as _flag_names
except ImportError:
    CO_OPTIMIZED, CO_NEWLOCALS = 0x1, 0x2
    CO_VARARGS, CO_VARKEYWORDS = 0x4, 0x8
    CO_NESTED, CO_GENERATOR, CO_NOFREE = 0x10, 0x20, 0x40
else:
    mod_dict = globals()
    for k, v in _flag_names.items():
        mod_dict["CO_" + v] = k
56

57 58 59
# See Include/object.h
TPFLAGS_IS_ABSTRACT = 1 << 20

60 61 62 63 64
# ----------------------------------------------------------- type-checking
def ismodule(object):
    """Return true if the object is a module.

    Module objects provide these attributes:
Barry Warsaw's avatar
Barry Warsaw committed
65
        __cached__      pathname to byte compiled file
66 67
        __doc__         documentation string
        __file__        filename (missing for built-in modules)"""
68
    return isinstance(object, types.ModuleType)
69 70 71 72 73 74 75

def isclass(object):
    """Return true if the object is a class.

    Class objects provide these attributes:
        __doc__         documentation string
        __module__      name of module in which this class was defined"""
76
    return isinstance(object, type)
77 78 79 80 81 82 83

def ismethod(object):
    """Return true if the object is an instance method.

    Instance method objects provide these attributes:
        __doc__         documentation string
        __name__        name with which this method was defined
84 85
        __func__        function object containing implementation of method
        __self__        instance to which this method is bound"""
86
    return isinstance(object, types.MethodType)
87

88
def ismethoddescriptor(object):
89 90 91
    """Return true if the object is a method descriptor.

    But not if ismethod() or isclass() or isfunction() are true.
92 93 94 95 96 97

    This is new in Python 2.2, and, for example, is true of int.__add__.
    An object passing this test has a __get__ attribute but not a __set__
    attribute, but beyond that the set of attributes varies.  __name__ is
    usually sensible, and __doc__ often is.

98 99 100
    Methods implemented via descriptors that also pass one of the other
    tests return false from the ismethoddescriptor() test, simply because
    the other tests promise more -- you can, e.g., count on having the
101
    __func__ attribute (etc) when an object passes ismethod()."""
102 103 104
    return (hasattr(object, "__get__")
            and not hasattr(object, "__set__") # else it's a data descriptor
            and not ismethod(object)           # mutual exclusion
105
            and not isfunction(object)
106 107
            and not isclass(object))

108 109 110 111 112 113 114 115 116 117
def isdatadescriptor(object):
    """Return true if the object is a data descriptor.

    Data descriptors have both a __get__ and a __set__ attribute.  Examples are
    properties (defined in Python) and getsets and members (defined in C).
    Typically, data descriptors will also have __name__ and __doc__ attributes
    (properties, getsets, and members have both of these attributes), but this
    is not guaranteed."""
    return (hasattr(object, "__set__") and hasattr(object, "__get__"))

118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151
if hasattr(types, 'MemberDescriptorType'):
    # CPython and equivalent
    def ismemberdescriptor(object):
        """Return true if the object is a member descriptor.

        Member descriptors are specialized descriptors defined in extension
        modules."""
        return isinstance(object, types.MemberDescriptorType)
else:
    # Other implementations
    def ismemberdescriptor(object):
        """Return true if the object is a member descriptor.

        Member descriptors are specialized descriptors defined in extension
        modules."""
        return False

if hasattr(types, 'GetSetDescriptorType'):
    # CPython and equivalent
    def isgetsetdescriptor(object):
        """Return true if the object is a getset descriptor.

        getset descriptors are specialized descriptors defined in extension
        modules."""
        return isinstance(object, types.GetSetDescriptorType)
else:
    # Other implementations
    def isgetsetdescriptor(object):
        """Return true if the object is a getset descriptor.

        getset descriptors are specialized descriptors defined in extension
        modules."""
        return False

152 153 154 155 156 157
def isfunction(object):
    """Return true if the object is a user-defined function.

    Function objects provide these attributes:
        __doc__         documentation string
        __name__        name with which this function was defined
158 159 160 161 162
        __code__        code object containing compiled function bytecode
        __defaults__    tuple of any default values for arguments
        __globals__     global namespace in which this function was defined
        __annotations__ dict of parameter annotations
        __kwdefaults__  dict of keyword only parameters with defaults"""
163
    return isinstance(object, types.FunctionType)
164

Christian Heimes's avatar
Christian Heimes committed
165 166 167 168 169
def isgeneratorfunction(object):
    """Return true if the object is a user-defined generator function.

    Generator function objects provides same attributes as functions.

170
    See help(isfunction) for attributes listing."""
171 172
    return bool((isfunction(object) or ismethod(object)) and
                object.__code__.co_flags & CO_GENERATOR)
Christian Heimes's avatar
Christian Heimes committed
173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190

def isgenerator(object):
    """Return true if the object is a generator.

    Generator objects provide these attributes:
        __iter__        defined to support interation over container
        close           raises a new GeneratorExit exception inside the
                        generator to terminate the iteration
        gi_code         code object
        gi_frame        frame object or possibly None once the generator has
                        been exhausted
        gi_running      set to 1 when generator is executing, 0 otherwise
        next            return the next item from the container
        send            resumes the generator and "sends" a value that becomes
                        the result of the current yield-expression
        throw           used to raise an exception inside the generator"""
    return isinstance(object, types.GeneratorType)

191 192 193 194 195 196 197 198
def istraceback(object):
    """Return true if the object is a traceback.

    Traceback objects provide these attributes:
        tb_frame        frame object at this level
        tb_lasti        index of last attempted instruction in bytecode
        tb_lineno       current line number in Python source code
        tb_next         next inner traceback object (called by this level)"""
199
    return isinstance(object, types.TracebackType)
200 201 202 203 204 205 206 207 208 209 210 211 212

def isframe(object):
    """Return true if the object is a frame object.

    Frame objects provide these attributes:
        f_back          next outer frame object (this frame's caller)
        f_builtins      built-in namespace seen by this frame
        f_code          code object being executed in this frame
        f_globals       global namespace seen by this frame
        f_lasti         index of last attempted instruction in bytecode
        f_lineno        current line number in Python source code
        f_locals        local namespace seen by this frame
        f_trace         tracing function for this frame, or None"""
213
    return isinstance(object, types.FrameType)
214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230

def iscode(object):
    """Return true if the object is a code object.

    Code objects provide these attributes:
        co_argcount     number of arguments (not including * or ** args)
        co_code         string of raw compiled bytecode
        co_consts       tuple of constants used in the bytecode
        co_filename     name of file in which this code object was created
        co_firstlineno  number of first line in Python source code
        co_flags        bitmap: 1=optimized | 2=newlocals | 4=*arg | 8=**arg
        co_lnotab       encoded mapping of line numbers to bytecode indices
        co_name         name with which this code object was defined
        co_names        tuple of names of local variables
        co_nlocals      number of local variables
        co_stacksize    virtual machine stack space required
        co_varnames     tuple of names of arguments and local variables"""
231
    return isinstance(object, types.CodeType)
232 233 234 235 236 237 238 239

def isbuiltin(object):
    """Return true if the object is a built-in function or method.

    Built-in functions and methods provide these attributes:
        __doc__         documentation string
        __name__        original name of this function or method
        __self__        instance to which a method is bound, or None"""
240
    return isinstance(object, types.BuiltinFunctionType)
241 242 243

def isroutine(object):
    """Return true if the object is any kind of function or method."""
244 245 246 247
    return (isbuiltin(object)
            or isfunction(object)
            or ismethod(object)
            or ismethoddescriptor(object))
248

249 250
def isabstract(object):
    """Return true if the object is an abstract base class (ABC)."""
Benjamin Peterson's avatar
Benjamin Peterson committed
251
    return bool(isinstance(object, type) and object.__flags__ & TPFLAGS_IS_ABSTRACT)
252

253 254 255 256 257
def getmembers(object, predicate=None):
    """Return all members of an object as (name, value) pairs sorted by name.
    Optionally, only return members that satisfy a given predicate."""
    results = []
    for key in dir(object):
Benjamin Peterson's avatar
Benjamin Peterson committed
258 259 260 261
        try:
            value = getattr(object, key)
        except AttributeError:
            continue
262 263 264 265 266
        if not predicate or predicate(value):
            results.append((key, value))
    results.sort()
    return results

267 268
Attribute = namedtuple('Attribute', 'name kind defining_class object')

269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307
def classify_class_attrs(cls):
    """Return list of attribute-descriptor tuples.

    For each name in dir(cls), the return list contains a 4-tuple
    with these elements:

        0. The name (a string).

        1. The kind of attribute this is, one of these strings:
               'class method'    created via classmethod()
               'static method'   created via staticmethod()
               'property'        created via property()
               'method'          any other flavor of method
               'data'            not a method

        2. The class which defined this attribute (a class).

        3. The object as obtained directly from the defining class's
           __dict__, not via getattr.  This is especially important for
           data attributes:  C.data is just a data object, but
           C.__dict__['data'] may be a data descriptor with additional
           info, like a __doc__ string.
    """

    mro = getmro(cls)
    names = dir(cls)
    result = []
    for name in names:
        # Get the object associated with the name.
        # Getting an obj from the __dict__ sometimes reveals more than
        # using getattr.  Static and class methods are dramatic examples.
        if name in cls.__dict__:
            obj = cls.__dict__[name]
        else:
            obj = getattr(cls, name)

        # Figure out where it was defined.
        homecls = getattr(obj, "__objclass__", None)
        if homecls is None:
308
            # search the dicts.
309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328
            for base in mro:
                if name in base.__dict__:
                    homecls = base
                    break

        # Get the object again, in order to get it from the defining
        # __dict__ instead of via getattr (if possible).
        if homecls is not None and name in homecls.__dict__:
            obj = homecls.__dict__[name]

        # Also get the object via getattr.
        obj_via_getattr = getattr(cls, name)

        # Classify the object.
        if isinstance(obj, staticmethod):
            kind = "static method"
        elif isinstance(obj, classmethod):
            kind = "class method"
        elif isinstance(obj, property):
            kind = "property"
329
        elif (isfunction(obj_via_getattr) or
330 331 332 333 334
              ismethoddescriptor(obj_via_getattr)):
            kind = "method"
        else:
            kind = "data"

335
        result.append(Attribute(name, kind, homecls, obj))
336 337 338

    return result

339 340 341 342
# ----------------------------------------------------------- class helpers

def getmro(cls):
    "Return tuple of base classes (including cls) in method resolution order."
343
    return cls.__mro__
344

345 346 347
# -------------------------------------------------- source code extraction
def indentsize(line):
    """Return the indent size, in spaces, at the start of a line of text."""
348 349
    expline = line.expandtabs()
    return len(expline) - len(expline.lstrip())
350 351 352 353 354 355 356

def getdoc(object):
    """Get the documentation string for an object.

    All tabs are expanded to spaces.  To clean up docstrings that are
    indented to line up with blocks of code, any whitespace than can be
    uniformly removed from the second line onwards is removed."""
357 358 359 360
    try:
        doc = object.__doc__
    except AttributeError:
        return None
361
    if not isinstance(doc, str):
362
        return None
Georg Brandl's avatar
Georg Brandl committed
363 364 365 366 367 368 369
    return cleandoc(doc)

def cleandoc(doc):
    """Clean up indentation from docstrings.

    Any whitespace that can be uniformly removed from the second line
    onwards is removed."""
370
    try:
371
        lines = doc.expandtabs().split('\n')
372 373 374
    except UnicodeError:
        return None
    else:
Ka-Ping Yee's avatar
Ka-Ping Yee committed
375
        # Find minimum indentation of any non-blank lines after first line.
376
        margin = sys.maxsize
377
        for line in lines[1:]:
378
            content = len(line.lstrip())
Ka-Ping Yee's avatar
Ka-Ping Yee committed
379 380 381 382 383 384
            if content:
                indent = len(line) - content
                margin = min(margin, indent)
        # Remove indentation.
        if lines:
            lines[0] = lines[0].lstrip()
385
        if margin < sys.maxsize:
386
            for i in range(1, len(lines)): lines[i] = lines[i][margin:]
Ka-Ping Yee's avatar
Ka-Ping Yee committed
387 388 389 390 391
        # Remove any trailing or leading blank lines.
        while lines and not lines[-1]:
            lines.pop()
        while lines and not lines[0]:
            lines.pop(0)
392
        return '\n'.join(lines)
393 394

def getfile(object):
395
    """Work out which source or compiled file an object was defined in."""
396 397 398
    if ismodule(object):
        if hasattr(object, '__file__'):
            return object.__file__
Benjamin Peterson's avatar
Benjamin Peterson committed
399
        raise TypeError('{!r} is a built-in module'.format(object))
400
    if isclass(object):
401
        object = sys.modules.get(object.__module__)
402 403
        if hasattr(object, '__file__'):
            return object.__file__
Benjamin Peterson's avatar
Benjamin Peterson committed
404
        raise TypeError('{!r} is a built-in class'.format(object))
405
    if ismethod(object):
406
        object = object.__func__
407
    if isfunction(object):
408
        object = object.__code__
409 410 411 412 413 414
    if istraceback(object):
        object = object.tb_frame
    if isframe(object):
        object = object.f_code
    if iscode(object):
        return object.co_filename
Benjamin Peterson's avatar
Benjamin Peterson committed
415 416
    raise TypeError('{!r} is not a module, class, method, '
                    'function, traceback, frame, or code object'.format(object))
417

418 419
ModuleInfo = namedtuple('ModuleInfo', 'name suffix mode module_type')

420 421 422
def getmoduleinfo(path):
    """Get the module name, suffix, mode, and module type for a given file."""
    filename = os.path.basename(path)
423 424
    suffixes = [(-len(suffix), suffix, mode, mtype)
                    for suffix, mode, mtype in imp.get_suffixes()]
425 426 427
    suffixes.sort() # try longest suffixes first, in case they overlap
    for neglen, suffix, mode, mtype in suffixes:
        if filename[neglen:] == suffix:
428
            return ModuleInfo(filename[:neglen], suffix, mode, mtype)
429 430 431 432 433 434

def getmodulename(path):
    """Return the module name for a given file, or None."""
    info = getmoduleinfo(path)
    if info: return info[0]

435
def getsourcefile(object):
436 437 438
    """Return the filename that can be used to locate an object's source.
    Return None if no way can be identified to get the source.
    """
439
    filename = getfile(object)
440
    if filename[-4:].lower() in ('.pyc', '.pyo'):
441
        filename = filename[:-4] + '.py'
442
    for suffix, mode, kind in imp.get_suffixes():
443
        if 'b' in mode and filename[-len(suffix):].lower() == suffix:
444 445
            # Looks like a binary file.  We want to only return a text file.
            return None
446 447
    if os.path.exists(filename):
        return filename
448 449
    # only return a non-existent filename if the module has a PEP 302 loader
    if hasattr(getmodule(object, filename), '__loader__'):
450
        return filename
451 452 453
    # or it is in the linecache
    if filename in linecache.cache:
        return filename
454

455
def getabsfile(object, _filename=None):
456
    """Return an absolute path to the source or compiled file for an object.
457

458 459
    The idea is for each object to have a unique origin, so this routine
    normalizes the result as much as possible."""
460 461 462
    if _filename is None:
        _filename = getsourcefile(object) or getfile(object)
    return os.path.normcase(os.path.abspath(_filename))
463

464
modulesbyfile = {}
465
_filesbymodname = {}
466

467
def getmodule(object, _filename=None):
468
    """Return the module an object was defined in, or None if not found."""
469 470
    if ismodule(object):
        return object
471
    if hasattr(object, '__module__'):
Ka-Ping Yee's avatar
Ka-Ping Yee committed
472
        return sys.modules.get(object.__module__)
473 474 475 476
    # Try the filename to modulename cache
    if _filename is not None and _filename in modulesbyfile:
        return sys.modules.get(modulesbyfile[_filename])
    # Try the cache again with the absolute file name
477
    try:
478
        file = getabsfile(object, _filename)
479 480
    except TypeError:
        return None
481
    if file in modulesbyfile:
482
        return sys.modules.get(modulesbyfile[file])
483 484 485
    # Update the filename to module name cache and check yet again
    # Copy sys.modules in order to cope with changes while iterating
    for modname, module in sys.modules.items():
486
        if ismodule(module) and hasattr(module, '__file__'):
487 488 489 490 491
            f = module.__file__
            if f == _filesbymodname.get(modname, None):
                # Have already mapped this module, so skip it
                continue
            _filesbymodname[modname] = f
492
            f = getabsfile(module)
493
            # Always map to the name the module knows itself by
494 495
            modulesbyfile[f] = modulesbyfile[
                os.path.realpath(f)] = module.__name__
496
    if file in modulesbyfile:
497
        return sys.modules.get(modulesbyfile[file])
498
    # Check the main module
499
    main = sys.modules['__main__']
500 501
    if not hasattr(object, '__name__'):
        return None
502
    if hasattr(main, object.__name__):
503
        mainobject = getattr(main, object.__name__)
504 505
        if mainobject is object:
            return main
506
    # Check builtins
507
    builtin = sys.modules['builtins']
508
    if hasattr(builtin, object.__name__):
509
        builtinobject = getattr(builtin, object.__name__)
510 511
        if builtinobject is object:
            return builtin
512 513 514 515 516 517 518 519

def findsource(object):
    """Return the entire source file and starting line number for an object.

    The argument may be a module, class, method, function, traceback, frame,
    or code object.  The source code is returned as a list of all the lines
    in the file and the line number indexes a line in that list.  An IOError
    is raised if the source code cannot be retrieved."""
520 521 522 523

    file = getfile(object)
    sourcefile = getsourcefile(object)
    if not sourcefile and file[0] + file[-1] != '<>':
524
        raise IOError('source code not available')
525 526
    file = sourcefile if sourcefile else file

527
    module = getmodule(object, file)
528 529 530 531
    if module:
        lines = linecache.getlines(file, module.__dict__)
    else:
        lines = linecache.getlines(file)
532
    if not lines:
533
        raise IOError('could not get source code')
534 535 536 537 538 539

    if ismodule(object):
        return lines, 0

    if isclass(object):
        name = object.__name__
540 541 542 543 544
        pat = re.compile(r'^(\s*)class\s*' + name + r'\b')
        # make some effort to find the best matching class definition:
        # use the one with the least indentation, which is the one
        # that's most probably not inside a function definition.
        candidates = []
545
        for i in range(len(lines)):
546 547 548 549 550 551 552 553 554 555 556 557
            match = pat.match(lines[i])
            if match:
                # if it's at toplevel, it's already the best one
                if lines[i][0] == 'c':
                    return lines, i
                # else add whitespace to candidate list
                candidates.append((match.group(1), i))
        if candidates:
            # this will sort by whitespace, and by line number,
            # less whitespace first
            candidates.sort()
            return lines, candidates[0][1]
558 559
        else:
            raise IOError('could not find class definition')
560 561

    if ismethod(object):
562
        object = object.__func__
563
    if isfunction(object):
564
        object = object.__code__
565 566 567 568 569
    if istraceback(object):
        object = object.tb_frame
    if isframe(object):
        object = object.f_code
    if iscode(object):
570
        if not hasattr(object, 'co_firstlineno'):
571
            raise IOError('could not find function definition')
572
        lnum = object.co_firstlineno - 1
573
        pat = re.compile(r'^(\s*def\s)|(.*(?<!\w)lambda(:|\s))|^(\s*@)')
574
        while lnum > 0:
575
            if pat.match(lines[lnum]): break
576 577
            lnum = lnum - 1
        return lines, lnum
578
    raise IOError('could not find code object')
579 580

def getcomments(object):
581 582 583 584 585 586 587 588
    """Get lines of comments immediately preceding an object's source code.

    Returns None when source can't be found.
    """
    try:
        lines, lnum = findsource(object)
    except (IOError, TypeError):
        return None
589 590 591 592

    if ismodule(object):
        # Look for a comment block at the top of the file.
        start = 0
593
        if lines and lines[0][:2] == '#!': start = 1
594
        while start < len(lines) and lines[start].strip() in ('', '#'):
595
            start = start + 1
596
        if start < len(lines) and lines[start][:1] == '#':
597 598 599
            comments = []
            end = start
            while end < len(lines) and lines[end][:1] == '#':
600
                comments.append(lines[end].expandtabs())
601
                end = end + 1
602
            return ''.join(comments)
603 604 605 606 607

    # Look for a preceding block of comments at the same indentation.
    elif lnum > 0:
        indent = indentsize(lines[lnum])
        end = lnum - 1
608
        if end >= 0 and lines[end].lstrip()[:1] == '#' and \
609
            indentsize(lines[end]) == indent:
610
            comments = [lines[end].expandtabs().lstrip()]
611 612
            if end > 0:
                end = end - 1
613
                comment = lines[end].expandtabs().lstrip()
614 615 616 617
                while comment[:1] == '#' and indentsize(lines[end]) == indent:
                    comments[:0] = [comment]
                    end = end - 1
                    if end < 0: break
618 619
                    comment = lines[end].expandtabs().lstrip()
            while comments and comments[0].strip() == '#':
620
                comments[:1] = []
621
            while comments and comments[-1].strip() == '#':
622
                comments[-1:] = []
623
            return ''.join(comments)
624

625 626 627 628 629 630
class EndOfBlock(Exception): pass

class BlockFinder:
    """Provide a tokeneater() method to detect the end of a code block."""
    def __init__(self):
        self.indent = 0
631
        self.islambda = False
632 633
        self.started = False
        self.passline = False
634
        self.last = 1
635

636
    def tokeneater(self, type, token, srowcol, erowcol, line):
637
        if not self.started:
638
            # look for the first "def", "class" or "lambda"
639
            if token in ("def", "class", "lambda"):
640 641
                if token == "lambda":
                    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 = srowcol[0]
647 648
            if self.islambda:       # lambdas always end at the first NEWLINE
                raise EndOfBlock
649 650
        elif self.passline:
            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 657 658 659 660 661 662 663 664
            # the end of matching indent/dedent pairs end a block
            # (note that this only works for "def"/"class" blocks,
            #  not e.g. for "if: else:" or "try: finally:" blocks)
            if self.indent <= 0:
                raise EndOfBlock
        elif self.indent == 0 and type not in (tokenize.COMMENT, tokenize.NL):
            # any other token on the same indentation level end the previous
            # block as well, except the pseudo-tokens COMMENT and NL.
            raise EndOfBlock
665 666 667

def getblock(lines):
    """Extract the block of code at the top of the given list of lines."""
668
    blockfinder = BlockFinder()
669
    try:
670 671 672
        tokens = tokenize.generate_tokens(iter(lines).__next__)
        for _token in tokens:
            blockfinder.tokeneater(*_token)
673 674 675
    except (EndOfBlock, IndentationError):
        pass
    return lines[:blockfinder.last]
676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696

def getsourcelines(object):
    """Return a list of source lines and starting line number for an object.

    The argument may be a module, class, method, function, traceback, frame,
    or code object.  The source code is returned as a list of the lines
    corresponding to the object and the line number indicates where in the
    original source file the first line of code was found.  An IOError is
    raised if the source code cannot be retrieved."""
    lines, lnum = findsource(object)

    if ismodule(object): return lines, 0
    else: return getblock(lines[lnum:]), lnum + 1

def getsource(object):
    """Return the text of the source code for an object.

    The argument may be a module, class, method, function, traceback, frame,
    or code object.  The source code is returned as a single string.  An
    IOError is raised if the source code cannot be retrieved."""
    lines, lnum = getsourcelines(object)
697
    return ''.join(lines)
698 699 700 701 702

# --------------------------------------------------- class tree extraction
def walktree(classes, children, parent):
    """Recursive helper function for getclasstree()."""
    results = []
703
    classes.sort(key=attrgetter('__module__', '__name__'))
704 705
    for c in classes:
        results.append((c, c.__bases__))
706
        if c in children:
707 708 709
            results.append(walktree(children[c], children, c))
    return results

710
def getclasstree(classes, unique=False):
711 712 713 714 715 716 717 718 719 720 721 722 723
    """Arrange the given list of classes into a hierarchy of nested lists.

    Where a nested list appears, it contains classes derived from the class
    whose entry immediately precedes the list.  Each entry is a 2-tuple
    containing a class and a tuple of its base classes.  If the 'unique'
    argument is true, exactly one entry appears in the returned structure
    for each class in the given list.  Otherwise, classes using multiple
    inheritance and their descendants will appear multiple times."""
    children = {}
    roots = []
    for c in classes:
        if c.__bases__:
            for parent in c.__bases__:
724
                if not parent in children:
725 726 727 728 729
                    children[parent] = []
                children[parent].append(c)
                if unique and parent in classes: break
        elif c not in roots:
            roots.append(c)
730
    for parent in children:
731 732 733 734 735
        if parent not in classes:
            roots.append(parent)
    return walktree(roots, children, None)

# ------------------------------------------------ argument list extraction
736 737
Arguments = namedtuple('Arguments', 'args, varargs, varkw')

738 739 740
def getargs(co):
    """Get information about the arguments accepted by a code object.

741
    Three things are returned: (args, varargs, varkw), where
742 743 744
    'args' is the list of argument names. Keyword-only arguments are
    appended. 'varargs' and 'varkw' are the names of the * and **
    arguments or None."""
745
    args, varargs, kwonlyargs, varkw = _getfullargs(co)
746
    return Arguments(args + kwonlyargs, varargs, varkw)
747 748 749 750 751

def _getfullargs(co):
    """Get information about the arguments accepted by a code object.

    Four things are returned: (args, varargs, kwonlyargs, varkw), where
752 753
    'args' and 'kwonlyargs' are lists of argument names, and 'varargs'
    and 'varkw' are the names of the * and ** arguments or None."""
754 755

    if not iscode(co):
Benjamin Peterson's avatar
Benjamin Peterson committed
756
        raise TypeError('{!r} is not a code object'.format(co))
757 758 759

    nargs = co.co_argcount
    names = co.co_varnames
760
    nkwargs = co.co_kwonlyargcount
761
    args = list(names[:nargs])
762
    kwonlyargs = list(names[nargs:nargs+nkwargs])
763 764
    step = 0

765
    nargs += nkwargs
766 767 768 769 770 771 772
    varargs = None
    if co.co_flags & CO_VARARGS:
        varargs = co.co_varnames[nargs]
        nargs = nargs + 1
    varkw = None
    if co.co_flags & CO_VARKEYWORDS:
        varkw = co.co_varnames[nargs]
773
    return args, varargs, kwonlyargs, varkw
774

775 776 777

ArgSpec = namedtuple('ArgSpec', 'args varargs keywords defaults')

778 779 780 781
def getargspec(func):
    """Get the names and default values of a function's arguments.

    A tuple of four things is returned: (args, varargs, varkw, defaults).
782
    'args' is a list of the argument names.
783
    'args' will include keyword-only argument names.
784
    'varargs' and 'varkw' are the names of the * and ** arguments or None.
785
    'defaults' is an n-tuple of the default values of the last n arguments.
786

787 788 789 790 791 792 793 794
    Use the getfullargspec() API for Python-3000 code, as annotations
    and keyword arguments are supported. getargspec() will raise ValueError
    if the func has either annotations or keyword arguments.
    """

    args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, ann = \
        getfullargspec(func)
    if kwonlyargs or ann:
795 796
        raise ValueError("Function has keyword-only arguments or annotations"
                         ", use getfullargspec() API which can support them")
797 798 799
    return ArgSpec(args, varargs, varkw, defaults)

FullArgSpec = namedtuple('FullArgSpec',
800
    'args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations')
801 802 803 804

def getfullargspec(func):
    """Get the names and default values of a function's arguments.

805 806
    A tuple of seven things is returned:
    (args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults annotations).
807
    'args' is a list of the argument names.
808 809 810 811 812
    'varargs' and 'varkw' are the names of the * and ** arguments or None.
    'defaults' is an n-tuple of the default values of the last n arguments.
    'kwonlyargs' is a list of keyword-only argument names.
    'kwonlydefaults' is a dictionary mapping names from kwonlyargs to defaults.
    'annotations' is a dictionary mapping argument names to annotations.
813

814
    The first four items in the tuple correspond to getargspec().
815 816 817
    """

    if ismethod(func):
818
        func = func.__func__
819
    if not isfunction(func):
Benjamin Peterson's avatar
Benjamin Peterson committed
820
        raise TypeError('{!r} is not a Python function'.format(func))
821
    args, varargs, kwonlyargs, varkw = _getfullargs(func.__code__)
822
    return FullArgSpec(args, varargs, varkw, func.__defaults__,
823
            kwonlyargs, func.__kwdefaults__, func.__annotations__)
824

825 826
ArgInfo = namedtuple('ArgInfo', 'args varargs keywords locals')

827 828 829 830
def getargvalues(frame):
    """Get information about arguments passed into a particular frame.

    A tuple of four things is returned: (args, varargs, varkw, locals).
831
    'args' is a list of the argument names.
832 833 834
    'varargs' and 'varkw' are the names of the * and ** arguments or None.
    'locals' is the locals dictionary of the given frame."""
    args, varargs, varkw = getargs(frame.f_code)
Benjamin Peterson's avatar
Benjamin Peterson committed
835
    return ArgInfo(args, varargs, varkw, frame.f_locals)
836

837 838
def formatannotation(annotation, base_module=None):
    if isinstance(annotation, type):
839
        if annotation.__module__ in ('builtins', base_module):
840 841 842
            return annotation.__name__
        return annotation.__module__+'.'+annotation.__name__
    return repr(annotation)
843

844
def formatannotationrelativeto(object):
845 846 847 848
    module = getattr(object, '__module__', None)
    def _formatannotation(annotation):
        return formatannotation(annotation, module)
    return _formatannotation
849

850
def formatargspec(args, varargs=None, varkw=None, defaults=None,
851
                  kwonlyargs=(), kwonlydefaults={}, annotations={},
852 853 854 855
                  formatarg=str,
                  formatvarargs=lambda name: '*' + name,
                  formatvarkw=lambda name: '**' + name,
                  formatvalue=lambda value: '=' + repr(value),
856
                  formatreturns=lambda text: ' -> ' + text,
857
                  formatannotation=formatannotation):
858
    """Format an argument spec from the values returned by getargspec
859 860 861 862 863 864 865 866 867 868 869 870
    or getfullargspec.

    The first seven arguments are (args, varargs, varkw, defaults,
    kwonlyargs, kwonlydefaults, annotations).  The other five arguments
    are the corresponding optional formatting functions that are called to
    turn names and values into strings.  The last argument is an optional
    function to format the sequence of arguments."""
    def formatargandannotation(arg):
        result = formatarg(arg)
        if arg in annotations:
            result += ': ' + formatannotation(annotations[arg])
        return result
871 872 873
    specs = []
    if defaults:
        firstdefault = len(args) - len(defaults)
874
    for i, arg in enumerate(args):
875
        spec = formatargandannotation(arg)
876 877 878
        if defaults and i >= firstdefault:
            spec = spec + formatvalue(defaults[i - firstdefault])
        specs.append(spec)
879
    if varargs is not None:
880 881 882 883 884 885 886
        specs.append(formatvarargs(formatargandannotation(varargs)))
    else:
        if kwonlyargs:
            specs.append('*')
    if kwonlyargs:
        for kwonlyarg in kwonlyargs:
            spec = formatargandannotation(kwonlyarg)
887
            if kwonlydefaults and kwonlyarg in kwonlydefaults:
888 889
                spec += formatvalue(kwonlydefaults[kwonlyarg])
            specs.append(spec)
890
    if varkw is not None:
891
        specs.append(formatvarkw(formatargandannotation(varkw)))
892
    result = '(' + ', '.join(specs) + ')'
893 894 895
    if 'return' in annotations:
        result += formatreturns(formatannotation(annotations['return']))
    return result
896 897 898 899 900

def formatargvalues(args, varargs, varkw, locals,
                    formatarg=str,
                    formatvarargs=lambda name: '*' + name,
                    formatvarkw=lambda name: '**' + name,
901
                    formatvalue=lambda value: '=' + repr(value)):
902 903 904 905 906 907 908 909 910 911 912
    """Format an argument spec from the 4 values returned by getargvalues.

    The first four arguments are (args, varargs, varkw, locals).  The
    next four arguments are the corresponding optional formatting functions
    that are called to turn names and values into strings.  The ninth
    argument is an optional function to format the sequence of arguments."""
    def convert(name, locals=locals,
                formatarg=formatarg, formatvalue=formatvalue):
        return formatarg(name) + formatvalue(locals[name])
    specs = []
    for i in range(len(args)):
913
        specs.append(convert(args[i]))
914 915 916 917
    if varargs:
        specs.append(formatvarargs(varargs) + formatvalue(locals[varargs]))
    if varkw:
        specs.append(formatvarkw(varkw) + formatvalue(locals[varkw]))
918
    return '(' + ', '.join(specs) + ')'
919

920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936
def _missing_arguments(f_name, argnames, pos, values):
    names = [repr(name) for name in argnames if name not in values]
    missing = len(names)
    if missing == 1:
        s = names[0]
    elif missing == 2:
        s = "{} and {}".format(*names)
    else:
        tail = ", {} and {}".format(names[-2:])
        del names[-2:]
        s = ", ".join(names) + tail
    raise TypeError("%s() missing %i required %s argument%s: %s" %
                    (f_name, missing,
                      "positional" if pos else "keyword-only",
                      "" if missing == 1 else "s", s))

def _too_many(f_name, args, kwonly, varargs, defcount, given, values):
937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956
    atleast = len(args) - defcount
    kwonly_given = len([arg for arg in kwonly if arg in values])
    if varargs:
        plural = atleast != 1
        sig = "at least %d" % (atleast,)
    elif defcount:
        plural = True
        sig = "from %d to %d" % (atleast, len(args))
    else:
        plural = len(args) != 1
        sig = str(len(args))
    kwonly_sig = ""
    if kwonly_given:
        msg = " positional argument%s (and %d keyword-only argument%s)"
        kwonly_sig = (msg % ("s" if given != 1 else "", kwonly_given,
                             "s" if kwonly_given != 1 else ""))
    raise TypeError("%s() takes %s positional argument%s but %d%s %s given" %
            (f_name, sig, "s" if plural else "", given, kwonly_sig,
             "was" if given == 1 and not kwonly_given else "were"))

957 958 959 960 961 962 963 964 965 966 967
def getcallargs(func, *positional, **named):
    """Get the mapping of arguments to values.

    A dict is returned, with keys the function argument names (including the
    names of the * and ** arguments, if any), and values the respective bound
    values from 'positional' and 'named'."""
    spec = getfullargspec(func)
    args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, ann = spec
    f_name = func.__name__
    arg2value = {}

968

969 970 971 972 973 974
    if ismethod(func) and func.__self__ is not None:
        # implicit 'self' (or 'cls' for classmethods) argument
        positional = (func.__self__,) + positional
    num_pos = len(positional)
    num_args = len(args)
    num_defaults = len(defaults) if defaults else 0
975 976 977 978

    n = min(num_pos, num_args)
    for i in range(n):
        arg2value[args[i]] = positional[i]
979
    if varargs:
980 981
        arg2value[varargs] = tuple(positional[n:])
    possible_kwargs = set(args + kwonlyargs)
982
    if varkw:
983 984 985 986 987 988 989 990 991 992 993 994 995
        arg2value[varkw] = {}
    for kw, value in named.items():
        if kw not in possible_kwargs:
            if not varkw:
                raise TypeError("%s() got an unexpected keyword argument %r" %
                                (f_name, kw))
            arg2value[varkw][kw] = value
            continue
        if kw in arg2value:
            raise TypeError("%s() got multiple values for argument %r" %
                            (f_name, kw))
        arg2value[kw] = value
    if num_pos > num_args and not varargs:
996 997
        _too_many(f_name, args, kwonlyargs, varargs, num_defaults,
                   num_pos, arg2value)
998
    if num_pos < num_args:
999 1000
        req = args[:num_args - num_defaults]
        for arg in req:
1001
            if arg not in arg2value:
1002
                _missing_arguments(f_name, req, True, arg2value)
1003 1004 1005
        for i, arg in enumerate(args[num_args - num_defaults:]):
            if arg not in arg2value:
                arg2value[arg] = defaults[i]
1006
    missing = 0
1007 1008
    for kwarg in kwonlyargs:
        if kwarg not in arg2value:
1009 1010 1011 1012 1013 1014
            if kwarg in kwonlydefaults:
                arg2value[kwarg] = kwonlydefaults[kwarg]
            else:
                missing += 1
    if missing:
        _missing_arguments(f_name, kwonlyargs, False, arg2value)
1015 1016
    return arg2value

1017
# -------------------------------------------------- stack frame extraction
1018 1019 1020

Traceback = namedtuple('Traceback', 'filename lineno function code_context index')

1021 1022 1023 1024 1025 1026 1027 1028 1029
def getframeinfo(frame, context=1):
    """Get information about a frame or traceback object.

    A tuple of five things is returned: the filename, the line number of
    the current line, the function name, a list of lines of context from
    the source code, and the index of the current line within that list.
    The optional second argument specifies the number of lines of context
    to return, which are centered around the current line."""
    if istraceback(frame):
1030
        lineno = frame.tb_lineno
1031
        frame = frame.tb_frame
1032 1033
    else:
        lineno = frame.f_lineno
1034
    if not isframe(frame):
Benjamin Peterson's avatar
Benjamin Peterson committed
1035
        raise TypeError('{!r} is not a frame or traceback object'.format(frame))
1036

1037
    filename = getsourcefile(frame) or getfile(frame)
1038
    if context > 0:
1039
        start = lineno - 1 - context//2
1040 1041
        try:
            lines, lnum = findsource(frame)
1042 1043 1044
        except IOError:
            lines = index = None
        else:
1045
            start = max(start, 1)
1046
            start = max(0, min(start, len(lines) - context))
1047
            lines = lines[start:start+context]
1048
            index = lineno - 1 - start
1049 1050 1051
    else:
        lines = index = None

1052
    return Traceback(filename, lineno, frame.f_code.co_name, lines, index)
1053 1054 1055

def getlineno(frame):
    """Get the line number from a frame object, allowing for optimization."""
Michael W. Hudson's avatar
Michael W. Hudson committed
1056 1057
    # FrameType.f_lineno is now a descriptor that grovels co_lnotab
    return frame.f_lineno
1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080

def getouterframes(frame, context=1):
    """Get a list of records for a frame and all higher (calling) frames.

    Each record contains a frame object, filename, line number, function
    name, a list of lines of context, and index within the context."""
    framelist = []
    while frame:
        framelist.append((frame,) + getframeinfo(frame, context))
        frame = frame.f_back
    return framelist

def getinnerframes(tb, context=1):
    """Get a list of records for a traceback's frame and all lower frames.

    Each record contains a frame object, filename, line number, function
    name, a list of lines of context, and index within the context."""
    framelist = []
    while tb:
        framelist.append((tb.tb_frame,) + getframeinfo(tb, context))
        tb = tb.tb_next
    return framelist

1081
def currentframe():
Benjamin Peterson's avatar
Benjamin Peterson committed
1082
    """Return the frame of the caller or None if this is not possible."""
1083
    return sys._getframe(1) if hasattr(sys, "_getframe") else None
1084 1085 1086

def stack(context=1):
    """Return a list of records for the stack above the caller's frame."""
1087
    return getouterframes(sys._getframe(1), context)
1088 1089

def trace(context=1):
Tim Peters's avatar
Tim Peters committed
1090
    """Return a list of records for the stack below the current exception."""
1091
    return getinnerframes(sys.exc_info()[2], context)
1092 1093 1094 1095 1096 1097


# ------------------------------------------------ static version of getattr

_sentinel = object()

1098 1099 1100
def _static_getmro(klass):
    return type.__dict__['__mro__'].__get__(klass)

1101 1102 1103 1104 1105 1106
def _check_instance(obj, attr):
    instance_dict = {}
    try:
        instance_dict = object.__getattribute__(obj, "__dict__")
    except AttributeError:
        pass
1107
    return dict.get(instance_dict, attr, _sentinel)
1108 1109 1110


def _check_class(klass, attr):
1111
    for entry in _static_getmro(klass):
1112 1113 1114 1115 1116
        if not _shadowed_dict(type(entry)):
            try:
                return entry.__dict__[attr]
            except KeyError:
                pass
1117 1118
    return _sentinel

1119 1120 1121 1122 1123 1124 1125
def _is_type(obj):
    try:
        _static_getmro(obj)
    except TypeError:
        return False
    return True

1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138
def _shadowed_dict(klass):
    dict_attr = type.__dict__["__dict__"]
    for entry in _static_getmro(klass):
        try:
            class_dict = dict_attr.__get__(entry)["__dict__"]
        except KeyError:
            pass
        else:
            if not (type(class_dict) is types.GetSetDescriptorType and
                    class_dict.__name__ == "__dict__" and
                    class_dict.__objclass__ is entry):
                return True
    return False
1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151

def getattr_static(obj, attr, default=_sentinel):
    """Retrieve attributes without triggering dynamic lookup via the
       descriptor protocol,  __getattr__ or __getattribute__.

       Note: this function may not be able to retrieve all attributes
       that getattr can fetch (like dynamically created attributes)
       and may find attributes that getattr can't (like descriptors
       that raise AttributeError). It can also return descriptor objects
       instead of instance members in some cases. See the
       documentation for details.
    """
    instance_result = _sentinel
1152
    if not _is_type(obj):
1153
        klass = type(obj)
1154 1155
        if not _shadowed_dict(klass):
            instance_result = _check_instance(obj, attr)
1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172
    else:
        klass = obj

    klass_result = _check_class(klass, attr)

    if instance_result is not _sentinel and klass_result is not _sentinel:
        if (_check_class(type(klass_result), '__get__') is not _sentinel and
            _check_class(type(klass_result), '__set__') is not _sentinel):
            return klass_result

    if instance_result is not _sentinel:
        return instance_result
    if klass_result is not _sentinel:
        return klass_result

    if obj is klass:
        # for types we check the metaclass too
1173
        for entry in _static_getmro(type(klass)):
1174 1175 1176 1177 1178 1179 1180
            try:
                return entry.__dict__[attr]
            except KeyError:
                pass
    if default is not _sentinel:
        return default
    raise AttributeError(attr)
1181 1182


1183 1184 1185 1186
GEN_CREATED = 'GEN_CREATED'
GEN_RUNNING = 'GEN_RUNNING'
GEN_SUSPENDED = 'GEN_SUSPENDED'
GEN_CLOSED = 'GEN_CLOSED'
1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203

def getgeneratorstate(generator):
    """Get current state of a generator-iterator.

    Possible states are:
      GEN_CREATED: Waiting to start execution.
      GEN_RUNNING: Currently being executed by the interpreter.
      GEN_SUSPENDED: Currently suspended at a yield expression.
      GEN_CLOSED: Execution has completed.
    """
    if generator.gi_running:
        return GEN_RUNNING
    if generator.gi_frame is None:
        return GEN_CLOSED
    if generator.gi_frame.f_lasti == -1:
        return GEN_CREATED
    return GEN_SUSPENDED