警告類別¶

有許多內建的例外代表警告類別。這種分類方式對於能夠過濾掉特定群組的警告很有用。

雖然這些在技術上是 內建例外，但它們被記錄在這裡，因為從概念上來說，它們屬於警告機制的一部分。

使用者程式碼可以透過繼承其中一個標準警告類別來定義額外的警告類別。一個警告類別必須永遠是 Warning 類別的子類別。

目前定義了以下警告類別：

警告過濾器¶

警告過濾器控制警告是被忽略、顯示，還是轉為錯誤（引發一個例外）。

從概念上講，警告過濾器維護一個有序的過濾器規格串列；任何特定的警告都會依次與串列中的每個過濾器規格進行比對，直到找到匹配項；過濾器決定了匹配項的處理方式。每個條目都是一個 (action, message, category, module, lineno) 形式的元組，其中：

• action 是以下字串之一：

  值	處理方式
  "default"	為發出警告的每個位置（模組 + 行號）印出第一次出現的匹配警告
  "error"	將匹配的警告轉為例外
  "ignore"	永不印出匹配的警告
  "always"	總是印出匹配的警告
  "module"	為發出警告的每個模組印出第一次出現的匹配警告（不論行號）
  "once"	只印出第一次出現的匹配警告，不論位置

• message 是一個包含正規表示式的字串，警告訊息的開頭必須與其匹配（不區分大小寫）。在 -W 和 PYTHONWARNINGS 中，message 是一個字面字串，警告訊息的開頭必須包含該字串（不區分大小寫），並忽略 message 開頭或結尾的任何空白字元。

• category 是一個類別（Warning 的子類別），警告類別必須是它的子類別才能匹配。

• module 是一個包含正規表示式的字串，完整限定模組名稱的開頭必須與其匹配（區分大小寫）。在 -W 和 PYTHONWARNINGS 中，module 是一個字面字串，完整限定模組名稱必須與其相等（區分大小寫），並忽略 module 開頭或結尾的任何空白字元。

• lineno 是一個整數，發出警告的行號必須與其匹配，或者為 0 以匹配所有行號。

由於 Warning 類別衍生自內建的 Exception 類別，要將警告轉為錯誤，我們只需引發 category(message)。

如果一個警告被回報且不匹配任何已註冊的過濾器，則會套用 "default" 動作（因此得名）。

action:message:category:module:line

default                      # 顯示所有警告（即使是預設忽略的警告）
ignore                       # 忽略所有警告
error                        # 將所有警告轉換為錯誤
error::ResourceWarning       # 將 ResourceWarning 訊息視為錯誤
default::DeprecationWarning  # 顯示 DeprecationWarning 訊息
ignore,default:::mymodule    # 只回報由 "mymodule" 觸發的警告
error:::mymodule             # 將 "mymodule" 中的警告轉換為錯誤

default::DeprecationWarning:__main__
ignore::DeprecationWarning
ignore::PendingDeprecationWarning
ignore::ImportWarning
ignore::ResourceWarning

import sys

if not sys.warnoptions:
    import warnings
    warnings.simplefilter("ignore")

import sys

if not sys.warnoptions:
    import os, warnings
    warnings.simplefilter("default") # 在此行程中更改過濾器
    os.environ["PYTHONWARNINGS"] = "default" # 也會影響子行程

import warnings
warnings.filterwarnings("default", category=DeprecationWarning,
                                   module=user_ns.get("__name__"))

暫時抑制警告¶

如果你正在使用的程式碼，你知道它會引發一個警告（例如一個已棄用的函式），但你不想看到這個警告（即使警告已透過命令列明確設定），那麼可以使用 catch_warnings 情境管理器來抑制該警告：

import warnings

def fxn():
    warnings.warn("deprecated", DeprecationWarning)

with warnings.catch_warnings():
    warnings.simplefilter("ignore")
    fxn()

在情境管理器中，所有警告都將被直接忽略。這允許你在使用已知的已棄用程式碼時不必看到警告，同時又不會抑制其他可能不知道自己正在使用已棄用程式碼的程式碼所發出的警告。注意：這只能在單一執行緒的應用程式中得到保證。如果兩個或多個執行緒同時使用 catch_warnings 情境管理器，其行為是未定義的。

測試警告¶

要測試程式碼引發的警告，請使用 catch_warnings 情境管理器。透過它，你可以暫時改變警告過濾器以方便你的測試。例如，執行以下操作來捕獲所有引發的警告以進行檢查：

import warnings

def fxn():
    warnings.warn("deprecated", DeprecationWarning)

with warnings.catch_warnings(record=True) as w:
    # 讓所有警告總是會被觸發。
    warnings.simplefilter("always")
    # 觸發一個警告。
    fxn()
    # 驗證一些事情
    assert len(w) == 1
    assert issubclass(w[-1].category, DeprecationWarning)
    assert "deprecated" in str(w[-1].message)

也可以使用 error 而非 always 來讓所有警告都變成例外。需要注意的一點是，如果一個警告因為 once/default 規則已經被引發過，那麼無論設定什麼過濾器，這個警告都不會再出現，除非與該警告相關的警告註冊表已被清除。

一旦情境管理器退出，警告過濾器就會恢復到進入情境時的狀態。這可以防止測試在不同測試之間以意想不到的方式更改警告過濾器，從而導致不確定的測試結果。模組中的 showwarning() 函式也會恢復到其原始值。注意：這只能在單一執行緒的應用程式中得到保證。如果兩個或多個執行緒同時使用 catch_warnings 情境管理器，其行為是未定義的。

在測試多個會引發同類警告的操作時，重要的是要以一種能確認每個操作都在引發新警告的方式來進行測試（例如，將警告設定為引發例外，並檢查操作是否引發例外；檢查警告串列的長度在每次操作後是否持續增加；或者在每次新操作前從警告串列中刪除先前的條目）。

為新版相依套件更新程式碼¶

主要針對 Python 開發者（而非以 Python 編寫的應用程式的終端使用者）的警告類別預設會被忽略。

值得注意的是，這個「預設忽略」串列包括 DeprecationWarning`（除了 ``__main__` 以外的所有模組），這意味著開發者應該確保在測試他們的程式碼時，讓通常被忽略的警告可見，以便及時收到未來 API 破壞性變更的通知（無論是在標準函式庫還是第三方套件中）。

在理想情況下，程式碼會有一個合適的測試套件，而測試執行器會在執行測試時負責隱式地啟用所有警告（unittest 模組提供的測試執行器就是這樣做的）。

在較不理想的情況下，可以透過將 -Wd 傳遞給 Python 直譯器（這是 -W default 的簡寫）或在環境中設定 PYTHONWARNINGS=default 來檢查應用程式是否使用了已棄用的介面。這會為所有警告啟用預設處理，包括那些預設被忽略的警告。要更改對遇到的警告所採取的動作，你可以更改傳遞給 -W 的引數（例如 -W error）。有關更多可能性的詳細資訊，請參閱 -W 旗標。

可用的函式¶

warnings.warn(message, category=None, stacklevel=1, source=None, *, skip_file_prefixes=())¶

發出一個警告，或者可能忽略它或引發一個例外。category 引數（如果提供）必須是一個 警告類別；它預設為 UserWarning。或者，message 可以是一個 Warning 實例，在這種情況下 category 將被忽略，並使用 message.__class__。在這種情況下，訊息文本將是 str(message)。如果發出的特定警告被 警告過濾器 轉為錯誤，此函式會引發一個例外。stacklevel 引數可以被以 Python 編寫的包裝函式使用，如下所示：

def deprecated_api(message):
    warnings.warn(message, DeprecationWarning, stacklevel=2)

這會讓警告指向 deprecated_api 的呼叫者，而不是 deprecated_api 本身的原始碼（因為後者會違背警告訊息的目的）。

skip_file_prefixes 關鍵字引數可用於指示在計算堆疊層級時應忽略哪些堆疊幀。當你希望警告總是在套件外部的呼叫點出現，而固定的 stacklevel 不適用於所有呼叫路徑或難以維護時，這會很有用。如果提供，它必須是一個字串的元組。當提供前綴時，stacklevel 會被隱式地覆寫為 max(2, stacklevel)。要讓警告歸因於目前套件外部的呼叫者，你可以這樣寫：

# example/lower.py
_warn_skips = (os.path.dirname(__file__),)

def one_way(r_luxury_yacht=None, t_wobbler_mangrove=None):
    if r_luxury_yacht:
        warnings.warn("Please migrate to t_wobbler_mangrove=.",
                      skip_file_prefixes=_warn_skips)

# example/higher.py
from . import lower

def another_way(**kw):
    lower.one_way(**kw)

這使得警告只會從存在於 example 套件之外的呼叫程式碼中，指向 example.lower.one_way() 和 package.higher.another_way() 的呼叫點。

source（如果提供）是發出 ResourceWarning 的已銷毀物件。

在 3.6 版的變更: 新增 source 參數。

在 3.12 版的變更: 新增 skip_file_prefixes。

warnings.warn_explicit(message, category, filename, lineno, module=None, registry=None, module_globals=None, source=None)¶

這是一個 warn() 功能的低階介面，明確傳入訊息、類別、檔名和行號，以及可選的模組名稱和註冊表（應為模組的 __warningregistry__ 字典）。模組名稱預設為去掉 .py 的檔名；如果沒有傳入註冊表，警告將永遠不會被抑制。message 必須是字串，category 必須是 Warning 的子類別，或者 message 可以是 Warning 的實例，在這種情況下 category 將被忽略。

module_globals（如果提供）應該是發出警告的程式碼所使用的全域命名空間。（此引數用於支援顯示在 zip 檔案或其他非檔案系統引入來源中找到的模組的原始碼）。

source（如果提供）是發出 ResourceWarning 的已銷毀物件。

在 3.6 版的變更: 新增 source 參數。

warnings.showwarning(message, category, filename, lineno, file=None, line=None)¶

將警告寫入一個檔案。預設實作會呼叫 formatwarning(message, category, filename, lineno, line) 並將結果字串寫入 file，預設為 sys.stderr。你可以透過賦值給 warnings.showwarning 來用任何可呼叫物件取代此函式。line 是要包含在警告訊息中的一行原始碼；如果未提供 line，showwarning() 將嘗試讀取由 filename 和 lineno 指定的行。

warnings.formatwarning(message, category, filename, lineno, line=None)¶

以標準方式格式化警告。這會回傳一個可能包含嵌入換行符並以換行符結尾的字串。line 是要包含在警告訊息中的一行原始碼；如果未提供 line，formatwarning() 將嘗試讀取由 filename 和 lineno 指定的行。

warnings.filterwarnings(action, message='', category=Warning, module='', lineno=0, append=False)¶

在 警告過濾器規格 串列中插入一個條目。預設情況下，條目會插入到最前面；如果 append 為 true，則會插入到最後面。這會檢查引數的型別，編譯 message 和 module 的正規表示式，並將它們作為一個元組插入到警告過濾器串列中。如果兩個條目都匹配一個特定的警告，那麼串列中較靠前的條目會覆寫較後面的條目。省略的引數預設為一個能匹配所有內容的值。

warnings.simplefilter(action, category=Warning, lineno=0, append=False)¶

在 警告過濾器規格 串列中插入一個簡單的條目。函式參數的含義與 filterwarnings() 相同，但不需要正規表示式，因為只要類別和行號匹配，插入的過濾器總是會匹配任何模組中的任何訊息。

warnings.resetwarnings()¶

重設警告過濾器。這會捨棄所有先前對 filterwarnings() 的呼叫效果，包括 -W 命令列選項和對 simplefilter() 的呼叫。

@warnings.deprecated(msg, *, category=DeprecationWarning, stacklevel=1)¶

用來指示一個類別、函式或重載 (overload) 已被棄用的裝飾器。

當此裝飾器應用於一個物件時，在使用該物件時，可能會在 runtime 發出棄用警告。靜態型別檢查器 也會在使用已棄用物件時產生診斷訊息。

用法：

from warnings import deprecated
from typing import overload

@deprecated("改用 B")
class A:
    pass

@deprecated("改用 g")
def f():
    pass

@overload
@deprecated("對 int 的支援已棄用")
def g(x: int) -> int: ...
@overload
def g(x: str) -> int: ...

由 category 指定的警告將在使用已棄用物件時於 runtime 發出。對於函式，這發生在呼叫時；對於類別，發生在實例化和建立子類別時。如果 category 是 None，則在 runtime 不會發出警告。stacklevel 決定了警告發出的位置。如果它是 1（預設值），警告會在已棄用物件的直接呼叫者處發出；如果更高，它會在堆疊的更上層發出。靜態型別檢查器的行為不受 category 和 stacklevel 引數的影響。

傳遞給裝飾器的棄用訊息會儲存在被裝飾物件的 __deprecated__ 屬性中。如果應用於重載，裝飾器必須在 @overload 裝飾器之後，這樣屬性才會存在於 typing.get_overloads() 回傳的重載上。

在 3.13 版被加入: 參閱 PEP 702。

可用的情境管理器¶

class warnings.catch_warnings(*, record=False, module=None, action=None, category=Warning, lineno=0, append=False)¶

一個情境管理器，它會複製並在退出時恢復警告過濾器和 showwarning() 函式。如果 record 引數為 False（預設值），情境管理器在進入時回傳 None。如果 record 為 True，則會回傳一個串列，該串列會由自訂的 showwarning() 函式（該函式也會抑制對 sys.stdout 的輸出）所看到的物件逐步填充。串列中的每個物件都具有與 showwarning() 的引數同名的屬性。

module 引數接受一個模組，用以取代預設的 warnings 模組，而該（被傳入）模組的過濾器將會受到保護。此引數主要用於測試 warnings 模組本身。

如果 action 引數不是 None，則其餘引數會傳遞給 simplefilter()，就像在進入情境時立即呼叫它一樣。

有關 category 和 lineno 參數的含義，請參閱 警告過濾器。

備註

catch_warnings 管理器的工作原理是替換然後再恢復模組的 showwarning() 函式和內部過濾器規格串列。這意味著情境管理器正在修改全域狀態，因此不是執行緒安全的。

在 3.11 版的變更: 新增 action、category、lineno 和 append 參數。