warnings —— 警告信息的控制?

警告類別?

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

雖然在技術(shù)上警告類別屬于 內(nèi)置異常，但也只是在此記錄一下而已，因?yàn)樵诟拍钌纤麄儗儆诰鏅C(jī)制的一部分。

通過對(duì)某個(gè)標(biāo)準(zhǔn)的警告類別進(jìn)行派生，用戶代碼可以定義其他的警告類別。 警告類別必須是 Warning 類的子類。

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

警告過濾器?

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

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

• action 是以下字符串之一：

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

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

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

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

• lineno 是個(gè)整數(shù)，發(fā)生警告的行號(hào)必須與之匹配，或?yàn)?0 表示與所有行號(hào)匹配。

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

如果警告不匹配所有已注冊(cè)的過濾器，那就會(huì)應(yīng)用 “default” 動(dòng)作（正如其名）。

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í)禁止警告?

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

import warnings

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

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

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

測試警告?

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

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)因?yàn)?once / default 規(guī)則而被引發(fā)，那么無論設(shè)置什么過濾器，該條警告都不會(huì)再出現(xiàn)，除非該警告有關(guān)的注冊(cè)數(shù)據(jù)被清除。

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

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

為新版本的依賴關(guān)系更新代碼?

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

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

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

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

可用的函數(shù)?

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

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

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

這會(huì)讓警告指向 deprecation() 的調(diào)用者，而不是 deprecation() 本身的來源（因?yàn)楹笳邥?huì)破壞引發(fā)警告的目的）。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

在 警告過濾器種類 列表中插入一條簡單數(shù)據(jù)項(xiàng)。函數(shù)參數(shù)的含義與 filterwarnings() 相同，但不需要正則表達(dá)式，因?yàn)椴迦氲倪^濾器總是匹配任何模塊中的任何信息，只要類別和行號(hào)匹配即可。

warnings.resetwarnings()?

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

可用的上下文管理器?

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

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

module 參數(shù)代表一個(gè)模塊，當(dāng)導(dǎo)入 warnings 時(shí)，將被用于代替返回的模塊，其過濾器將被保護(hù)。該參數(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 管理器的工作方式，是替換并隨后恢復(fù)模塊的 showwarning() 函數(shù)和內(nèi)部的過濾器種類列表。這意味著上下文管理器將會(huì)修改全局狀態(tài)，因此不是線程安全的。

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