warnings —— 警告信息的控制?

警告類別?

警告的類別由一些內(nèi)置的異常表示。這種分類有助于對警告信息進行分組過濾。

雖然在技術上警告類別屬于 內(nèi)置異常，但也只是在此記錄一下而已，因為在概念上他們屬于警告機制的一部分。

通過對某個標準的警告類別進行派生，用戶代碼可以定義其他的警告類別。 警告類別必須是 Warning 類的子類。

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

警告過濾器?

警告過濾器控制著警告是否被忽略、顯示或轉(zhuǎn)為錯誤（觸發(fā)異常）。

從概念上講，警告過濾器維護著一個經(jīng)過排序的過濾器類別列表；任何具體的警告都會依次與列表中的每種過濾器進行匹配，直到找到一個匹配項；過濾器決定了匹配項的處理方式。每個列表項均為 ( action , message , category , module , lineno ) 格式的元組，其中：

• action 是以下字符串之一：

  值	處置
  "default"	為發(fā)出警告的每個位置（模塊+行號）打印第一個匹配警告
  "error"	將匹配警告轉(zhuǎn)換為異常
  "ignore"	從不打印匹配的警告
  "always"	總是打印匹配的警告
  "module"	為發(fā)出警告的每個模塊打印第一次匹配警告（無論行號如何）
  "once"	無論位置如何，僅打印第一次出現(xiàn)的匹配警告

• message 是包含正則表達式的字符串，警告信息的開頭必須與之匹配。該表達式編譯時不區(qū)分大小寫。

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

• module 是個字符串，包含了模塊名稱必須匹配的正則表達式。該表達式編譯時大小寫敏感。

• lineno 是個整數(shù)，發(fā)生警告的行號必須與之匹配，或為 0 表示與所有行號匹配。

由于 Warning 類是由內(nèi)置類 Exception 派生出來的，要把某個警告變成錯誤，只要觸發(fā)``category(message)`` 即可。

如果警告不匹配所有已注冊的過濾器，那就會應用 “default” 動作（正如其名）。

action:message:category:module:line

default                      # Show all warnings (even those ignored by default)
ignore                       # Ignore all warnings
error                        # Convert all warnings to errors
error::ResourceWarning       # Treat ResourceWarning messages as errors
default::DeprecationWarning  # Show DeprecationWarning messages
ignore,default:::mymodule    # Only report warnings triggered by "mymodule"
error:::mymodule[.*]         # Convert warnings to errors in "mymodule"
                             # and any subpackages of "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") # Change the filter in this process
    os.environ["PYTHONWARNINGS"] = "default" # Also affect subprocesses

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

暫時禁止警告?

如果明知正在使用會引起警告的代碼，比如某個廢棄函數(shù)，但不想看到警告（即便警告已經(jīng)通過命令行作了顯式配置），那么可以使用 catch_warnings 上下文管理器來抑制警告。

import warnings

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

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

在上下文管理器中，所有的警告將被簡單地忽略。這樣就能使用已知的過時代碼而又不必看到警告，同時也不會限制警告其他可能不知過時的代碼。注意：只能保證在單線程應用程序中生效。如果兩個以上的線程同時使用 catch_warnings 上下文管理器，行為不可預知。

測試警告?

要測試由代碼引發(fā)的警告，請采用 catch_warnings 上下文管理器。有了它，就可以臨時改變警告過濾器以方便測試。例如，以下代碼可捕獲所有的警告以便查看：

import warnings

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

with warnings.catch_warnings(record=True) as w:
    # Cause all warnings to always be triggered.
    warnings.simplefilter("always")
    # Trigger a warning.
    fxn()
    # Verify some things
    assert len(w) == 1
    assert issubclass(w[-1].category, DeprecationWarning)
    assert "deprecated" in str(w[-1].message)

也可以用 error 取代 always ，讓所有的警告都成為異常。需要注意的是，如果某條警告已經(jīng)因為 once / default 規(guī)則而被引發(fā)，那么無論設置什么過濾器，該條警告都不會再出現(xiàn)，除非該警告有關的注冊數(shù)據(jù)被清除。

一旦上下文管理器退出，警告過濾器將恢復到剛進此上下文時的狀態(tài)。這樣在多次測試時可防止意外改變警告過濾器，從而導致不確定的測試結果。模塊中的 showwarning() 函數(shù)也被恢復到初始值。注意：這只能在單線程應用程序中得到保證。如果兩個以上的線程同時使用 catch_warnings 上下文管理器，行為未定義。

當測試多項操作會引發(fā)同類警告時，重點是要確保每次操作都會觸發(fā)新的警告（比如，將警告設置為異常并檢查操作是否觸發(fā)異常，檢查每次操作后警告列表的長度是否有增加，否則就在每次新操作前將以前的警告列表項刪除）。

為新版本的依賴關系更新代碼?

在默認情況下，主要針對 Python 開發(fā)者（而不是 Python 應用程序的最終用戶）的警告類別，會被忽略。

值得注意的是，這個“默認忽略”的列表包含 DeprecationWarning （適用于每個模塊，除了 __main__），這意味著開發(fā)人員應該確保在測試代碼時應將通常忽略的警告顯示出來，以便未來破壞性 API 變化時及時收到通知（無論是在標準庫還是第三方包）。

理想情況下，代碼會有一個合適的測試套件，在運行測試時會隱含地啟用所有警告（由 unittest 模塊提供的測試運行程序就是如此）。

在不太理想的情況下，可以通過向 Python 解釋器傳入 -Wd (這是 -W default 的簡寫) 或設置環(huán)境變量 PYTHONWARNINGS=default 來檢查應用程序是否用到了已棄用的接口。 這樣可以啟用對所有警告的默認處理操作，包括那些默認忽略的警告。 要改變遇到警告后執(zhí)行的動作，可以改變傳給 -W 的參數(shù) (例如 -W error)。 請參閱 -W 旗標來了解更多的細節(jié)。

可用的函數(shù)?

warnings.warn(message, category=None, stacklevel=1, source=None)?

引發(fā)警告、忽略或者觸發(fā)異常。 如果給出 category 參數(shù)，則必須是 警告類別類 ；默認為 UserWarning。 或者 message 可為 Warning 的實例，這時 category 將被忽略，轉(zhuǎn)而采用 message.__class__。 在這種情況下，錯誤信息文本將是 str(message)。 如果某條警告被 警告過濾器 改成了錯誤，本函數(shù)將觸發(fā)一條異常。 參數(shù) stacklevel 可供 Python 包裝函數(shù)使用，比如:

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

這會讓警告指向 deprecation() 的調(diào)用者，而不是 deprecation() 本身的來源（因為后者會破壞引發(fā)警告的目的）。

source 是發(fā)出 ResourceWarning 的被銷毀對象。

在 3.6 版更改: 加入 source  參數(shù)。

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

這是 warn() 函數(shù)的底層接口，顯式傳入消息、類別、文件名和行號，以及可選的模塊名和注冊表（應為模塊的 __warningregistry__ 字典）。 模塊名稱默認為去除了 .py 的文件名；如果未傳遞注冊表，警告就不會被抑制。 message 必須是個字符串，category 是 Warning 的子類；或者*message* 可為 Warning 的實例，且 category 將被忽略。

module_globals 應為發(fā)出警告的代碼所用的全局命名空間。（該參數(shù)用于從 zip 文件或其他非文件系統(tǒng)導入模塊時顯式源碼）。

source 是發(fā)出 ResourceWarning 的被銷毀對象。

在 3.6 版更改: 加入 source 參數(shù)。

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

將警告信息寫入文件。默認的實現(xiàn)代碼是調(diào)用``formatwarning(message, category, filename, lineno, line)`` 并將結果字符串寫入 file ，默認文件為 sys.stderr。通過將任何可調(diào)用對象賦給 warnings.showwarning 可替換掉該函數(shù)。line 是要包含在警告信息中的一行源代碼；如果未提供 line，showwarning() 將嘗試讀取由*filename* 和 lineno 指定的行。

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

以標準方式格式化一條警告信息。將返回一個字符串，可能包含內(nèi)嵌的換行符，并以換行符結束。如果未提供 line，formatwarning() 將嘗試讀取由 filename 和 lineno 指定的行。

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

在 警告過濾器種類 列表中插入一條數(shù)據(jù)項。默認情況下，該數(shù)據(jù)項將被插到前面；如果 append 為 True，則會插到后面。這里會檢查參數(shù)的類型，編譯 message 和 module 正則表達式，并將他們作為一個元組插入警告過濾器的列表中。如果兩者都與某種警告匹配，那么靠近列表前面的數(shù)據(jù)項就會覆蓋后面的項。省略的參數(shù)默認匹配任意值。

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

在 警告過濾器種類 列表中插入一條簡單數(shù)據(jù)項。函數(shù)參數(shù)的含義與 filterwarnings() 相同，但不需要正則表達式，因為插入的過濾器總是匹配任何模塊中的任何信息，只要類別和行號匹配即可。

warnings.resetwarnings()?

重置警告過濾器。這將丟棄之前對 filterwarnings() 的所有調(diào)用，包括 -W 命令行選項和對 simplefilter() 的調(diào)用效果。

可用的上下文管理器?

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

該上下文管理器會復制警告過濾器和 showwarning() 函數(shù)，并在退出時恢復。 如果 record 參數(shù)是 False (默認)，則在進入時會返回 None。 如果 record 為 True，則返回一個列表，列表由自定義 showwarning() 函數(shù)所用對象逐步填充（該函數(shù)還會抑制 sys.stdout 的輸出）。 列表中每個對象的屬性與 showwarning() 的參數(shù)名稱相同。

module 參數(shù)代表一個模塊，當導入 warnings 時，將被用于代替返回的模塊，其過濾器將被保護。該參數(shù)主要是為了測試 warnings 模塊自身。

If the action argument is not None, the remaining arguments are passed to simplefilter() as if it were called immediately on entering the context.

備注

catch_warnings 管理器的工作方式，是替換并隨后恢復模塊的 showwarning() 函數(shù)和內(nèi)部的過濾器種類列表。這意味著上下文管理器將會修改全局狀態(tài)，因此不是線程安全的。

在 3.11 版更改: Added the action, category, lineno, and append parameters.