inspect —- 检查对象

源代码:Lib/inspect.py


inspect 模块提供了一些有用的函数帮助获取对象的信息,例如模块、类、方法、函数、回溯、帧对象以及代码对象。例如它可以帮助你检查类的内容,获取某个方法的源代码,取得并格式化某个函数的参数列表,或者获取你需要显示的回溯的详细信息。

该模块提供了4种主要的功能:类型检查、获取源代码、检查类与函数、检查解释器的调用堆栈。

类型和成员

getmembers() 函数获取对象的成员,例如类或模块。函数名以"is"开始的函数主要作为 getmembers() 的第2个参数使用。它们也可用于判定某对象是否有如下的特殊属性:

类型属性描述
module 模块doc文档字符串
file文件名(内置模块没有文件名)
class — 类doc文档字符串
name类定义时所使用的名称
qualnamequalified name — 限定名称
module该类型被定义时所在的模块的名称
method 方法doc文档字符串
name该方法定义时所使用的名称
qualnamequalified name — 限定名称
func实现该方法的函数对象
self该方法被绑定的实例,若没有绑定则为 None
function — 函数doc文档字符串
name用于定义此函数的名称
qualnamequalified name — 限定名称
code包含已编译函数的代码对象 bytecode
defaultstuple of any defaultvalues for positional orkeyword parameters
kwdefaultsmapping of any defaultvalues for keyword-onlyparameters
globalsglobal namespace in whichthis function was defined
annotationsmapping of parametersnames to annotations;"return" key isreserved for returnannotations.
回溯tbframe此级别的框架对象
tb_lastiindex of last attemptedinstruction in bytecode
tb_linenocurrent line number inPython source code
tb_nextnext inner tracebackobject (called by thislevel)
框架f_backnext outer frame object(this frame's caller)
f_builtinsbuiltins namespace seenby this frame
f_codecode object beingexecuted in this frame
f_globalsglobal namespace seen bythis frame
f_lastiindex of last attemptedinstruction in bytecode
f_linenocurrent line number inPython source code
f_localslocal namespace seen bythis frame
f_tracetracing function for thisframe, or None
codeco_argcountnumber of arguments (notincluding keyword onlyarguments, or *args)
co_code原始编译字节码的字符串
co_cellvars单元变量名称的元组(通过包含作用域引用)
co_consts字节码中使用的常量元组
co_filename创建此代码对象的文件的名称
co_firstlinenonumber of first line inPython source code
co_flagsbitmap of CO flags,read more here
co_lnotab编码的行号到字节码索引的映射
co_freevarstuple of names of freevariables (referenced viaa function's closure)
co_kwonlyargcountnumber of keyword onlyarguments (not including* arg)
coname定义此代码对象的名称
conames局部变量名称的元组
conlocals局部变量的数量
costacksize需要虚拟机堆栈空间
covarnames参数名和局部变量的元组
generator — 生成器name名称
qualnamequalified name — 限定名称
giframe框架
girunning生成器在运行吗?
gicodecode
giyieldfromobject being iterated byyield from, orNone
coroutine — 协程name名称
_qualnamequalified name — 限定名称
cr_awaitobject being awaited on,or None
cr_frame框架
cr_runningis the coroutine running?
cr_codecode
cr_originwhere coroutine wascreated, or None. Seesys.set_coroutine_origin_tracking_depth()
builtin__doc文档字符串
__name此函数或方法的原始名称
__qualnamequalified name — 限定名称
__selfinstance to which amethod is bound, orNone

在 3.5 版更改: Add qualname and gi_yieldfrom attributes to generators.

The name attribute of generators is now set from the functionname, instead of the code name, and it can now be modified.

在 3.7 版更改: Add cr_origin attribute to coroutines.

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

注解

getmembers() will only return class attributes defined in themetaclass when the argument is a class and those attributes have beenlisted in the metaclass' custom dir().

  • inspect.getmodulename(path)
  • Return the name of the module named by the file path, without including thenames of enclosing packages. The file extension is checked against all ofthe entries in importlib.machinery.all_suffixes(). If it matches,the final path component is returned with the extension removed.Otherwise, None is returned.

Note that this function only returns a meaningful name for actualPython modules - paths that potentially refer to Python packages willstill return None.

在 3.3 版更改: The function is based directly on importlib.

  • inspect.ismodule(object)
  • Return True if the object is a module.
  • inspect.isclass(object)
  • Return True if the object is a class, whether built-in or created in Pythoncode.
  • inspect.ismethod(object)
  • Return True if the object is a bound method written in Python.
  • inspect.isfunction(object)
  • Return True if the object is a Python function, which includes functionscreated by a lambda expression.
  • inspect.isgeneratorfunction(object)
  • Return True if the object is a Python generator function.
  • inspect.isgenerator(object)
  • Return True if the object is a generator.

3.5 新版功能.

  • inspect.iscoroutine(object)
  • Return True if the object is a coroutine created by anasync def function.

3.5 新版功能.

  • inspect.isawaitable(object)
  • Return True if the object can be used in await expression.

Can also be used to distinguish generator-based coroutines from regulargenerators:

  1. def gen():
  2. yield
  3. @types.coroutine
  4. def gen_coro():
  5. yield
  6.  
  7. assert not isawaitable(gen())
  8. assert isawaitable(gen_coro())

3.5 新版功能.

  • inspect.isasyncgenfunction(object)
  • Return True if the object is an asynchronous generator function,for example:
  1. >>> async def agen():
  2. ... yield 1
  3. ...
  4. >>> inspect.isasyncgenfunction(agen)
  5. True

3.6 新版功能.

3.6 新版功能.

  • inspect.istraceback(object)
  • Return True if the object is a traceback.
  • inspect.isframe(object)
  • Return True if the object is a frame.
  • inspect.iscode(object)
  • Return True if the object is a code.
  • inspect.isbuiltin(object)
  • Return True if the object is a built-in function or a bound built-in method.
  • inspect.isroutine(object)
  • Return True if the object is a user-defined or built-in function or method.
  • inspect.isabstract(object)
  • Return True if the object is an abstract base class.

This, for example, is true of int.add. An object passing this testhas a get() method but not a set()method, but beyond that the set of attributes varies. Aname attribute is usuallysensible, and doc often is.

Methods implemented via descriptors that also pass one of the other testsreturn False from the ismethoddescriptor() test, simply because theother tests promise more — you can, e.g., count on having thefunc attribute (etc) when an object passes ismethod().

  • inspect.isdatadescriptor(object)
  • Return True if the object is a data descriptor.

Data descriptors have both a get and a set method.Examples are properties (defined in Python), getsets, and members. Thelatter two are defined in C and there are more specific tests available forthose types, which is robust across Python implementations. Typically, datadescriptors will also have name and doc attributes(properties, getsets, and members have both of these attributes), but this isnot guaranteed.

  • inspect.isgetsetdescriptor(object)
  • Return True if the object is a getset descriptor.

CPython implementation detail: getsets are attributes defined in extension modules viaPyGetSetDef structures. For Python implementations without suchtypes, this method will always return False.

  • inspect.ismemberdescriptor(object)
  • Return True if the object is a member descriptor.

CPython implementation detail: Member descriptors are attributes defined in extension modules viaPyMemberDef structures. For Python implementations without suchtypes, this method will always return False.

Retrieving source code

  • inspect.getdoc(object)
  • Get the documentation string for an object, cleaned up with cleandoc().If the documentation string for an object is not provided and the object isa class, a method, a property or a descriptor, retrieve the documentationstring from the inheritance hierarchy.

在 3.5 版更改: Documentation strings are now inherited if not overridden.

  • inspect.getcomments(object)
  • Return in a single string any lines of comments immediately preceding theobject's source code (for a class, function, or method), or at the top of thePython source file (if the object is a module). If the object's source codeis unavailable, return None. This could happen if the object has beendefined in C or the interactive shell.
  • inspect.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.
  • inspect.getmodule(object)
  • Try to guess which module an object was defined in.
  • inspect.getsourcefile(object)
  • Return the name of the Python source file in which an object was defined. Thiswill fail with a TypeError if the object is a built-in module, class, orfunction.
  • inspect.getsourcelines(object)
  • Return a list of source lines and starting line number for an object. Theargument may be a module, class, method, function, traceback, frame, or codeobject. The source code is returned as a list of the lines corresponding to theobject and the line number indicates where in the original source file the firstline of code was found. An OSError is raised if the source code cannotbe retrieved.

在 3.3 版更改: OSError is raised instead of IOError, now an alias of theformer.

  • inspect.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 isreturned as a single string. An OSError is raised if the source codecannot be retrieved.

在 3.3 版更改: OSError is raised instead of IOError, now an alias of theformer.

  • inspect.cleandoc(doc)
  • Clean up indentation from docstrings that are indented to line up with blocksof code.

All leading whitespace is removed from the first line. Any leading whitespacethat can be uniformly removed from the second line onwards is removed. Emptylines at the beginning and end are subsequently removed. Also, all tabs areexpanded to spaces.

Introspecting callables with the Signature object

3.3 新版功能.

The Signature object represents the call signature of a callable object and itsreturn annotation. To retrieve a Signature object, use the signature()function.

  • inspect.signature(callable, *, follow_wrapped=True)
  • Return a Signature object for the given callable:
  1. >>> from inspect import signature
  2. >>> def foo(a, *, b:int, **kwargs):
  3. ... pass
  4.  
  5. >>> sig = signature(foo)
  6.  
  7. >>> str(sig)
  8. '(a, *, b:int, **kwargs)'
  9.  
  10. >>> str(sig.parameters['b'])
  11. 'b:int'
  12.  
  13. >>> sig.parameters['b'].annotation
  14. <class 'int'>

Accepts a wide range of Python callables, from plain functions and classes tofunctools.partial() objects.

Raises ValueError if no signature can be provided, andTypeError if that type of object is not supported.

A slash(/) in the signature of a function denotes that the parameters priorto it are positional-only. For more info, seethe FAQ entry on positional-only parameters.

3.5 新版功能: followwrapped parameter. Pass False to get a signature ofcallable specifically (callable._wrapped will not be used tounwrap decorated callables.)

注解

Some callables may not be introspectable in certain implementations ofPython. For example, in CPython, some built-in functions defined inC provide no metadata about their arguments.

  • class inspect.Signature(parameters=None, *, return_annotation=Signature.empty)
  • A Signature object represents the call signature of a function and its returnannotation. For each parameter accepted by the function it stores aParameter object in its parameters collection.

The optional parameters argument is a sequence of Parameterobjects, which is validated to check that there are no parameters withduplicate names, and that the parameters are in the right order, i.e.positional-only first, then positional-or-keyword, and that parameters withdefaults follow parameters without defaults.

The optional return_annotation argument, can be an arbitrary Python object,is the "return" annotation of the callable.

Signature objects are immutable. Use Signature.replace() to make amodified copy.

在 3.5 版更改: Signature objects are picklable and hashable.

  • empty
  • A special class-level marker to specify absence of a return annotation.

  • parameters

  • An ordered mapping of parameters' names to the correspondingParameter objects. Parameters appear in strict definitionorder, including keyword-only parameters.

在 3.7 版更改: Python only explicitly guaranteed that it preserved the declarationorder of keyword-only parameters as of version 3.7, although in practicethis order had always been preserved in Python 3.

  • return_annotation
  • The "return" annotation for the callable. If the callable has no "return"annotation, this attribute is set to Signature.empty.

  • bind(*args, **kwargs)

  • Create a mapping from positional and keyword arguments to parameters.Returns BoundArguments if args and *kwargs match thesignature, or raises a TypeError.

  • bindpartial(args, *kwargs_)

  • Works the same way as Signature.bind(), but allows the omission ofsome required arguments (mimics functools.partial() behavior.)Returns BoundArguments, or raises a TypeError if thepassed arguments do not match the signature.

  • replace(*[, parameters][, return_annotation])

  • Create a new Signature instance based on the instance replace was invokedon. It is possible to pass different parameters and/orreturn_annotation to override the corresponding properties of the basesignature. To remove return_annotation from the copied Signature, pass inSignature.empty.
  1. >>> def test(a, b):
  2. ... pass
  3. >>> sig = signature(test)
  4. >>> new_sig = sig.replace(return_annotation="new return anno")
  5. >>> str(new_sig)
  6. "(a, b) -> 'new return anno'"
  • classmethod fromcallable(_obj, *, follow_wrapped=True)
  • Return a Signature (or its subclass) object for a given callableobj. Pass followwrapped=False to get a signature of objwithout unwrapping its _wrapped chain.

This method simplifies subclassing of Signature:

  1. class MySignature(Signature):
  2. pass
  3. sig = MySignature.from_callable(min)
  4. assert isinstance(sig, MySignature)

3.5 新版功能.

  • class inspect.Parameter(name, kind, *, default=Parameter.empty, annotation=Parameter.empty)
  • Parameter objects are immutable. Instead of modifying a Parameter object,you can use Parameter.replace() to create a modified copy.

在 3.5 版更改: Parameter objects are picklable and hashable.

  • empty
  • A special class-level marker to specify absence of default values andannotations.

  • name

  • The name of the parameter as a string. The name must be a validPython identifier.

CPython implementation detail: CPython generates implicit parameter names of the form .0 on thecode objects used to implement comprehensions and generatorexpressions.

在 3.6 版更改: These parameter names are exposed by this module as names likeimplicit0.

  • default
  • The default value for the parameter. If the parameter has no defaultvalue, this attribute is set to Parameter.empty.

  • annotation

  • The annotation for the parameter. If the parameter has no annotation,this attribute is set to Parameter.empty.

  • kind

  • Describes how argument values are bound to the parameter. Possible values(accessible via Parameter, like Parameter.KEYWORD_ONLY):

名称

含义

POSITIONAL_ONLY

Value must be supplied as a positionalargument.

Python has no explicit syntax for definingpositional-only parameters, but many built-inand extension module functions (especiallythose that accept only one or two parameters)accept them.

POSITIONAL_OR_KEYWORD

Value may be supplied as either a keyword orpositional argument (this is the standardbinding behaviour for functions implementedin Python.)

VAR_POSITIONAL

A tuple of positional arguments that aren'tbound to any other parameter. Thiscorresponds to a *args parameter in aPython function definition.

KEYWORD_ONLY

Value must be supplied as a keyword argument.Keyword only parameters are those whichappear after a or args entry in aPython function definition.

VAR_KEYWORD

A dict of keyword arguments that aren't boundto any other parameter. This corresponds to a**kwargs parameter in a Python functiondefinition.

Example: print all keyword-only arguments without default values:

  1. >>> def foo(a, b, *, c, d=10):
  2. ... pass
  3.  
  4. >>> sig = signature(foo)
  5. >>> for param in sig.parameters.values():
  6. ... if (param.kind == param.KEYWORD_ONLY and
  7. ... param.default is param.empty):
  8. ... print('Parameter:', param)
  9. Parameter: c
  • replace(*[, name][, kind][, default][, annotation])

Create a new Parameter instance based on the instance replaced was invokedon. To override a Parameter attribute, pass the correspondingargument. To remove a default value or/and an annotation from aParameter, pass Parameter.empty.

  1. >>> from inspect import Parameter>>> param = Parameter('foo', Parameter.KEYWORD_ONLY, default=42)>>> str(param)'foo=42'>>> str(param.replace()) # Will create a shallow copy of 'param''foo=42'>>> str(param.replace(default=Parameter.empty, annotation='spam'))"foo:'spam'"

在 3.4 版更改: In Python 3.3 Parameter objects were allowed to have name setto None if their kind was set to POSITIONAL_ONLY.This is no longer permitted.

Should be used in conjunction with Signature.parameters for anyargument processing purposes.

注解

Arguments for which Signature.bind() orSignature.bind_partial() relied on a default value are skipped.However, if needed, use BoundArguments.apply_defaults() to addthem.

  • args
  • A tuple of positional arguments values. Dynamically computed from thearguments attribute.

  • kwargs

  • A dict of keyword arguments values. Dynamically computed from thearguments attribute.

  • signature

  • A reference to the parent Signature object.

  • apply_defaults()

  • Set default values for missing arguments.

For variable-positional arguments (*args) the default is anempty tuple.

For variable-keyword arguments (**kwargs) the default is anempty dict.

  1. >>> def foo(a, b='ham', *args): pass
  2. >>> ba = inspect.signature(foo).bind('spam')
  3. >>> ba.apply_defaults()
  4. >>> ba.arguments
  5. OrderedDict([('a', 'spam'), ('b', 'ham'), ('args', ())])

3.5 新版功能.

The args and kwargs properties can be used to invokefunctions:

  1. def test(a, *, b):
  2. ...
  3.  
  4. sig = signature(test)
  5. ba = sig.bind(10, b=20)
  6. test(*ba.args, **ba.kwargs)

参见

  • PEP 362 - Function Signature Object.
  • The detailed specification, implementation details and examples.

类与函数

  • inspect.getclasstree(classes, unique=False)
  • Arrange the given list of classes into a hierarchy of nested lists. Where anested list appears, it contains classes derived from the class whose entryimmediately precedes the list. Each entry is a 2-tuple containing a class and atuple of its base classes. If the unique argument is true, exactly one entryappears in the returned structure for each class in the given list. Otherwise,classes using multiple inheritance and their descendants will appear multipletimes.
  • inspect.getargspec(func)
  • Get the names and default values of a Python function's parameters. Anamed tuple ArgSpec(args, varargs, keywords, defaults) isreturned. args is a list of the parameter names. varargs and keywords_are the names of the and * parameters or None. _defaults is atuple of default argument values or None if there are no defaultarguments; if this tuple has n elements, they correspond to the lastn elements listed in args.

3.0 版后已移除: Use getfullargspec() for an updated API that is usually a drop-inreplacement, but also correctly handles function annotations andkeyword-only parameters.

Alternatively, use signature() andSignature Object, which provide amore structured introspection API for callables.

  • inspect.getfullargspec(func)
  • Get the names and default values of a Python function's parameters. Anamed tuple is returned:

FullArgSpec(args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults,annotations)

args is a list of the positional parameter names.varargs is the name of the parameter or None if arbitrarypositional arguments are not accepted.varkw is the name of the * parameter or None if arbitrarykeyword arguments are not accepted.defaults is an n-tuple of default argument values corresponding to thelast n positional parameters, or None if there are no such defaultsdefined.kwonlyargs is a list of keyword-only parameter names in declaration order.kwonlydefaults is a dictionary mapping parameter names from kwonlyargs_to the default values used if no argument is supplied._annotations is a dictionary mapping parameter names to annotations.The special key "return" is used to report the function return valueannotation (if any).

Note that signature() andSignature Object provide the recommendedAPI for callable introspection, and support additional behaviours (likepositional-only arguments) that are sometimes encountered in extension moduleAPIs. This function is retained primarily for use in code that needs tomaintain compatibility with the Python 2 inspect module API.

在 3.4 版更改: This function is now based on signature(), but still ignoreswrapped attributes and includes the already bound firstparameter in the signature output for bound methods.

在 3.6 版更改: This method was previously documented as deprecated in favour ofsignature() in Python 3.5, but that decision has been reversedin order to restore a clearly supported standard interface forsingle-source Python 2/3 code migrating away from the legacygetargspec() API.

在 3.7 版更改: Python only explicitly guaranteed that it preserved the declarationorder of keyword-only parameters as of version 3.7, although in practicethis order had always been preserved in Python 3.

  • inspect.getargvalues(frame)
  • Get information about arguments passed into a particular frame. Anamed tuple ArgInfo(args, varargs, keywords, locals) isreturned. args is a list of the argument names. varargs and keywords_are the names of the and * arguments or None. _locals is thelocals dictionary of the given frame.

注解

This function was inadvertently marked as deprecated in Python 3.5.

  • inspect.formatargspec(args[, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations[, formatarg, formatvarargs, formatvarkw, formatvalue, formatreturns, formatannotations]])
  • Format a pretty argument spec from the values returned bygetfullargspec().

The first seven arguments are (args, varargs, varkw,defaults, kwonlyargs, kwonlydefaults, annotations).

The other six arguments are functions that are called to turn argument names, argument name, * argument name, default values, return annotationand individual annotations into strings, respectively.

例如:

  1. >>> from inspect import formatargspec, getfullargspec
  2. >>> def f(a: int, b: float):
  3. ... pass
  4. ...
  5. >>> formatargspec(*getfullargspec(f))
  6. '(a: int, b: float)'

3.5 版后已移除: Use signature() andSignature Object, which provide abetter introspecting API for callables.

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

注解

This function was inadvertently marked as deprecated in Python 3.5.

  • inspect.getmro(cls)
  • Return a tuple of class cls's base classes, including cls, in method resolutionorder. No class appears more than once in this tuple. Note that the methodresolution order depends on cls's type. Unless a very peculiar user-definedmetatype is in use, cls will be the first element of the tuple.
  • inspect.getcallargs(func, *args, **kwds)
  • Bind the args and kwds to the argument names of the Python function ormethod func, as if it was called with them. For bound methods, bind also thefirst argument (typically named self) to the associated instance. A dictis returned, mapping the argument names (including the names of the and** arguments, if any) to their values from args and kwds. In case ofinvoking func incorrectly, i.e. whenever func(args, **kwds) would raisean exception because of incompatible signature, an exception of the same typeand the same or similar message is raised. For example:
  1. >>> from inspect import getcallargs
  2. >>> def f(a, b=1, *pos, **named):
  3. ... pass
  4. >>> getcallargs(f, 1, 2, 3) == {'a': 1, 'named': {}, 'b': 2, 'pos': (3,)}
  5. True
  6. >>> getcallargs(f, a=2, x=4) == {'a': 2, 'named': {'x': 4}, 'b': 1, 'pos': ()}
  7. True
  8. >>> getcallargs(f)
  9. Traceback (most recent call last):
  10. ...
  11. TypeError: f() missing 1 required positional argument: 'a'

3.2 新版功能.

3.5 版后已移除: Use Signature.bind() and Signature.bind_partial() instead.

  • inspect.getclosurevars(func)
  • Get the mapping of external name references in a Python function ormethod func to their current values. Anamed tuple ClosureVars(nonlocals, globals, builtins, unbound)is returned. nonlocals maps referenced names to lexical closurevariables, globals to the function's module globals and builtins tothe builtins visible from the function body. unbound is the set of namesreferenced in the function that could not be resolved at all given thecurrent module globals and builtins.

TypeError is raised if func is not a Python function or method.

3.3 新版功能.

  • inspect.unwrap(func, *, stop=None)
  • Get the object wrapped by func. It follows the chain of wrappedattributes returning the last object in the chain.

stop is an optional callback accepting an object in the wrapper chainas its sole argument that allows the unwrapping to be terminated early ifthe callback returns a true value. If the callback never returns a truevalue, the last object in the chain is returned as usual. For example,signature() uses this to stop unwrapping if any object in thechain has a signature attribute defined.

ValueError is raised if a cycle is encountered.

3.4 新版功能.

The interpreter stack

When the following functions return "frame records," each record is anamed tupleFrameInfo(frame, filename, lineno, function, code_context, index).The tuple contains the frame object, the filename, the line number of thecurrent line,the function name, a list of lines of context from the source code, and theindex of the current line within that list.

在 3.5 版更改: Return a named tuple instead of a tuple.

注解

Keeping references to frame objects, as found in the first element of the framerecords these functions return, can cause your program to create referencecycles. Once a reference cycle has been created, the lifespan of all objectswhich can be accessed from the objects which form the cycle can become muchlonger even if Python's optional cycle detector is enabled. If such cycles mustbe created, it is important to ensure they are explicitly broken to avoid thedelayed destruction of objects and increased memory consumption which occurs.

Though the cycle detector will catch these, destruction of the frames (and localvariables) can be made deterministic by removing the cycle in afinally clause. This is also important if the cycle detector wasdisabled when Python was compiled or using gc.disable(). For example:

  1. def handle_stackframe_without_leak():
  2. frame = inspect.currentframe()
  3. try:
  4. # do something with the frame
  5. finally:
  6. del frame

If you want to keep the frame around (for example to print a tracebacklater), you can also break reference cycles by using theframe.clear() method.

The optional context argument supported by most of these functions specifiesthe number of lines of context to return, which are centered around the currentline.

  • inspect.getframeinfo(frame, context=1)
  • Get information about a frame or traceback object. A named tupleTraceback(filename, lineno, function, code_context, index) is returned.
  • inspect.getouterframes(frame, context=1)
  • Get a list of frame records for a frame and all outer frames. These framesrepresent the calls that lead to the creation of frame. The first entry in thereturned list represents frame; the last entry represents the outermost callon frame's stack.

在 3.5 版更改: A list of named tuplesFrameInfo(frame, filename, lineno, function, code_context, index)is returned.

  • inspect.getinnerframes(traceback, context=1)
  • Get a list of frame records for a traceback's frame and all inner frames. Theseframes represent calls made as a consequence of frame. The first entry in thelist represents traceback; the last entry represents where the exception wasraised.

在 3.5 版更改: A list of named tuplesFrameInfo(frame, filename, lineno, function, code_context, index)is returned.

  • inspect.currentframe()
  • Return the frame object for the caller's stack frame.

CPython implementation detail: This function relies on Python stack frame support in the interpreter,which isn't guaranteed to exist in all implementations of Python. Ifrunning in an implementation without Python stack frame support thisfunction returns None.

  • inspect.stack(context=1)
  • Return a list of frame records for the caller's stack. The first entry in thereturned list represents the caller; the last entry represents the outermostcall on the stack.

在 3.5 版更改: A list of named tuplesFrameInfo(frame, filename, lineno, function, code_context, index)is returned.

  • inspect.trace(context=1)
  • Return a list of frame records for the stack between the current frame and theframe in which an exception currently being handled was raised in. The firstentry in the list represents the caller; the last entry represents where theexception was raised.

在 3.5 版更改: A list of named tuplesFrameInfo(frame, filename, lineno, function, code_context, index)is returned.

Fetching attributes statically

Both getattr() and hasattr() can trigger code execution whenfetching or checking for the existence of attributes. Descriptors, likeproperties, will be invoked and getattr() and getattribute()may be called.

For cases where you want passive introspection, like documentation tools, thiscan be inconvenient. getattr_static() has the same signature as getattr()but avoids executing code when it fetches attributes.

  • inspect.getattrstatic(_obj, attr, default=None)
  • Retrieve attributes without triggering dynamic lookup via thedescriptor protocol, getattr() or getattribute().

Note: this function may not be able to retrieve all attributesthat getattr can fetch (like dynamically created attributes)and may find attributes that getattr can't (like descriptorsthat raise AttributeError). It can also return descriptors objectsinstead of instance members.

If the instance dict is shadowed by another member (forexample a property) then this function will be unable to find instancemembers.

3.2 新版功能.

getattr_static() does not resolve descriptors, for example slot descriptors orgetset descriptors on objects implemented in C. The descriptor objectis returned instead of the underlying attribute.

You can handle these with code like the following. Note thatfor arbitrary getset descriptors invoking these may triggercode execution:

  1. # example code for resolving the builtin descriptor types
  2. class _foo:
  3. __slots__ = ['foo']
  4.  
  5. slot_descriptor = type(_foo.foo)
  6. getset_descriptor = type(type(open(__file__)).name)
  7. wrapper_descriptor = type(str.__dict__['__add__'])
  8. descriptor_types = (slot_descriptor, getset_descriptor, wrapper_descriptor)
  9.  
  10. result = getattr_static(some_object, 'foo')
  11. if type(result) in descriptor_types:
  12. try:
  13. result = result.__get__()
  14. except AttributeError:
  15. # descriptors can raise AttributeError to
  16. # indicate there is no underlying value
  17. # in which case the descriptor itself will
  18. # have to do
  19. pass

Current State of Generators and Coroutines

When implementing coroutine schedulers and for other advanced uses ofgenerators, it is useful to determine whether a generator is currentlyexecuting, is waiting to start or resume or execution, or has alreadyterminated. getgeneratorstate() allows the current state of agenerator to be determined easily.

  • inspect.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.

3.2 新版功能.

  • inspect.getcoroutinestate(coroutine)
  • Get current state of a coroutine object. The function is intended to beused with coroutine objects created by async def functions, butwill accept any coroutine-like object that has cr_running andcr_frame attributes.

    • Possible states are:
      • CORO_CREATED: Waiting to start execution.

      • CORO_RUNNING: Currently being executed by the interpreter.

      • CORO_SUSPENDED: Currently suspended at an await expression.

      • CORO_CLOSED: Execution has completed.

3.5 新版功能.

The current internal state of the generator can also be queried. This ismostly useful for testing purposes, to ensure that internal state is beingupdated as expected:

  • inspect.getgeneratorlocals(generator)
  • Get the mapping of live local variables in generator to their currentvalues. A dictionary is returned that maps from variable names to values.This is the equivalent of calling locals() in the body of thegenerator, and all the same caveats apply.

If generator is a generator with no currently associated frame,then an empty dictionary is returned. TypeError is raised ifgenerator is not a Python generator object.

CPython implementation detail: This function relies on the generator exposing a Python stack framefor introspection, which isn't guaranteed to be the case in allimplementations of Python. In such cases, this function will alwaysreturn an empty dictionary.

3.3 新版功能.

  • inspect.getcoroutinelocals(coroutine)
  • This function is analogous to getgeneratorlocals(), butworks for coroutine objects created by async def functions.

3.5 新版功能.

Code Objects Bit Flags

Python code objects have a co_flags attribute, which is a bitmap ofthe following flags:

  • inspect.CO_OPTIMIZED
  • The code object is optimized, using fast locals.
  • inspect.CO_NEWLOCALS
  • If set, a new dict will be created for the frame's f_locals whenthe code object is executed.
  • inspect.CO_VARARGS
  • The code object has a variable positional parameter (*args-like).
  • inspect.CO_VARKEYWORDS
  • The code object has a variable keyword parameter (**kwargs-like).
  • inspect.CO_NESTED
  • The flag is set when the code object is a nested function.
  • inspect.CO_GENERATOR
  • The flag is set when the code object is a generator function, i.e.a generator object is returned when the code object is executed.
  • inspect.CO_NOFREE
  • The flag is set if there are no free or cell variables.
  • inspect.CO_COROUTINE
  • The flag is set when the code object is a coroutine function.When the code object is executed it returns a coroutine object.See PEP 492 for more details.

3.5 新版功能.

  • inspect.CO_ITERABLE_COROUTINE
  • The flag is used to transform generators into generator-basedcoroutines. Generator objects with this flag can be used inawait expression, and can yield from coroutine objects.See PEP 492 for more details.

3.5 新版功能.

  • inspect.CO_ASYNC_GENERATOR
  • The flag is set when the code object is an asynchronous generatorfunction. When the code object is executed it returns anasynchronous generator object. See PEP 525 for more details.

3.6 新版功能.

注解

The flags are specific to CPython, and may not be defined in otherPython implementations. Furthermore, the flags are an implementationdetail, and can be removed or deprecated in future Python releases.It's recommended to use public APIs from the inspect modulefor any introspection needs.

Command Line Interface

The inspect module also provides a basic introspection capabilityfrom the command line.

By default, accepts the name of a module and prints the source of thatmodule. A class or function within the module can be printed instead byappended a colon and the qualified name of the target object.

  • —details
  • Print information about the specified object rather than the source code