Inspect Module

index

The inspect module provides several useful functions to help get information about live objects such as modules, classes, methods, functions, tracebacks, frame objects, and code objects.

file 'tmp.py' with defined function 'f' will be used for examples:

    # the following function will add 2 values
    def f(x,y):
        """Add args x and y."""
        return x + y

getmembers( object[, predicate]) Return all the members of an object in a list of (name, value) pairs sorted by name. If the optional predicate argument is supplied, only members for which the predicate returns a true value are included.

    getmembers(f) 
    [('__call__', <method-wrapper '__call__' of function object at 0x00D31370>), ...

getmoduleinfo( path) Return a tuple of values that describe how Python will interpret the file identified by path if it is a module, or None if it would not be identified as a module. The return tuple is (name, suffix, mode, mtype), where name is the name of the module without the name of any enclosing package, suffix is the trailing part of the file name (which may not be a dot-delimited extension), mode is the open() mode that would be used ('r' or 'rb'), and mtype is an integer giving the type of the module. mtype will have a value which can be compared to the constants defined in the imp module; see the documentation for that module for more information on module types.

    getmoduleinfo('tmp.py')    # ('tmp', '.py', 'U', 1)

getmodulename( path) Return the name of the module named by the file path, without including the names of enclosing packages. This uses the same algorithm as the interpreter uses when searching for modules. If the name cannot be matched according to the interpreter's rules, None is returned.

    getmodulename('tmp.py')    # 'tmp'

getcomments( object) Return in a single string any lines of comments immediately preceding the object's source code (for a class, function, or method), or at the top of the Python source file (if the object is a module).

    print getcomments(f)   # # the following function will add 2 values

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.

    print getdoc(f)   #  Add args x and y.

getfile( object) Return the name of the (text or binary) file in which an object was defined. This will fail with a TypeError if the object is a built-in module, class, or function.

    print getfile(f)   # F:\\Python25\\tmp.py

getmodule( object) Try to guess which module an object was defined in.

    getmodule(f)    # <module 'tmp' from 'F:\Python25\tmp.py'>

getsourcefile( object) Return the name of the Python source file in which an object was defined. This will fail with a TypeError if the object is a built-in module, class, or function.

    getsourcefile(f)    # 'F:\\Python25\\tmp.py'

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.

    getsourcelines(f)    # (['def f(x,y):\n', '    """Add args."""\n', '    return x + y\n'], 2)

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.

    print getsource(f) 
    def f(x,y):
        """Add args."""
        return x + y

getclasstree( classes[, unique]) 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.

    class C(): pass
    class D(C): pass
    getclasstree([C, D])
    [(<class __main__.C at 0x00D400F0>, ()), [(<class __main__.D at 0x00D28E10>, 
    (<class __main__.C at 0x00D400F0>,))]]

getargspec( func) Get the names and default values of a function's arguments. A tuple of four things is returned: (args, varargs, varkw, defaults). args is a list of the argument names (it may contain nested lists). varargs and varkw are the names of the * and ** arguments or None. defaults is a tuple of default argument values or None if there are no default arguments; if this tuple has n elements, they correspond to the last n elements listed in args.

    def f(x,y,z='yes',*args,**kargs):
        return x+y
    getargspec(f)    # (['x', 'y', 'z'], 'args', 'kargs', ('yes',))

getargvalues( frame) Get information about arguments passed into a particular frame. A tuple of four things is returned: (args, varargs, varkw, locals). args is a list of the argument names (it may contain nested lists). varargs and varkw are the names of the * and ** arguments or None. locals is the locals dictionary of the given frame.

formatargspec( args[, varargs, varkw, defaults, formatarg, formatvarargs, formatvarkw, formatvalue, join]) Format a pretty argument spec from the four values returned by getargspec(). The format* arguments are the corresponding optional formatting functions that are called to turn names and values into strings.

    formatargspec(getargspec(f))    # '((x, y, z), args, kargs, (yes,))'

formatargvalues( args[, varargs, varkw, locals, formatarg, formatvarargs, formatvarkw, formatvalue, join]) Format a pretty argument spec from the four values returned by getargvalues(). The format* arguments are the corresponding optional formatting functions that are called to turn names and values into strings.

getmro( cls) Return a tuple of class cls's base classes, including cls, in method resolution order. No class appears more than once in this tuple. Note that the method resolution order depends on cls's type. Unless a very peculiar user-defined metatype is in use, cls will be the first element of the tuple.

index