Skip to main content

29.12. inspect —检查活体

源代码: Lib/inspect.py


inspect 模块提供了几个有用的函数来帮助获取有关活动对象的信息,例如模块,类,方法,函数,回溯,框架对象和代码对象。例如,它可以帮助您检查类的内容,检索方法的源代码,提取和格式化函数的参数列表,或获取显示详细追溯所需的所有信息。

该模块提供了四种主要的服务类型:类型检查,获取源代码,检查类和函数,以及检查解释器堆栈。

29.12.1. 类型和成员

getmembers() 函数检索对象的成员,例如类或模块。名称以“is”开头的函数主要提供为 getmembers() 的第二个参数的方便选择。它们还可以帮助您确定何时可以找到以下特殊属性:

类型

属性

描述

模块

__doc__

文档字符串

 

__文件__

filename(对于内置模块,缺少)

__doc__

文档字符串

 

__名称__

定义此类的名称

 

__qualname__

合格名称

 

__module__

定义此类的模块的名称

方法

__doc__

文档字符串

 

__名称__

定义此方法的名称

 

__qualname__

合格名称

 

__func__

函数对象包含方法的实现

 

__自__

此方法绑定到的实例,或 None

功能

__doc__

文档字符串

 

__名称__

定义此函数的名称

 

__qualname__

合格名称

 

__码__

代码对象包含编译函数 bytecode

 

__defaults__

位置或关键字参数的任何默认值的元组

 

__kwdefaults__

仅映射关键字参数的任何默认值

 

__globals__

全局命名空间,其中定义了此函数

 

__annotations__

将参数名称映射到注释; "return" 键保留用于返回注释。

追溯

tb_frame

框架对象

 

tb_lasti

最后尝试的指令在字节码中的索引

 

tb_lineno

Python源代码中的当前行号

 

tb_next

下一个内部跟踪对象(由此级别调用)

f_back

下一个外框对象(这个框架的调用者)

 

f_builtins

内建命名空间

 

f_code

代码对象在此帧中执行

 

f_globals

全局命名空间

 

f_lasti

最后尝试的指令在字节码中的索引

 

f_lineno

Python源代码中的当前行号

 

f_locals

本框架所见的本地命名空间

 

f_restricted

0或1,如果帧处于受限执行模式

 

f_trace

此帧的跟踪功能,或 None

co_argcount

参数数量(不包括 * 或 ** args)

 

co_code

原始编译字节码字符串

 

co_consts

字节码中使用的常量的元组

 

co_filename

创建此代码对象的文件的名称

 

co_firstlineno

Python源代码中的第一行数

 

co_flags

位图的 CO_* 标志,阅读更多 这里

 

co_lnotab

行编号到字节码索引的编码映射

 

co_name

定义此代码对象的名称

 

co_names

局部变量的名称的元组

 

co_nlocals

局部变量的数量

 

co_stacksize

虚拟机栈空间需要

 

co_varnames

元组名称的参数和局部变量

发电机

__名称__

名称

 

__qualname__

合格名称

 

gi_frame

 

gi_running

是发电机运行吗?

 

gi_code

 

gi_yieldfrom

对象由 yield fromNone 迭代

协同

__名称__

名称

 

__qualname__

合格名称

 

cr_await

对象正在等待,或 None

 

cr_frame

 

cr_running

是协程运行?

 

cr_code

内置

__doc__

文档字符串

 

__名称__

此函数或方法的原始名称

 

__qualname__

合格名称

 

__自__

绑定方法的实例,或 None

在 3.5 版更改: __qualname__gi_yieldfrom 属性添加到生成器。

发生器的 __name__ 属性现在从函数名称而不是代码名称设置,现在可以修改。

inspect.getmembers(object[, predicate])

返回按名称排序的(名称,值)对的列表中的对象的所有成员。如果提供了可选的 predicate 参数,则只包括谓词返回真值的成员。

注解

当参数是一个类并且这些属性已经在元类’custom __dir__() 中列出时,getmembers() 将只返回元类中定义的类属性。

inspect.getmodulename(path)

返回由文件 path 命名的模块的名称,而不包括封装包的名称。针对 importlib.machinery.all_suffixes() 中的所有条目检查文件扩展名。如果匹配,则返回最终路径组件,并删除扩展名。否则,返回 None

注意,这个函数 only 为实际的Python模块返回一个有意义的名称 - 潜在引用Python包的路径仍然会返回 None

在 3.3 版更改: 该功能直接基于 importlib

inspect.ismodule(object)

如果对象是模块,则返回true。

inspect.isclass(object)

如果对象是类,则返回true,无论是内置还是在Python代码中创建。

inspect.ismethod(object)

如果对象是用Python编写的绑定方法,则返回true。

inspect.isfunction(object)

如果对象是Python函数,则返回true,其中包括由 lambda 表达式创建的函数。

inspect.isgeneratorfunction(object)

如果对象是Python生成器函数,则返回true。

inspect.isgenerator(object)

如果对象是生成器,则返回true。

inspect.iscoroutinefunction(object)

如果对象是 coroutine function (使用 async def 语法定义的函数),则返回true。

3.5 新版功能.

inspect.iscoroutine(object)

如果对象是由 async def 函数创建的 coroutine,则返回true。

3.5 新版功能.

inspect.isawaitable(object)

如果对象可以在 await 表达式中使用,则返回true。

也可以用于区分基于发电机的协同程序与常规发电机:

def gen():
    yield
@types.coroutine
def gen_coro():
    yield

assert not isawaitable(gen())
assert isawaitable(gen_coro())

3.5 新版功能.

inspect.isasyncgenfunction(object)

例如,如果对象是 asynchronous generator 函数,则返回true:

>>> async def agen():
...     yield 1
...
>>> inspect.isasyncgenfunction(agen)
True

3.6 新版功能.

inspect.isasyncgen(object)

如果对象是由 asynchronous generator 函数创建的 asynchronous generator iterator,则返回true。

3.6 新版功能.

inspect.istraceback(object)

如果对象是回溯,则返回true。

inspect.isframe(object)

如果对象是框架,则返回true。

inspect.iscode(object)

如果对象是代码,则返回true。

inspect.isbuiltin(object)

如果对象是内置函数或绑定内置方法,则返回true。

inspect.isroutine(object)

如果对象是用户定义的或内置的函数或方法,则返回true。

inspect.isabstract(object)

如果对象是一个抽象基类返回true。

inspect.ismethoddescriptor(object)

如果对象是方法描述符,则返回true,而如果 ismethod()isclass()isfunction()isbuiltin() 为真,则返回true。

例如,这是 int.__add__ 的真实。通过此测试的对象具有 __get__() 方法,但不是 __set__() 方法,但超出该属性集合不同。 __name__ 属性通常是明智的,__doc__ 通常是。

通过也通过其他测试之一的描述符实现的方法从 ismethoddescriptor() 测试返回false,只是因为其他测试承诺更多 - 例如,当对象通过 ismethod() 时,可以计算具有 __func__ 属性(等)。

inspect.isdatadescriptor(object)

如果对象是数据描述符,则返回true。

数据描述符具有 __get____set__ 方法。示例是属性(在Python中定义),getsets和成员。后两者在C中定义,并且有更多的特定测试可用于这些类型,这在Python实现上是稳健的。通常,数据描述符也将具有 __name____doc__ 属性(属性,获取和成员都具有这些属性),但这不是保证。

inspect.isgetsetdescriptor(object)

如果对象是getset描述符,则返回true。

getsets是通过 PyGetSetDef 结构在扩展模块中定义的属性。对于没有这种类型的Python实现,这个方法将总是返回 False

inspect.ismemberdescriptor(object)

如果对象是成员描述符,则返回true。

成员描述符是通过 PyMemberDef 结构在扩展模块中定义的属性。对于没有这种类型的Python实现,这个方法将总是返回 False

29.12.2. 检索源代码

inspect.getdoc(object)

获取对象的文档字符串,用 cleandoc() 清理。如果未提供对象的文档字符串,并且对象是类,方法,属性或描述符,则从继承层次结构检索文档字符串。

在 3.5 版更改: 如果未覆盖,现在将继承文档字符串。

inspect.getcomments(object)

在单个字符串中返回紧接对象源代码(对于类,函数或方法)之前或Python源文件(如果对象是模块)顶部的任何注释行。

inspect.getfile(object)

返回定义了对象的(文本或二进制)文件的名称。如果对象是内置模块,类或函数,则这将与 TypeError 失败。

inspect.getmodule(object)

尝试猜测一个对象被定义在哪个模块中。

inspect.getsourcefile(object)

返回定义了对象的Python源文件的名称。如果对象是内置模块,类或函数,则这将与 TypeError 失败。

inspect.getsourcelines(object)

返回对象的源行和起始行号的列表。参数可以是模块,类,方法,函数,回溯,帧或代码对象。源代码作为对应于对象的行的列表返回,并且行号指示在原始源文件中在何处找到第一行代码。如果无法检索源代码,则会引发 OSError

在 3.3 版更改: OSError 而不是 IOError,现在是前者的别名。

inspect.getsource(object)

返回对象的源代码的文本。参数可以是模块,类,方法,函数,回溯,帧或代码对象。源代码作为单个字符串返回。如果无法检索源代码,则会引发 OSError

在 3.3 版更改: OSError 而不是 IOError,现在是前者的别名。

inspect.cleandoc(doc)

从缩进到与代码块对齐的文档字符串中清除缩进。

所有前导空白都从第一行删除。可以从第二行向前均匀删除的任何前导空白被删除。随后删除开始和结束处的空行。此外,所有选项卡都会展开为空格。

29.12.3. 使用Signature对象内省可调用项

3.3 新版功能.

Signature对象表示可调用对象及其返回注释的调用签名。要检索Signature对象,请使用 signature() 函数。

inspect.signature(callable, *, follow_wrapped=True)

返回给定 callableSignature 对象:

>>> from inspect import signature
>>> def foo(a, *, b:int, **kwargs):
...     pass

>>> sig = signature(foo)

>>> str(sig)
'(a, *, b:int, **kwargs)'

>>> str(sig.parameters['b'])
'b:int'

>>> sig.parameters['b'].annotation
<class 'int'>

接受范围广泛的python可调用,从纯函数和类到 functools.partial() 对象。

如果不能提供签名,则提升 ValueError;如果不支持该类型的对象,则提高 TypeError

3.5 新版功能: follow_wrapped 参数。通过 False 以获得 callable 的签名(callable.__wrapped__ 不会用于解开装饰的可写对象。)

注解

在Python的某些实现中,一些可调用项可能不是自省的。例如,在CPython中,C中定义的一些内置函数不提供有关其参数的元数据。

class inspect.Signature(parameters=None, *, return_annotation=Signature.empty)

Signature对象表示函数的调用签名及其返回注释。对于函数接受的每个参数,它将 Parameter 对象存储在其 parameters 集合中。

可选的 parameters 参数是 Parameter 对象的序列,其被验证以检查没有具有重复名称的参数,并且参数以正确的顺序,即首先位置,然后位置或关键字,以及带默认值的参数跟随没有默认值的参数。

可选的 return_annotation 参数,可以是任意的Python对象,是可调用的“返回”注释。

签名对象是 immutable。使用 Signature.replace() 制作修改的副本。

在 3.5 版更改: 签名对象是可拾取和哈希的。

empty

指定没有返回注释的特殊类级标记。

parameters

参数名称到对应的 Parameter 对象的有序映射。

return_annotation

callable的“return”注释。如果可调用方没有“返回”注释,则此属性设置为 Signature.empty

bind(*args, **kwargs)

创建从位置和关键字参数到参数的映射。如果 *args**kwargs 匹配签名,则返回 BoundArguments,或者提出 TypeError

bind_partial(*args, **kwargs)

工作方式与 Signature.bind() 相同,但允许省略一些必需的参数(模拟 functools.partial() 行为)。返回 BoundArguments,或者如果传递的参数与签名不匹配,则引发 TypeError

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

基于实例替换调用创建新的签名实例。可以通过不同的 parameters 和/或 return_annotation 来覆盖基本签名的相应属性。要从复制的签名中删除return_annotation,请传入 Signature.empty

>>> def test(a, b):
...     pass
>>> sig = signature(test)
>>> new_sig = sig.replace(return_annotation="new return anno")
>>> str(new_sig)
"(a, b) -> 'new return anno'"
classmethod from_callable(obj, *, follow_wrapped=True)

返回给定可调用 objSignature (或其子类)对象。通过 follow_wrapped=False 获得 obj 的签名,而不打开其 __wrapped__ 链。

此方法简化了 Signature 的子类化:

class MySignature(Signature):
    pass
sig = MySignature.from_callable(min)
assert isinstance(sig, MySignature)

3.5 新版功能.

class inspect.Parameter(name, kind, *, default=Parameter.empty, annotation=Parameter.empty)

参数对象是 immutable。您可以使用 Parameter.replace() 创建修改的副本,而不是修改参数对象。

在 3.5 版更改: 参数对象是可拾取和哈希的。

empty

用于指定缺省值和注释的特殊类级标记。

name

参数的名称作为字符串。名称必须是有效的Python标识符。

CPython在用于实现理解和生成器表达式的代码对象上生成 .0 形式的隐式参数名称。

在 3.6 版更改: 这些参数名称由此模块公开为名称,如 implicit0

default

参数的默认值。如果参数没有默认值,则此属性设置为 Parameter.empty

annotation

参数的注释。如果参数没有注释,则此属性设置为 Parameter.empty

kind

描述参数值如何绑定到参数。可能的值(可通过 Parameter 访问,如 Parameter.KEYWORD_ONLY):

名称

含义

POSITIONAL_ONLY

值必须作为位置参数提供。

Python没有明确的定义位置参数的语法,但是许多内置和扩展模块函数(特别是那些只接受一个或两个参数的函数)接受它们。

POSITIONAL_OR_KEYWORD

值可以作为关键字或位置参数提供(这是在Python中实现的函数的标准绑定行为。)

VAR_POSITIONAL

没有绑定到任何其他参数的位置参数的元组。这对应于Python函数定义中的 *args 参数。

KEYWORD_ONLY

值必须作为关键字参数提供。仅关键字参数是在Python函数定义中的 **args 条目之后出现的参数。

VAR_KEYWORD

未绑定到任何其他参数的关键字参数的dict。这对应于Python函数定义中的 **kwargs 参数。

示例:打印无默认值的所有仅关键字参数:

>>> def foo(a, b, *, c, d=10):
...     pass

>>> sig = signature(foo)
>>> for param in sig.parameters.values():
...     if (param.kind == param.KEYWORD_ONLY and
...                        param.default is param.empty):
...         print('Parameter:', param)
Parameter: c
replace(*[, name][, kind][, default][, annotation])

基于被替换的实例创建一个新的Parameter实例。要覆盖 Parameter 属性,请传递相应的参数。要从参数中删除默认值或/和注释,请传递 Parameter.empty

>>> 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 版更改: 在Python 3.3中,如果参数对象的 kind 设置为 POSITIONAL_ONLY,则允许参数对象将 name 设置为 None。这不再允许。

class inspect.BoundArguments

Signature.bind()Signature.bind_partial() 呼叫的结果。保存参数到函数参数的映射。

arguments

参数名称到参数值的有序,可变映射(collections.OrderedDict)。仅包含显式绑定的参数。 arguments 中的变化将反映在 argskwargs 中。

应与 Signature.parameters 结合使用以用于任何参数处理目的。

注解

跳过 Signature.bind()Signature.bind_partial() 依赖于默认值的参数。但是,如果需要,请使用 BoundArguments.apply_defaults() 来添加它们。

args

位置参数值的元组。从 arguments 属性动态计算。

kwargs

关键字参数值的字典。从 arguments 属性动态计算。

signature

Signature 父对象的引用。

apply_defaults()

为缺少的参数设置默认值。

对于可变位置参数(*args),默认值是一个空元组。

对于变量关键字参数(**kwargs),默认值为空字符。

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

3.5 新版功能.

argskwargs 属性可用于调用函数:

def test(a, *, b):
    ...

sig = signature(test)
ba = sig.bind(10, b=20)
test(*ba.args, **ba.kwargs)

参见

PEP 362 - 函数签名对象。

详细规范,实现细节和示例。

29.12.4. 类和函数

inspect.getclasstree(classes, unique=False)

将给定的类列表排列到嵌套列表的层次结构中。在出现嵌套列表时,它包含从其列紧接在列表之前的类派生的类。每个条目是一个2元组,包含一个类和它的基类的元组。如果 unique 参数为真,则在给定列表中的每个类的返回结构中恰好出现一个条目。否则,使用多继承的类及其后代将出现多次。

inspect.getargspec(func)

获取Python函数的参数的名称和默认值。返回 named tuple ArgSpec(args, varargs, keywords, defaults)args 是参数名称的列表。 varargskeywords*** 参数或 None 的名称。 defaults 是缺省参数值的一个元组,如果没有缺省参数,则为 None;如果此元组具有 n 元素,则它们对应于 args 中列出的最后一个 n 元素。

3.0 版后已移除: 使用 getfullargspec() 作为更新的API,通常是一个插入替换,但也正确处理函数注释和仅关键字参数。

或者,使用 signature()签名对象,它们为可调用项提供更结构化的内省API。

inspect.getfullargspec(func)

获取Python函数参数的名称和默认值。返回 named tuple

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

args 是位置参数名称的列表。 varargs* 参数或 None 的名称,如果不接受任意位置参数。 varkw** 参数的名称,如果不接受任意关键字参数,则为 Nonedefaults 是对应于最后 n 位置参数的默认参数值的 n 元组,或者如果没有定义这样的默认值,则是 Nonekwonlyargs 是仅关键字参数名称的列表。 kwonlydefaults 是一个字典,将参数名称从 kwonlyargs 映射到如果没有提供参数时使用的默认值。 annotations 是将参数名称映射到注释的字典。特殊键 "return" 用于报告函数返回值注释(如果有)。

请注意,signature()签名对象 为可调内省提供了推荐的API,并支持扩展模块API中有时遇到的其他行为(如仅位置参数)。此函数主要保留在需要与Python 2 inspect 模块API保持兼容性的代码中。

在 3.4 版更改: 此函数现在基于 signature(),但仍然忽略 __wrapped__ 属性,并包括已绑定的方法的签名输出中已绑定的第一个参数。

在 3.6 版更改: 此方法以前被记录为不赞成使用Python 3.5中的 signature(),但该决定已被逆转为了恢复一个明确支持的标准接口,单一源代码的Python 2/3代码迁移离开传统的 getargspec() API。

inspect.getargvalues(frame)

获取传递到特定框架的参数的信息。返回 named tuple ArgInfo(args, varargs, keywords, locals)args 是参数名称的列表。 varargskeywords*** 参数或 None 的名称。 locals 是给定帧的本地字典。

3.5 版后已移除: 使用 signature()签名对象,为callables提供更好的内省API。

inspect.formatargspec(args[, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations[, formatarg, formatvarargs, formatvarkw, formatvalue, formatreturns, formatannotations]])

根据 getfullargspec() 返回的值设置一个漂亮的参数规范。

前七个参数是(argsvarargsvarkwdefaultskwonlyargskwonlydefaultsannotations)。

其他六个参数是被调用来分别将参数名称,* 参数名称,** 参数名称,默认值,返回注释和单个注释转换为字符串的函数。

例如:

>>> from inspect import formatargspec, getfullargspec
>>> def f(a: int, b: float):
...     pass
...
>>> formatargspec(*getfullargspec(f))
'(a: int, b: float)'

3.5 版后已移除: 使用 signature()签名对象,为callables提供更好的内省API。

inspect.formatargvalues(args[, varargs, varkw, locals, formatarg, formatvarargs, formatvarkw, formatvalue])

根据 getargvalues() 返回的四个值设置一个漂亮的参数规范。格式*参数是相应的可选格式化函数,用于将名称和值转换为字符串。

3.5 版后已移除: 使用 signature()签名对象,为callables提供更好的内省API。

inspect.getmro(cls)

在方法解析顺序中返回类cls的基类的一个元组,包括cls。没有类在此元组中多次出现。请注意,方法解析顺序取决于cls的类型。除非使用非常特殊的用户定义元类型,否则cls将是元组的第一个元素。

inspect.getcallargs(func, *args, **kwds)

argskwds 绑定到Python函数或方法 func 的参数名称,就像它们被调用一样。对于绑定的方法,还将第一个参数(通常命名为 self)绑定到关联的实例。返回dict,将参数名称(包括 *** 参数的名称,如果有的话)映射到来自 argskwds 的值。在不正确地调用 func 的情况下,即每当 func(*args, **kwds) 由于不兼容的签名而引发异常时,引发相同类型和相同或类似消息的异常。例如:

>>> from inspect import getcallargs
>>> def f(a, b=1, *pos, **named):
...     pass
>>> getcallargs(f, 1, 2, 3) == {'a': 1, 'named': {}, 'b': 2, 'pos': (3,)}
True
>>> getcallargs(f, a=2, x=4) == {'a': 2, 'named': {'x': 4}, 'b': 1, 'pos': ()}
True
>>> getcallargs(f)
Traceback (most recent call last):
...
TypeError: f() missing 1 required positional argument: 'a'

3.2 新版功能.

3.5 版后已移除: 使用 Signature.bind()Signature.bind_partial()

inspect.getclosurevars(func)

获取Python函数或方法 func 中的外部名称引用与其当前值的映射。返回 named tuple ClosureVars(nonlocals, globals, builtins, unbound)nonlocals 将引用名称映射到词法闭包变量,将 globals 映射到函数的模块全局变量,将 builtins 映射到从函数主体可见的内置函数。 unbound 是在函数中引用的一组名称,在给定当前模块全局和内置的情况下,这些名称无法解析。

如果 func 不是Python函数或方法,则引发 TypeError

3.3 新版功能.

inspect.unwrap(func, *, stop=None)

获取由 func 包装的对象。它遵循返回链中最后一个对象的 __wrapped__ 属性链。

stop 是一个可选的回调,它接受包装器链中的一个对象作为其唯一的参数,如果回调返回一个真值,则允许解包被提前终止。如果回调从不返回真值,则链中的最后一个对象将照常返回。例如,如果链中的任何对象具有定义的 __signature__ 属性,signature() 使用它来停止展开。

如果遇到循环,则引发 ValueError

3.4 新版功能.

29.12.5. 解释器堆栈

当以下函数返回“帧记录”时,每个记录都是 named tuple FrameInfo(frame, filename, lineno, function, code_context, index)。元组包含帧对象,文件名,当前行的行号,函数名称,源代码的上下文行列表,以及该列表中当前行的索引。

在 3.5 版更改: 返回一个命名的元组,而不是一个元组。

注解

保持对框架对象的引用,如在框架的第一个元素中发现的,记录这些函数返回,可以导致程序创建引用循环。一旦创建了参考循环,即使Python的可选循环检测器被启用,可以从形成循环的对象访问的所有对象的生命周期可能变得更长。如果必须创建这样的循环,则重要的是确保它们被明确地断开以避免对象的延迟破坏和增加的发生的存储器消耗。

虽然周期检测器将捕获这些,但是可以通过去除 finally 子句中的周期来确定帧(和局部变量)的破坏。如果循环检测器在编译Python或使用 gc.disable() 时被禁用,这也很重要。例如:

def handle_stackframe_without_leak():
    frame = inspect.currentframe()
    try:
        # do something with the frame
    finally:
        del frame

如果要保留框架(例如稍后打印跟踪消息),您还可以使用 frame.clear() 方法中断参考周期。

大多数这些函数支持的可选 context 参数指定要返回的上下文的行数,它们以当前行为中心。

inspect.getframeinfo(frame, context=1)

获取有关框架或跟踪对象的信息。返回 named tuple Traceback(filename, lineno, function, code_context, index)

inspect.getouterframes(frame, context=1)

获取帧和所有外部帧的帧记录列表。这些框架代表导致 frame 创建的调用。返回列表中的第一个条目表示 frame;最后一个条目表示 frame 堆栈上的最外层调用。

在 3.5 版更改: 返回 命名元组 FrameInfo(frame, filename, lineno, function, code_context, index) 的列表。

inspect.getinnerframes(traceback, context=1)

获取回溯帧和所有内部帧的帧记录列表。这些帧表示作为 frame 的结果的呼叫。列表中的第一个条目表示 traceback;最后一个条目表示引发异常的位置。

在 3.5 版更改: 返回 命名元组 FrameInfo(frame, filename, lineno, function, code_context, index) 的列表。

inspect.currentframe()

返回调用者的堆栈帧的帧对象。

这个函数依赖于解释器中的Python栈框架支持,这不能保证在Python的所有实现中都存在。如果运行在没有Python栈框架的实现中,此函数返回 None

inspect.stack(context=1)

返回调用者堆栈的帧记录列表。返回列表中的第一个条目表示调用者;最后一个条目表示堆栈上的最外层调用。

在 3.5 版更改: 返回 命名元组 FrameInfo(frame, filename, lineno, function, code_context, index) 的列表。

inspect.trace(context=1)

返回在当前帧和当前正在处理的异常出现的帧之间的堆栈的帧记录的列表。列表中的第一个条目表示调用者;最后一个条目表示引发异常的位置。

在 3.5 版更改: 返回 命名元组 FrameInfo(frame, filename, lineno, function, code_context, index) 的列表。

29.12.6. 静态获取属性

当提取或检查属性的存在时,getattr()hasattr() 都可以触发代码执行。描述符,如属性,将被调用,__getattr__()__getattribute__() 可被调用。

对于需要被动内省的情况,如文档工具,这可能不方便。 getattr_static() 具有与 getattr() 相同的签名,但是避免在获取属性时执行代码。

inspect.getattr_static(obj, attr, default=None)

检索属性而不触发通过描述符协议,__getattr__()__getattribute__() 的动态查找。

注意:此函数可能无法检索getattr可以获取的所有属性(如动态创建的属性),并且可能找到getattr不能(如引发AttributeError的描述符)的属性。它也可以返回描述符对象而不是实例成员。

如果实例 __dict__ 被另一个成员(例如属性)遮蔽,则此函数将无法找到实例成员。

3.2 新版功能.

getattr_static() 不解析描述符,例如在C上实现的对象的槽描述符或getset描述符。返回描述符对象而不是底层属性。

你可以用下面的代码处理这些。请注意,对于调用这些的任意getset描述符,可能会触发代码执行:

# example code for resolving the builtin descriptor types
class _foo:
    __slots__ = ['foo']

slot_descriptor = type(_foo.foo)
getset_descriptor = type(type(open(__file__)).name)
wrapper_descriptor = type(str.__dict__['__add__'])
descriptor_types = (slot_descriptor, getset_descriptor, wrapper_descriptor)

result = getattr_static(some_object, 'foo')
if type(result) in descriptor_types:
    try:
        result = result.__get__()
    except AttributeError:
        # descriptors can raise AttributeError to
        # indicate there is no underlying value
        # in which case the descriptor itself will
        # have to do
        pass

29.12.7. 发电机和协同系统的当前状态

当实现协同调度器和用于生成器的其他高级使用时,确定生成器当前是否正在执行,正在等待开始或恢复或执行,或已经终止是有用的。 getgeneratorstate() 允许容易地确定发电机的当前状态。

inspect.getgeneratorstate(generator)

获取生成器迭代器的当前状态。

可能的状态是:
  • GEN_CREATED:正在等待开始执行。

  • GEN_RUNNING:当前正在由解释器执行。

  • GEN_SUSPENDED:目前暂停在yield表达式。

  • GEN_CLOSED:执行已完成。

3.2 新版功能.

inspect.getcoroutinestate(coroutine)

获取协程对象的当前状态。该函数旨在与由 async def 函数创建的协同程序对象一起使用,但将接受具有 cr_runningcr_frame 属性的任何类似于协同程序的对象。

可能的状态是:
  • CORO_CREATED:正在等待开始执行。

  • CORO_RUNNING:当前正在由解释器执行。

  • CORO_SUSPENDED:目前暂停等待表达。

  • CORO_CLOSED:执行完成。

3.5 新版功能.

还可以查询发电机的当前内部状态。这主要用于测试目的,以确保内部状态正在按预期更新:

inspect.getgeneratorlocals(generator)

获取 generator 中的活本地变量到其当前值的映射。返回从变量名映射到值的字典。这相当于在生成器的主体中调用 locals(),并且所有相同的警告都适用。

如果 generator 是没有当前相关联的帧的 generator,则返回空字典。如果 generator 不是Python生成器对象,则会引发 TypeError

这个函数依赖于生成器暴露Python堆栈帧以进行内省,这在Python的所有实现中不能保证是这种情况。在这种情况下,此函数将始终返回一个空字典。

3.3 新版功能.

inspect.getcoroutinelocals(coroutine)

此函数类似于 getgeneratorlocals(),但适用于由 async def 函数创建的协程对象。

3.5 新版功能.

29.12.8. 代码对象位标志

Python代码对象具有 co_flags 属性,它是以下标志的位图:

inspect.CO_NEWLOCALS

如果设置,当代码对象被执行时,将为帧的 f_locals 创建一个新的字典。

inspect.CO_VARARGS

代码对象具有可变位置参数(类似于 *args)。

inspect.CO_VARKEYWORDS

代码对象具有一个可变关键字参数(类似于 **kwargs)。

inspect.CO_GENERATOR

当代码对象是生成器函数时,设置标志,即当执行代码对象时返回生成器对象。

inspect.CO_NOFREE

如果没有自由或单元格变量,则设置该标志。

inspect.CO_COROUTINE

当代码对象是协同程序函数时,该标志被设置。当代码对象被执行时,它返回一个协程对象。有关详细信息,请参阅 PEP 492

3.5 新版功能.

inspect.CO_ITERABLE_COROUTINE

该标志用于将发电机转换为基于发电机的协同程序。具有此标志的生成器对象可以在 await 表达式中使用,并且可以 yield from 协同对象。有关详细信息,请参阅 PEP 492

3.5 新版功能.

inspect.CO_ASYNC_GENERATOR

当代码对象是异步生成器函数时,该标志被设置。当代码对象被执行时,它返回一个异步生成器对象。有关详细信息,请参阅 PEP 525

3.6 新版功能.

注解

这些标志特定于CPython,可能不会在其他Python实现中定义。此外,这些标志是一个实现细节,可以在将来的Python版本中删除或弃用。建议使用 inspect 模块的公共API来获得任何内省需求。

29.12.9. 命令行界面

inspect 模块还从命令行提供基本的自省能力。

默认情况下,接受模块的名称并打印该模块的源。可以通过附加冒号和目标对象的限定名称来打印模块中的类或函数。

--details

打印有关指定对象而不是源代码的信息