`inspect` — 檢查即時物件¶

原始碼: Lib/inspect.py

inspect 模組提供了幾個有用的函式，用於幫助獲取關於模組、類、方法、函式、回溯、幀物件和程式碼物件等即時物件的資訊。例如，它可以幫助你檢查類的內容、檢索方法的原始碼、提取並格式化函式的引數列表，或者獲取顯示詳細回溯所需的所有資訊。

此模組提供四種主要服務：型別檢查、獲取原始碼、檢查類和函式以及檢查直譯器堆疊。

型別和成員¶

getmembers() 函式檢索物件的成員，例如類或模組。名稱以“is”開頭的函式主要作為 getmembers() 的第二個引數的便捷選擇。它們還可以幫助你確定何時可以預期找到以下特殊屬性（有關模組屬性，請參閱模組物件上與匯入相關的屬性）

型別	屬性	描述
類	__doc__	文件字串
	__name__	定義此類的名稱
	__qualname__	限定名稱
	__module__	定義此類的模組名稱
	__type_params__	一個包含泛型類的型別引數的元組
方法	__doc__	文件字串
	__name__	定義此方法的名稱
	__qualname__	限定名稱
	__func__	包含方法實現的函式物件
	__self__	此方法繫結的例項，或 `None`
	__module__	定義此方法的模組名稱
函式	__doc__	文件字串
	__name__	定義此函式的名稱
	__qualname__	限定名稱
	__code__	包含已編譯函式位元組碼的程式碼物件
	__defaults__	位置引數或關鍵字引數的任何預設值的元組
	__kwdefaults__	僅關鍵字引數的任何預設值的對映
	__globals__	定義此函式的全域性名稱空間
	__builtins__	內建名稱空間
	__annotations__	引數名稱到註解的對映；`"return"` 鍵保留用於返回註解。
	__type_params__	一個包含泛型函式的型別引數的元組
	__module__	定義此函式的模組名稱
traceback	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_generator	返回擁有此幀的生成器或協程物件，如果幀是常規函式則返回 `None`
	f_trace	此幀的跟蹤函式，或 `None`
	f_trace_lines	指示是否為每個原始碼行觸發跟蹤事件
	f_trace_opcodes	指示是否請求每操作碼事件
	clear()	用於清除對區域性變數的所有引用
code	co_argcount	引數數量（不包括僅關鍵字引數、* 或 ** args）
	co_code	原始編譯位元組碼字串
	co_cellvars	單元變數名稱的元組（由包含範圍引用）
	co_consts	位元組碼中使用的常量的元組
	co_filename	建立此程式碼物件的檔名
	co_firstlineno	Python 原始碼中的第一行行號
	co_flags	`CO_*` 標誌的點陣圖，在此處閱讀更多資訊
	co_lnotab	行號到位元組碼索引的編碼對映
	co_freevars	自由變數名稱的元組（透過函式的閉包引用）
	co_posonlyargcount	僅位置引數的數量
	co_kwonlyargcount	僅關鍵字引數的數量（不包括 ** arg）
	co_name	定義此程式碼物件的名稱
	co_qualname	定義此程式碼物件的完全限定名稱
	co_names	除引數和函式區域性變數之外的名稱元組
	co_nlocals	區域性變數數量
	co_stacksize	所需的虛擬機器堆疊空間
	co_varnames	引數和區域性變數名稱的元組
	co_lines()	返回一個迭代器，它生成連續的位元組碼範圍
	co_positions()	返回一個迭代器，其中包含每個位元組碼指令的原始碼位置
	replace()	返回帶有新值的程式碼物件的副本
生成器	__name__	名稱
	__qualname__	限定名稱
	gi_frame	幀
	gi_running	生成器是否正在執行？
	gi_suspended	生成器是否已暫停？
	gi_code	code
	gi_yieldfrom	由 `yield from` 迭代的物件，或 `None`
非同步生成器	__name__	名稱
	__qualname__	限定名稱
	ag_await	正在等待的物件，或 `None`
	ag_frame	幀
	ag_running	生成器是否正在執行？
	ag_code	code
協程	__name__	名稱
	__qualname__	限定名稱
	cr_await	正在等待的物件，或 `None`
	cr_frame	幀
	cr_running	協程是否正在執行？
	cr_code	code
	cr_origin	協程的建立位置，或 `None`。請參閱 `sys.set_coroutine_origin_tracking_depth()`
內建	__doc__	文件字串
	__name__	此函式或方法的原始名稱
	__qualname__	限定名稱
	__self__	方法繫結的例項，或 `None`

3.5 新版功能: 為生成器新增 __qualname__ 和 gi_yieldfrom 屬性。

生成器的 __name__ 屬性現在從函式名而不是程式碼名設定，並且現在可以修改。

3.7 新版功能: 為協程新增 cr_origin 屬性。

3.10 新版功能: 為函式新增 __builtins__ 屬性。

3.14 新版功能: 為幀新增 f_generator 屬性。

inspect.getmembers(object[, predicate])¶: 返回物件的所有成員，以按名稱排序的 (name, value) 對列表形式。如果提供了可選的 *predicate* 引數（它將使用每個成員的 value 物件進行呼叫），則僅包含謂詞返回真值的成員。

備註

getmembers() 僅在引數為類且這些屬性已列在元類的自定義 __dir__() 中時，才會返回元類中定義的類屬性。

inspect.getmembers_static(object[, predicate])¶: 返回物件的所有成員，以按名稱排序的 (name, value) 對列表形式，而不透過描述符協議、__getattr__ 或 __getattribute__ 觸發動態查詢。可選地，僅返回滿足給定謂詞的成員。

備註

getmembers_static() 可能無法檢索 getmembers() 可以獲取的所有成員（例如動態建立的屬性），並且可能找到 getmembers() 無法找到的成員（例如引發 AttributeError 的描述符）。在某些情況下，它還可以返回描述符物件而不是例項成員。

在 3.11 版本中新增。

inspect.getmodulename(path)¶

返回由檔案 *path* 命名的模組的名稱，不包括 enclosing package 的名稱。副檔名與 importlib.machinery.all_suffixes() 中的所有條目進行檢查。如果匹配，則返回去除副檔名的最終路徑元件。否則，返回 None。

請注意，此函式 *僅* 返回實際 Python 模組的有意義的名稱 - 可能引用 Python 包的路徑仍將返回 None。

3.3 新版功能: 該函式直接基於 importlib。

inspect.ismodule(object)¶: 如果物件是模組，則返回 True。

inspect.isclass(object)¶: 如果物件是類，無論是內建的還是在 Python 程式碼中建立的，則返回 True。

inspect.ismethod(object)¶: 如果物件是用 Python 編寫的繫結方法，則返回 True。

inspect.ispackage(object)¶: 如果物件是包，則返回 True。

在 3.14 版本加入。

inspect.isfunction(object)¶: 如果物件是 Python 函式，其中包括透過 lambda 表示式建立的函式，則返回 True。

inspect.isgeneratorfunction(object)¶: 如果物件是 Python 生成器函式，則返回 True。

3.8 新版功能: 如果包裝函式是 Python 生成器函式，則包裝在 functools.partial() 中的函式現在返回 True。

3.13 新版功能: 如果包裝函式是 Python 生成器函式，則包裝在 functools.partialmethod() 中的函式現在返回 True。

inspect.isgenerator(object)¶: 如果物件是生成器，則返回 True。

inspect.iscoroutinefunction(object)¶: 如果物件是協程函式（用 async def 語法定義的函式）、包裝協程函式的 functools.partial()，或用 markcoroutinefunction() 標記的同步函式，則返回 True。

在 3.5 版本加入。

3.8 新版功能: 如果包裝函式是協程函式，則包裝在 functools.partial() 中的函式現在返回 True。

3.12 新版功能: 用 markcoroutinefunction() 標記的同步函式現在返回 True。

3.13 新版功能: 如果包裝函式是協程函式，則包裝在 functools.partialmethod() 中的函式現在返回 True。

inspect.markcoroutinefunction(func)¶

用於將可呼叫物件標記為協程函式的裝飾器，如果它不能被 iscoroutinefunction() 檢測到的話。

這可能對返回協程的同步函式有用，如果該函式傳遞給需要 iscoroutinefunction() 的 API。

如果可能，最好使用 async def 函式。呼叫函式並使用 iscoroutine() 測試返回值也是可以接受的。

3.12 新版功能.

inspect.iscoroutine(object)¶: 如果物件是 async def 函式建立的協程，則返回 True。

在 3.5 版本加入。

inspect.isawaitable(object)¶

如果物件可以在 await 表示式中使用，則返回 True。

也可用於區分基於生成器的協程和常規生成器

import types

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

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

在 3.5 版本加入。

inspect.isasyncgenfunction(object)¶

如果物件是非同步生成器函式，例如，則返回 True。

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

在 3.6 版本加入。

3.8 新版功能: 如果包裝函式是非同步生成器函式，則包裝在 functools.partial() 中的函式現在返回 True。

3.13 新版功能: 如果包裝函式是協程函式，則包裝在 functools.partialmethod() 中的函式現在返回 True。

inspect.isasyncgen(object)¶: 如果物件是非同步生成器函式建立的非同步生成器迭代器，則返回 True。

在 3.6 版本加入。

inspect.istraceback(object)¶: 如果物件是回溯，則返回 True。

inspect.isframe(object)¶: 如果物件是幀，則返回 True。

inspect.iscode(object)¶: 如果物件是程式碼，則返回 True。

inspect.isbuiltin(object)¶: 如果物件是內建函式或繫結的內建方法，則返回 True。

inspect.ismethodwrapper(object)¶

如果物件的型別是 MethodWrapperType，則返回 True。

這些是 MethodWrapperType 的例項，例如 __str__()、__eq__() 和 __repr__()。

在 3.11 版本中新增。

inspect.isroutine(object)¶: 如果物件是使用者定義或內建函式或方法，則返回 True。

inspect.isabstract(object)¶: 如果物件是抽象基類，則返回 True。

inspect.ismethoddescriptor(object)¶

如果物件是方法描述符，但 ismethod()、isclass()、isfunction() 或 isbuiltin() 返回 True 則不返回 True。

例如，這對於 int.__add__ 成立。透過此測試的物件具有 __get__() 方法，但沒有 __set__() 方法或 __delete__() 方法。除此之外，屬性集各不相同。__name__ 屬性通常是合理的，__doc__ 也經常是。

透過描述符實現的方法，如果也通過了其他測試，則 ismethoddescriptor() 測試會返回 False，僅僅是因為其他測試提供了更多保證——例如，當物件透過 ismethod() 時，你可以指望擁有 __func__ 屬性（等等）。

3.13 新版功能: 此函式不再錯誤地將具有 __get__() 和 __delete__() 但沒有 __set__() 的物件報告為方法描述符（此類物件是資料描述符，而不是方法描述符）。

inspect.isdatadescriptor(object)¶

如果物件是資料描述符，則返回 True。

資料描述符具有 __set__ 或 __delete__ 方法。例子包括屬性（在 Python 中定義）、getsets 和成員。後兩者在 C 中定義，並且有更具體的測試可用於這些型別，這在 Python 實現中是健壯的。通常，資料描述符也具有 __name__ 和 __doc__ 屬性（屬性、getsets 和成員都具有這些屬性），但這不是保證。

inspect.isgetsetdescriptor(object)¶: 如果物件是 getset 描述符，則返回 True。

CPython 實現細節: getsets 是透過 PyGetSetDef 結構在擴充套件模組中定義的屬性。對於沒有此類型別的 Python 實現，此方法將始終返回 False。

inspect.ismemberdescriptor(object)¶: 如果物件是成員描述符，則返回 True。

CPython 實現細節: 成員描述符是透過 PyMemberDef 結構在擴充套件模組中定義的屬性。對於沒有此類型別的 Python 實現，此方法將始終返回 False。

檢索原始碼¶

inspect.getdoc(object)¶: 獲取物件的文件字串，並使用 cleandoc() 清理。如果未提供物件的文件字串且物件是類、方法、屬性或描述符，則從繼承層次結構中檢索文件字串。如果文件字串無效或缺失，則返回 None。

3.5 新版功能: 如果未被重寫，現在會繼承文件字串。

inspect.getcomments(object)¶: 以單個字串的形式返回緊接在物件原始碼（對於類、函式或方法）或 Python 原始檔頂部（如果物件是模組）之前的任何註釋行。如果物件的原始碼不可用，則返回 None。如果物件是在 C 或互動式 shell 中定義的，則可能發生這種情況。

inspect.getfile(object)¶: 返回定義物件的（文字或二進位制）檔案的名稱。如果物件是內建模組、類或函式，則會引發 TypeError。

inspect.getmodule(object)¶: 嘗試猜測物件是在哪個模組中定義的。如果無法確定模組，則返回 None。

inspect.getsourcefile(object)¶: 返回定義物件的 Python 原始檔的名稱，如果無法確定獲取原始檔的方式，則返回 None。如果物件是內建模組、類或函式，則會引發 TypeError。

inspect.getsourcelines(object)¶: 返回物件的原始碼行列表和起始行號。引數可以是模組、類、方法、函式、回溯、幀或程式碼物件。原始碼以與物件對應的行列表形式返回，行號指示程式碼第一行在原始原始檔中的位置。如果無法檢索原始碼，則引發 OSError。如果物件是內建模組、類或函式，則引發 TypeError。

3.3 新版功能: OSError 被引發，而不是 IOError，後者現在是前者的別名。

inspect.getsource(object)¶: 返回物件的原始碼文字。引數可以是模組、類、方法、函式、回溯、幀或程式碼物件。原始碼以單個字串形式返回。如果無法檢索原始碼，則引發 OSError。如果物件是內建模組、類或函式，則引發 TypeError。

3.3 新版功能: OSError 被引發，而不是 IOError，後者現在是前者的別名。

inspect.cleandoc(doc)¶

清理文件字串中與程式碼塊對齊的縮排。

第一行的所有前導空格都會被移除。從第二行開始，可以統一移除的任何前導空格都會被移除。然後，開頭的空行和末尾的空行會被移除。此外，所有制表符都會展開為空格。

使用 Signature 物件進行可呼叫物件自省¶

在 3.3 版本加入。

Signature 物件表示可呼叫物件的呼叫簽名及其返回註解。要檢索 Signature 物件，請使用 signature() 函式。

inspect.signature(callable, *, follow_wrapped=True, globals=None, locals=None, eval_str=False, annotation_format=Format.VALUE)¶

返回給定 *callable* 的 Signature 物件

>>> 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() 物件。

如果某些註解是字串（例如，因為使用了 from __future__ import annotations），signature() 將嘗試使用 annotationlib.get_annotations() 自動解除字串化註解。*globals*、*locals* 和 *eval_str* 引數在解析註解時傳遞給 annotationlib.get_annotations()；有關如何使用這些引數的說明，請參閱 annotationlib.get_annotations() 的文件。可以將 annotationlib.Format 列舉的成員傳遞給 *annotation_format* 引數，以控制返回註解的格式。例如，使用 annotation_format=annotationlib.Format.STRING 以字串格式返回註解。

如果無法提供簽名，則引發 ValueError，如果不支援該型別的物件，則引發 TypeError。此外，如果註解是字串化的，並且 *eval_str* 不為 false，則 annotationlib.get_annotations() 中用於解除字串化註解的 eval() 呼叫可能會引發任何型別的異常。

函式簽名中的斜槓 (/) 表示其之前的引數是僅位置引數。更多資訊請參閱關於僅位置引數的 FAQ 條目。

3.5 新版功能: 添加了 *follow_wrapped* 引數。傳入 False 以專門獲取 *callable* 的簽名（callable.__wrapped__ 將不會用於解包裝飾過的可呼叫物件。）

3.10 新版功能: 添加了 *globals*、*locals* 和 *eval_str* 引數。

3.14 新版功能: 添加了 *annotation_format* 引數。

備註

某些可呼叫物件在 Python 的某些實現中可能無法自省。例如，在 CPython 中，一些在 C 中定義的內建函式不提供其引數的任何元資料。

CPython 實現細節: 如果傳入的物件具有 __signature__ 屬性，我們可能會使用它來建立簽名。確切的語義是實現細節，可能會發生未經宣佈的更改。請查閱原始碼以瞭解當前的語義。

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

一個 Signature 物件表示函式的呼叫簽名及其返回註解。對於函式接受的每個引數，它都會在其 parameters 集合中儲存一個 Parameter 物件。

可選的 *parameters* 引數是 Parameter 物件的序列，它會經過驗證以檢查是否存在具有重複名稱的引數，以及引數是否按正確順序排列，即僅位置引數在前，然後是位置或關鍵字引數，並且帶預設值的引數跟隨不帶預設值的引數。

可選的 *return_annotation* 引數可以是任意 Python 物件。它表示可呼叫物件的“返回”註解。

Signature 物件是 *不可變* 的。使用 Signature.replace() 或 copy.replace() 來建立修改後的副本。

3.5 新版功能: Signature 物件現在可 pickle 化並可雜湊。

empty¶: 一個特殊的類級別標記，用於表示沒有返回註解。

parameters¶: 引數名稱到相應 Parameter 物件的有序對映。引數按嚴格的定義順序出現，包括僅關鍵字引數。

3.7 新版功能: Python 僅在 3.7 版本中明確保證它保留了僅關鍵字引數的宣告順序，儘管在實踐中此順序在 Python 3 中始終得到保留。

return_annotation¶: 可呼叫物件的“返回”註解。如果可呼叫物件沒有“返回”註解，則此屬性設定為 Signature.empty。

bind(*args, **kwargs)¶: 建立從位置引數和關鍵字引數到引數的對映。如果 *args 和 **kwargs 與簽名匹配，則返回 BoundArguments，否則引發 TypeError。

bind_partial(*args, **kwargs)¶: 與 Signature.bind() 工作方式相同，但允許省略某些必需引數（模擬 functools.partial() 行為）。返回 BoundArguments，如果傳入的引數與簽名不匹配，則引發 TypeError。

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

基於呼叫 replace() 的例項建立一個新的 Signature 例項。可以傳遞不同的 *parameters* 和/或 *return_annotation* 來覆蓋基礎簽名的相應屬性。要從複製的 Signature 中移除 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'"

Signature 物件也受泛型函式 copy.replace() 支援。

format(*, max_width=None, quote_annotation_strings=True)¶

建立 Signature 物件的字串表示。

如果傳入 *max_width*，該方法將嘗試將簽名適應於最多 *max_width* 字元的行。如果簽名長於 *max_width*，所有引數將單獨佔一行。

如果 *quote_annotation_strings* 為 False，簽名中的註解如果為字串，則不帶引號顯示。這在簽名使用 STRING 格式建立或使用了 from __future__ import annotations 時很有用。

在 3.13 版本加入。

3.14 新版功能: 添加了 *unquote_annotations* 引數。

classmethod from_callable(obj, *, follow_wrapped=True, globals=None, locals=None, eval_str=False)¶

返回給定可呼叫物件 *obj* 的 Signature（或其子類）物件。

此方法簡化了 Signature 的子類化

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

其行為與 signature() 相同。

在 3.5 版本加入。

3.10 新版功能: 添加了 *globals*、*locals* 和 *eval_str* 引數。

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

Parameter 物件是 *不可變* 的。您可以使用 Parameter.replace() 或 copy.replace() 來建立修改後的副本，而不是修改 Parameter 物件。

3.5 新版功能: Parameter 物件現在可 pickle 化並可雜湊。

empty¶: 一個特殊的類級別標記，用於指定缺少預設值和註解。

name¶: 引數的名稱，以字串形式。名稱必須是有效的 Python 識別符號。

CPython 實現細節: 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	未繫結到任何其他引數的關鍵字引數字典。這對應於 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

kind.description¶

描述 Parameter.kind 的列舉值。

在 3.8 版本加入。

示例：列印所有引數的描述

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

>>> sig = signature(foo)
>>> for param in sig.parameters.values():
...     print(param.kind.description)
positional or keyword
positional or keyword
keyword-only
keyword-only

replace(*[, name][, kind][, default][, annotation])¶

基於呼叫 replace 的例項建立一個新的 Parameter 例項。要覆蓋 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'"

Parameter 物件也受泛型函式 copy.replace() 支援。

3.4 新版功能: 在 Python 3.3 中，Parameter 物件允許將 name 設定為 None，如果它們的 kind 設定為 POSITIONAL_ONLY。現在不再允許。

class inspect.BoundArguments¶

Signature.bind() 或 Signature.bind_partial() 呼叫的結果。儲存引數到函式引數的對映。

arguments¶

引數名稱到引數值的可變對映。只包含顯式繫結的引數。arguments 中的更改將反映在 args 和 kwargs 中。

應與 Signature.parameters 結合使用，以進行任何引數處理。

備註

對於 Signature.bind() 或 Signature.bind_partial() 依賴預設值的引數會被跳過。但是，如果需要，可以使用 BoundArguments.apply_defaults() 新增它們。

3.9 新版功能: arguments 現在是 dict 型別。以前它是 collections.OrderedDict 型別。

args¶: 位置引數值的元組。從 arguments 屬性動態計算。

kwargs¶: 關鍵字引數值的字典。從 arguments 屬性動態計算。可以按位置傳遞的引數包含在 args 中。

signature¶: 對父級 Signature 物件的引用。

apply_defaults()¶

為缺失的引數設定預設值。

對於可變位置引數 (*args)，預設值是空元組。

對於可變關鍵字引數 (**kwargs)，預設值是空字典。

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

在 3.5 版本加入。

args 和 kwargs 屬性可用於呼叫函式

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

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

參見

PEP 362 - 函式簽名物件。: 詳細規範、實現細節和示例。

類和函式¶

inspect.getclasstree(classes, unique=False)¶: 將給定的類列表排列成巢狀列表的層次結構。巢狀列表出現時，它包含從緊接在列表之前的類條目派生的類。每個條目是一個包含類及其基類元組的 2 元組。如果 unique 引數為真，則返回的結構中給定列表中的每個類只出現一個條目。否則，使用多重繼承的類及其子類將多次出現。

inspect.getfullargspec(func)¶

獲取 Python 函式引數的名稱和預設值。返回一個命名元組

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

args 是位置引數名稱的列表。varargs 是 * 引數的名稱，如果不支援任意位置引數則為 None。varkw 是 ** 引數的名稱，如果不支援任意關鍵字引數則為 None。defaults 是一個 n 元組，包含對應於最後 n 個位置引數的預設引數值，如果未定義此類預設值，則為 None。kwonlyargs 是按宣告順序排列的僅限關鍵字引數名稱列表。kwonlydefaults 是一個字典，將 kwonlyargs 中的引數名稱對映到未提供引數時使用的預設值。annotations 是一個字典，將引數名稱對映到註釋。特殊鍵 "return" 用於報告函式返回值註釋（如果有）。

請注意，signature() 和 Signature Object 提供了可呼叫自省的推薦 API，並支援擴充套件模組 API 中有時會遇到的其他行為（例如僅位置引數）。此函式主要保留用於需要與 Python 2 inspect 模組 API 保持相容的程式碼。

3.4 版本中已更改: 此函式現在基於 signature()，但仍然忽略 __wrapped__ 屬性，並且在繫結方法的簽名輸出中包含已繫結的第一個引數。

3.6 版本中已更改: 此方法此前在 Python 3.5 中被標記為已棄用，以支援 signature()，但為了恢復對從舊版 getargspec() API 遷移的單源 Python 2/3 程式碼的明確支援標準介面，該決定已被撤銷。

3.7 新版功能: Python 僅在 3.7 版本中明確保證它保留了僅關鍵字引數的宣告順序，儘管在實踐中此順序在 Python 3 中始終得到保留。

inspect.getargvalues(frame)¶: 獲取有關傳遞到特定幀的引數的資訊。返回一個命名元組 ArgInfo(args, varargs, keywords, locals)。args 是引數名稱的列表。varargs 和 keywords 是 * 和 ** 引數的名稱，或者為 None。locals 是給定幀的區域性變數字典。

備註

此函式在 Python 3.5 中被意外標記為已棄用。

inspect.formatargvalues(args[, varargs, varkw, locals, formatarg, formatvarargs, formatvarkw, formatvalue])¶: 根據 getargvalues() 返回的四個值格式化一個漂亮的引數規範。format* 引數是相應的可選格式化函式，用於將名稱和值轉換為字串。

備註

此函式在 Python 3.5 中被意外標記為已棄用。

inspect.getmro(cls)¶: 返回類 cls 的基類元組，包括 cls，按照方法解析順序排列。在此元組中，每個類只出現一次。請注意，方法解析順序取決於 cls 的型別。除非使用了非常特殊的自定義元型別，否則 cls 將是元組的第一個元素。

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

將 args 和 kwds 繫結到 Python 函式或方法 func 的引數名稱，就像它被它們呼叫一樣。對於繫結方法，還將第一個引數（通常名為 self）繫結到關聯的例項。返回一個字典，將引數名稱（包括 * 和 ** 引數的名稱，如果有的話）對映到它們在 args 和 kwds 中的值。如果呼叫 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 中外部名稱引用的對映到其當前值。返回一個命名元組 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 版本加入。

inspect.get_annotations(obj, *, globals=None, locals=None, eval_str=False, format=annotationlib.Format.VALUE)¶

計算物件的註釋字典。

這是 annotationlib.get_annotations() 的別名；有關更多資訊，請參閱該函式的文件。

注意

此函式可能會執行註釋中包含的任意程式碼。有關更多資訊，請參閱自省註釋的安全隱患。

在 3.10 版本加入。

3.14 版本中已更改: 此函式現在是 annotationlib.get_annotations() 的別名。將其作為 inspect.get_annotations 呼叫將繼續有效。

直譯器堆疊¶

以下某些函式返回 FrameInfo 物件。為了向後相容，這些物件允許對除 positions 之外的所有屬性執行類似元組的操作。此行為被視為已棄用，將來可能會被移除。

class inspect.FrameInfo¶

frame¶: 該記錄對應的幀物件。

filename¶: 與此記錄對應的幀所執行的程式碼相關聯的檔名。

lineno¶: 與此記錄對應的幀所執行的程式碼相關聯的當前行號。

function¶: 此記錄對應的幀正在執行的函式名稱。

code_context¶: 一個上下文行列表，來自此記錄對應的幀正在執行的原始碼。

index¶: 在 code_context 列表中正在執行的當前行的索引。

positions¶: 一個 dis.Positions 物件，包含與此記錄對應的幀正在執行的指令相關聯的起始行號、結束行號、起始列偏移量和結束列偏移量。

3.5 版本中已更改: 返回命名元組而不是 tuple。

3.11 版本中已更改: FrameInfo 現在是一個類例項（與之前的命名元組相容）。

class inspect.Traceback¶

filename¶: 與此回溯對應的幀所執行的程式碼相關聯的檔名。

lineno¶: 與此回溯對應的幀所執行的程式碼相關聯的當前行號。

function¶: 此回溯對應的幀正在執行的函式名稱。

code_context¶: 一個上下文行列表，來自此回溯對應的幀正在執行的原始碼。

index¶: 在 code_context 列表中正在執行的當前行的索引。

positions¶: 一個 dis.Positions 物件，包含與此回溯對應的幀正在執行的指令相關聯的起始行號、結束行號、起始列偏移量和結束列偏移量。

3.11 版本中已更改: Traceback 現在是一個類例項（與之前的命名元組相容）。

備註

保留對幀物件的引用（如這些函式返回的幀記錄的第一個元素中所示）可能導致您的程式建立引用迴圈。一旦建立了引用迴圈，即使啟用了 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)¶: 獲取有關幀或回溯物件的資訊。返回一個 Traceback 物件。

3.11 版本中已更改: 返回 Traceback 物件而不是命名元組。

inspect.getouterframes(frame, context=1)¶: 獲取幀和所有外部幀的 FrameInfo 物件列表。這些幀表示導致 frame 建立的呼叫。返回列表中的第一個條目表示 frame；最後一個條目表示 frame 堆疊上最外層的呼叫。

3.5 版本中已更改: 返回一個命名元組列表 FrameInfo(frame, filename, lineno, function, code_context, index)。

3.11 版本中已更改: 返回 FrameInfo 物件的列表。

inspect.getinnerframes(traceback, context=1)¶: 獲取回溯的幀和所有內部幀的 FrameInfo 物件列表。這些幀表示由於 frame 而進行的呼叫。列表中的第一個條目表示 traceback；最後一個條目表示引發異常的位置。

3.5 版本中已更改: 返回一個命名元組列表 FrameInfo(frame, filename, lineno, function, code_context, index)。

3.11 版本中已更改: 返回 FrameInfo 物件的列表。

inspect.currentframe()¶: 返回呼叫者堆疊幀的幀物件。

CPython 實現細節： 此函式依賴於直譯器中的 Python 堆疊幀支援，該支援不保證在所有 Python 實現中都存在。如果在沒有 Python 堆疊幀支援的實現中執行，此函式將返回 None。

inspect.stack(context=1)¶: 返回呼叫者堆疊的 FrameInfo 物件列表。返回列表中的第一個條目表示呼叫者；最後一個條目表示堆疊上最外層的呼叫。

3.5 版本中已更改: 返回一個命名元組列表 FrameInfo(frame, filename, lineno, function, code_context, index)。

3.11 版本中已更改: 返回 FrameInfo 物件的列表。

inspect.trace(context=1)¶: 返回當前幀和當前正在處理的異常引發幀之間堆疊的 FrameInfo 物件列表。列表中的第一個條目表示呼叫者；最後一個條目表示引發異常的位置。

3.5 版本中已更改: 返回一個命名元組列表 FrameInfo(frame, filename, lineno, function, code_context, index)。

3.11 版本中已更改: 返回 FrameInfo 物件的列表。

靜態獲取屬性¶

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

生成器、協程和非同步生成器的當前狀態¶

在實現協程排程器和用於生成器的其他高階用途時，確定生成器是當前正在執行、正在等待開始或恢復執行，還是已終止，這是很有用的。getgeneratorstate() 允許輕鬆確定生成器的當前狀態。

inspect.getgeneratorstate(generator)¶

獲取生成器迭代器的當前狀態。

可能的狀態為

GEN_CREATED: 等待開始執行。
GEN_RUNNING: 正在被直譯器執行。
GEN_SUSPENDED: 當前在 yield 表示式處暫停。
GEN_CLOSED: 執行已完成。

在 3.2 版本加入。

inspect.getcoroutinestate(coroutine)¶

獲取協程物件的當前狀態。此函式旨在用於 async def 函式建立的協程物件，但它將接受任何具有 cr_running 和 cr_frame 屬性的類似協程的物件。

可能的狀態為

CORO_CREATED: 等待開始執行。
CORO_RUNNING: 當前正在被直譯器執行。
CORO_SUSPENDED: 當前在 await 表示式處暫停。
CORO_CLOSED: 執行已完成。

在 3.5 版本加入。

inspect.getasyncgenstate(agen)¶

獲取非同步生成器物件的當前狀態。此函式旨在用於使用 yield 語句的 async def 函式建立的非同步迭代器物件，但它將接受任何具有 ag_running 和 ag_frame 屬性的類似非同步生成器的物件。

可能的狀態為

AGEN_CREATED: 等待開始執行。
AGEN_RUNNING: 當前正在被直譯器執行。
AGEN_SUSPENDED: 當前在 yield 表示式處暫停。
AGEN_CLOSED: 執行已完成。

3.12 新版功能.

還可以查詢生成器的當前內部狀態。這主要用於測試目的，以確保內部狀態按預期更新。

inspect.getgeneratorlocals(generator)¶

獲取 generator 中活動區域性變數到其當前值的對映。返回一個字典，將變數名對映到值。這等效於在生成器體內呼叫 locals()，所有相同的注意事項均適用。

如果 generator 是一個沒有當前關聯幀的生成器，則返回一個空字典。如果 generator 不是 Python 生成器物件，則會引發 TypeError。

CPython 實現細節： 此函式依賴於生成器暴露一個 Python 堆疊幀以進行自省，這在所有 Python 實現中並不保證。在這種情況下，此函式將始終返回一個空字典。

在 3.3 版本加入。

inspect.getcoroutinelocals(coroutine)¶: 此函式類似於 getgeneratorlocals()，但適用於 async def 函式建立的協程物件。

在 3.5 版本加入。

inspect.getasyncgenlocals(agen)¶: 此函式類似於 getgeneratorlocals()，但適用於使用 yield 語句的 async def 函式建立的非同步生成器物件。

3.12 新版功能.

程式碼物件位標誌¶

Python 程式碼物件具有 co_flags 屬性，它是一個以下標誌的點陣圖。

inspect.CO_OPTIMIZED¶: 程式碼物件已最佳化，使用快速區域性變數。

inspect.CO_NEWLOCALS¶: 如果設定，當代碼物件執行時，將為幀的 f_locals 建立一個新的字典。

inspect.CO_VARARGS¶: 程式碼物件有一個可變位置引數（類似 *args）。

inspect.CO_VARKEYWORDS¶: 程式碼物件有一個可變關鍵字引數（類似 **kwargs）。

inspect.CO_NESTED¶: 當代碼物件是巢狀函式時，此標誌會被設定。

inspect.CO_GENERATOR¶: 當代碼物件是生成器函式時，此標誌會被設定，即當代碼物件執行時會返回一個生成器物件。

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 版本加入。

inspect.CO_HAS_DOCSTRING¶: 當原始碼中存在程式碼物件的文件字串時，此標誌會被設定。如果設定，它將是 co_consts 中的第一個元素。

在 3.14 版本加入。

inspect.CO_METHOD¶: 當代碼物件是在類作用域中定義的函式時，此標誌會被設定。

在 3.14 版本加入。

備註

這些標誌是 CPython 特有的，並且可能未在其他 Python 實現中定義。此外，這些標誌是實現細節，並且可能在未來的 Python 版本中被刪除或棄用。建議使用 inspect 模組中的公共 API 來滿足任何自省需求。

緩衝區標誌¶

class inspect.BufferFlags¶

這是一個 enum.IntFlag，表示可以傳遞給實現緩衝區協議的物件的 __buffer__() 方法的標誌。

這些標誌的含義在緩衝區請求型別中進行了解釋。

SIMPLE¶

WRITABLE¶

FORMAT¶

ND¶

STRIDES¶

C_CONTIGUOUS¶

F_CONTIGUOUS¶

ANY_CONTIGUOUS¶

INDIRECT¶

CONTIG¶

CONTIG_RO¶

STRIDED¶

STRIDED_RO¶

RECORDS¶

RECORDS_RO¶

FULL¶

FULL_RO¶

READ¶

WRITE¶

3.12 新版功能.

命令列介面¶

inspect 模組還提供了從命令列進行基本自省的功能。

預設情況下，接受模組名稱並列印該模組的原始碼。可以透過附加冒號和目標物件的限定名稱來列印模組中的類或函式。

--details¶: 列印有關指定物件的資訊而不是原始碼

`inspect` — 檢查即時物件¶

型別和成員¶

檢索原始碼¶

使用 Signature 物件進行可呼叫物件自省¶

類和函式¶

直譯器堆疊¶

靜態獲取屬性¶

生成器、協程和非同步生成器的當前狀態¶

程式碼物件位標誌¶

緩衝區標誌¶

命令列介面¶

目錄

上一主題

下一主題

本頁

inspect — 檢查即時物件¶

型別和成員¶

檢索原始碼¶

使用 Signature 物件進行可呼叫物件自省¶

類和函式¶

直譯器堆疊¶

靜態獲取屬性¶

生成器、協程和非同步生成器的當前狀態¶

程式碼物件位標誌¶

緩衝區標誌¶

命令列介面¶

`inspect` — 檢查即時物件¶