內建異常

在 Python 中，所有異常都必須是派生自 BaseException 的類的例項。在帶有提及特定類的 try 語句的 except 子句中，該子句也處理從該類派生的任何異常類（但不處理它派生的異常類）。即使兩個異常類具有相同的名稱，如果它們不是透過子類化關聯的，則它們永遠不等價。

本章列出的內建異常可以由直譯器或內建函式生成。除非另有說明，否則它們都具有指示錯誤詳細原因的“關聯值”。這可以是字串或多個資訊項的元組（例如，錯誤程式碼和解釋程式碼的字串）。關聯值通常作為引數傳遞給異常類的建構函式。

使用者程式碼可以引發內建異常。這可以用於測試異常處理程式或報告錯誤情況，就像直譯器引發相同異常的情況一樣；但請注意，沒有什麼可以阻止使用者程式碼引發不適當的錯誤。

內建異常類可以被子類化以定義新的異常；鼓勵程式設計師從 Exception 類或其子類之一派生新的異常，而不是從 BaseException 派生。有關定義異常的更多資訊，請參閱 Python 教程中的 使用者定義的異常。

異常上下文

異常物件的三個屬性提供了有關引發異常的上下文的資訊

BaseException.__context__

BaseException.__cause__

BaseException.__suppress_context__

當在處理另一個異常時引發新異常時，新異常的 __context__ 屬性會自動設定為處理的異常。當使用 except 或 finally 子句或 with 語句時，可能會處理異常。

透過使用帶有 raise 的 from，可以顯式原因來補充此隱式異常上下文

raise new_exc from original_exc

以下 from 的表示式必須是異常或 None。它將被設定為所引發異常的 __cause__。設定 __cause__ 還會隱式地將 __suppress_context__ 屬性設定為 True，因此使用 raise new_exc from None 可以有效地替換顯示目的的舊異常（例如，將 KeyError 轉換為 AttributeError），同時保留舊異常在 __context__ 中以便在除錯時進行內省。

預設的回溯顯示程式碼會在異常本身的回溯之外顯示這些鏈式異常。當存在時，始終顯示 __cause__ 中的顯式連結異常。僅當 __cause__ 為 None 且 __suppress_context__ 為 false 時，才顯示 __context__ 中的隱式連結異常。

在任何一種情況下，異常本身始終在任何鏈式異常之後顯示，以便回溯的最後一行始終顯示引發的最後一個異常。

從內建異常繼承

使用者程式碼可以建立從異常型別繼承的子類。建議一次只子類化一個異常型別，以避免基類如何處理 args 屬性之間的任何可能的衝突，以及由於可能的記憶體佈局不相容性。

CPython 實現細節： 為了提高效率，大多數內建異常是在 C 中實現的，請參閱：Objects/exceptions.c。某些異常具有自定義記憶體佈局，這使得無法建立從多個異常型別繼承的子類。型別的記憶體佈局是實現細節，可能會在 Python 版本之間發生變化，從而導致未來出現新的衝突。因此，建議完全避免子類化多個異常型別。

基類

以下異常主要用作其他異常的基類。

exception BaseException

所有內建異常的基類。它不是要由使用者定義的類直接繼承（為此，請使用 Exception）。如果在此類的例項上呼叫 str()，則返回例項引數的表示形式，如果沒有引數，則返回空字串。

args

傳遞給異常建構函式的引數的元組。某些內建異常（如 OSError）期望一定數量的引數，併為該元組的元素分配特殊含義，而其他異常通常僅使用給出錯誤訊息的單個字串呼叫。

with_traceback(tb)

此方法將tb設定為異常的新回溯，並返回異常物件。在PEP 3134的異常鏈特性可用之前，此方法更為常用。下面的例子展示瞭如何在保留回溯的同時將 SomeException 的例項轉換為 OtherException 的例項。一旦引發，當前幀會被推送到 OtherException 的回溯中，就像我們允許原始 SomeException 傳播到呼叫者時所發生的回溯一樣。

try:
    ...
except SomeException:
    tb = sys.exception().__traceback__
    raise OtherException(...).with_traceback(tb)

__traceback__

一個可寫欄位，用於儲存與此異常關聯的回溯物件。另請參閱：raise 語句。

add_note(note)

將字串 note 新增到異常的註釋中，這些註釋出現在異常字串後的標準回溯中。如果 note 不是字串，則引發 TypeError。

在 3.11 版本中新增。

__notes__

此異常的註釋列表，這些註釋是透過 add_note() 新增的。此屬性在呼叫 add_note() 時建立。

在 3.11 版本中新增。

exception Exception

所有內建的、非系統退出的異常都派生自此類。所有使用者定義的異常也應派生自此類。

exception ArithmeticError

為各種算術錯誤引發的那些內建異常的基類：OverflowError、ZeroDivisionError、FloatingPointError。

exception BufferError

當無法執行與 緩衝區 相關的操作時引發。

exception LookupError

當在對映或序列上使用的鍵或索引無效時引發的異常的基類：IndexError、KeyError。可以透過 codecs.lookup() 直接引發。

具體異常

以下異常是通常引發的異常。

exception AssertionError

當 assert 語句失敗時引發。

exception AttributeError

當屬性引用（參見 屬性引用）或賦值失敗時引發。（當一個物件完全不支援屬性引用或屬性賦值時，會引發 TypeError。）

可以使用建構函式的僅關鍵字引數設定 name 和 obj 屬性。當設定它們時，它們分別表示嘗試訪問的屬性的名稱和訪問該屬性的物件。

在 3.10 版本中更改: 添加了 name 和 obj 屬性。

exception EOFError

當 input() 函式在未讀取任何資料的情況下遇到檔案結束條件 (EOF) 時引發。（注意：io.IOBase.read() 和 io.IOBase.readline() 方法在遇到 EOF 時返回一個空字串。）

exception FloatingPointError

目前未使用。

exception GeneratorExit

當生成器或協程被關閉時引發；請參閱generator.close()和coroutine.close()。它直接繼承自BaseException而不是Exception，因為它在技術上不是錯誤。

exception ImportError

當 import 語句在嘗試載入模組時遇到問題時引發。當 from ... import 中的 “from list” 中存在找不到的名稱時也會引發。

可選的 name 和 path 僅關鍵字引數設定相應的屬性

name

嘗試匯入的模組的名稱。

path

觸發異常的任何檔案的路徑。

在 3.3 版本中更改: 添加了 name 和 path 屬性。

exception ModuleNotFoundError

當找不到模組時，import 引發的 ImportError 的子類。當在 sys.modules 中找到 None 時也會引發。

在 3.6 版本中新增。

exception IndexError

當序列下標超出範圍時引發。（切片索引會被靜默地截斷以落在允許的範圍內；如果索引不是整數，則會引發 TypeError。）

exception KeyError

當在現有鍵的集合中找不到對映（字典）鍵時引發。

exception KeyboardInterrupt

當用戶按下中斷鍵（通常是 Control-C 或 Delete）時引發。在執行期間，會定期檢查中斷。該異常繼承自 BaseException，以便不會被捕獲 Exception 的程式碼意外捕獲，從而阻止直譯器退出。

注意

捕獲 KeyboardInterrupt 需要特別注意。因為它可能在不可預測的點引發，因此在某些情況下，它可能會使正在執行的程式處於不一致的狀態。通常最好允許 KeyboardInterrupt 儘快結束程式，或者完全避免引發它。（請參閱 關於訊號處理程式和異常的說明。）

exception MemoryError

當操作耗盡記憶體但情況仍然可以挽救（透過刪除某些物件）時引發。關聯的值是一個字串，指示哪種（內部）操作耗盡了記憶體。請注意，由於底層記憶體管理架構（C 的 malloc() 函式），直譯器可能並不總是能夠完全從此情況中恢復；但是，它仍然會引發異常，以便可以列印堆疊回溯，以防執行時程式是原因。

exception NameError

當找不到區域性或全域性名稱時引發。這僅適用於不限定的名稱。關聯的值是一條錯誤訊息，其中包括無法找到的名稱。

可以使用僅關鍵字引數來設定建構函式的 name 屬性。設定後，它表示嘗試訪問的變數的名稱。

3.10 版本更改: 添加了 name 屬性。

exception NotImplementedError

此異常派生自 RuntimeError。在使用者定義的基類中，當抽象方法需要派生類覆蓋該方法時，或者在開發類以指示仍需要新增真實實現時，應引發此異常。

注意

它不應用於指示根本不支援運算子或方法——在這種情況下，要麼使運算子/方法未定義，要麼在子類中將其設定為 None。

注意

NotImplementedError 和 NotImplemented 不可互換，即使它們的名稱和目的相似。有關何時使用它的詳細資訊，請參閱 NotImplemented。

exception OSError([arg])

exception OSError(errno, strerror[, filename[, winerror[, filename2]]])

當系統函式返回系統相關錯誤時引發此異常，包括 I/O 故障，例如“找不到檔案”或“磁碟已滿”（不包括非法引數型別或其他意外錯誤）。

建構函式的第二種形式設定下面描述的相應屬性。如果未指定，則這些屬性預設為 None。為了向後相容，如果傳遞了三個引數，則 args 屬性僅包含前兩個建構函式引數的 2 元組。

建構函式通常實際上返回 OSError 的子類，如下面的 OS 異常中所述。特定的子類取決於最終的 errno 值。僅當直接或透過別名構造 OSError 時才會發生此行為，並且在子類化時不會繼承此行為。

errno

來自 C 變數 errno 的數字錯誤程式碼。

winerror

在 Windows 下，這為您提供了本機 Windows 錯誤程式碼。errno 屬性然後是以 POSIX 術語表示的該本機錯誤程式碼的近似轉換。

在 Windows 下，如果 *winerror* 建構函式引數是整數，則 errno 屬性由 Windows 錯誤程式碼確定，並忽略 *errno* 引數。在其他平臺上，將忽略 *winerror* 引數，並且 winerror 屬性不存在。

strerror

作業系統提供的相應錯誤訊息。它由 POSIX 下的 C 函式 perror() 和 Windows 下的 FormatMessage() 格式化。

filename

filename2

對於涉及檔案系統路徑的異常（例如 open() 或 os.unlink()），filename 是傳遞給該函式的檔名。對於涉及兩個檔案系統路徑的函式（例如 os.rename()），filename2 對應於傳遞給該函式的第二個檔名。

3.3 版本更改: EnvironmentError、IOError、WindowsError、socket.error、select.error 和 mmap.error 已合併到 OSError 中，並且建構函式可能返回子類。

3.4 版本更改: filename 屬性現在是傳遞給函式的原始檔名，而不是編碼為或從 檔案系統編碼和錯誤處理程式 解碼的名稱。此外，還添加了 *filename2* 建構函式引數和屬性。

exception OverflowError

當算術運算的結果太大而無法表示時引發。這不會發生在整數上（整數會引發 MemoryError 而不是放棄）。但是，出於歷史原因，有時會為超出所需範圍的整數引發 OverflowError。由於 C 中浮點異常處理缺乏標準化，因此大多數浮點運算都不會進行檢查。

exception PythonFinalizationError

此異常派生自 RuntimeError。當在直譯器關閉期間（也稱為Python 最終化）操作被阻塞時，會引發此異常。

以下是一些在 Python 最終化期間可能被 PythonFinalizationError 阻塞的操作示例：

• 建立新的 Python 執行緒。

• os.fork().

另請參閱 sys.is_finalizing() 函式。

3.13 版本新增: 此前，會引發一個普通的 RuntimeError。

exception RecursionError

此異常派生自 RuntimeError。當直譯器檢測到超過最大遞迴深度（請參閱 sys.getrecursionlimit()）時，會引發此異常。

3.5 版本新增: 此前，會引發一個普通的 RuntimeError。

exception ReferenceError

當使用 weakref.proxy() 函式建立的弱引用代理，在被引用物件被垃圾回收之後，嘗試訪問該物件的屬性時，會引發此異常。有關弱引用的更多資訊，請參閱 weakref 模組。

exception RuntimeError

當檢測到不屬於任何其他類別的錯誤時，會引發此異常。關聯的值是一個字串，指示具體出了什麼問題。

exception StopIteration

內建函式 next() 和迭代器的 __next__() 方法會引發此異常，以表示迭代器不再產生任何項。

value

異常物件有一個屬性 value，它在構造異常時作為引數給出，預設為 None。

當生成器或協程函式返回時，會引發一個新的 StopIteration 例項，並且該函式返回的值將用作異常建構函式的 value 引數。

如果生成器程式碼直接或間接地引發 StopIteration，它將被轉換為 RuntimeError（保留 StopIteration 作為新異常的原因）。

在 3.3 版本中變更: 添加了 value 屬性，並使生成器函式可以使用它來返回值。

在 3.5 版本中變更: 透過 from __future__ import generator_stop 引入了 RuntimeError 轉換，請參閱 PEP 479。

在 3.7 版本中變更: 預設情況下為所有程式碼啟用 PEP 479：在生成器中引發的 StopIteration 錯誤會被轉換為 RuntimeError。

exception StopAsyncIteration

__anext__() 方法必須由非同步迭代器物件引發，以停止迭代。

3.5 版本新增。

exception SyntaxError(message, details)

當解析器遇到語法錯誤時，會引發此異常。這可能發生在 import 語句中，在呼叫內建函式 compile()、exec() 或 eval() 時，或者在讀取初始指令碼或標準輸入時（也包括互動式）。

異常例項的 str() 僅返回錯誤訊息。詳細資訊是一個元組，其成員也可以作為單獨的屬性訪問。

filename

發生語法錯誤的檔名。

lineno

檔案中發生錯誤的行號。這是從 1 開始的索引：檔案中的第一行具有 lineno 為 1。

offset

錯誤發生在該行中的列。這是從 1 開始的索引：該行的第一個字元的 offset 為 1。

text

錯誤中涉及的原始碼文字。

end_lineno

檔案中錯誤結束的行號。這是從 1 開始的索引：檔案中的第一行具有 lineno 為 1。

end_offset

錯誤結束的行中的列。這是從 1 開始的索引：該行的第一個字元的 offset 為 1。

對於 f 字串欄位中的錯誤，訊息會以 “f-string: ” 為字首，並且偏移量是根據替換表示式構造的文字中的偏移量。例如，編譯 f’Bad {a b} field’ 會產生以下 args 屬性：(‘f-string: …’, (‘’, 1, 2, ‘(a b)n’, 1, 5))。

在 3.10 版本中變更: 添加了 end_lineno 和 end_offset 屬性。

exception IndentationError

與不正確的縮排相關的語法錯誤的基類。它是 SyntaxError 的子類。

exception TabError

當縮排包含製表符和空格的不一致使用時，會引發此異常。它是 IndentationError 的子類。

exception SystemError

當直譯器發現內部錯誤，但情況看起來並不嚴重到導致它放棄所有希望時，會引發此異常。關聯的值是一個字串，指示出了什麼問題（以低階術語）。

你應該將此情況報告給你的 Python 直譯器的作者或維護者。請務必報告 Python 直譯器的版本（sys.version；它也會在互動式 Python 會話開始時列印），確切的錯誤訊息（異常的關聯值），如果可能，還要報告觸發錯誤的程式原始碼。

exception SystemExit

此異常由 sys.exit() 函式引發。它繼承自 BaseException 而不是 Exception，這樣它就不會被捕獲 Exception 的程式碼意外捕獲。這允許異常正確地向上傳播並導致直譯器退出。當它未被處理時，Python 直譯器會退出；不會列印堆疊回溯。建構函式接受傳遞給 sys.exit() 的相同的可選引數。如果值是一個整數，它指定系統退出狀態（傳遞給 C 的 exit() 函式）；如果值為 None，則退出狀態為零；如果它具有其他型別（例如字串），則列印物件的值，退出狀態為 1。

對 sys.exit() 的呼叫被轉換為異常，以便可以執行清理處理程式（finally 子句，在 try 語句中），並且偵錯程式可以執行指令碼而不會有失去控制的風險。如果絕對有必要立即退出（例如，在呼叫 os.fork() 之後在子程序中），可以使用 os._exit() 函式。

code

傳遞給建構函式的退出狀態或錯誤訊息。（預設為 None。）

exception TypeError

當操作或函式應用於不適當型別的物件時引發。關聯的值是一個字串，提供了有關型別不匹配的詳細資訊。

使用者程式碼可以引發此異常，以指示嘗試對物件進行的操作不受支援，並且不打算支援。如果一個物件打算支援給定的操作但尚未提供實現，則應該引發 NotImplementedError 異常。

傳遞錯誤型別的引數（例如，當期望一個 int 時傳遞一個 list）應該導致 TypeError，但是傳遞錯誤值的引數（例如，超出預期範圍的數字）應該導致 ValueError。

exception UnboundLocalError

當在函式或方法中引用區域性變數，但該變數沒有繫結值時引發。這是 NameError 的子類。

exception UnicodeError

當發生與 Unicode 相關的編碼或解碼錯誤時引發。它是 ValueError 的子類。

UnicodeError 具有描述編碼或解碼錯誤的屬性。例如，err.object[err.start:err.end] 給出編解碼器失敗的特定無效輸入。

encoding

引發錯誤的編碼名稱。

reason

描述特定編解碼器錯誤的字串。

object

編解碼器嘗試編碼或解碼的物件。

start

object 中無效資料的第一個索引。

end

object 中最後一個無效資料之後的索引。

exception UnicodeEncodeError

當編碼期間發生與 Unicode 相關的錯誤時引發。它是 UnicodeError 的子類。

exception UnicodeDecodeError

當解碼期間發生與 Unicode 相關的錯誤時引發。它是 UnicodeError 的子類。

exception UnicodeTranslateError

當轉換期間發生與 Unicode 相關的錯誤時引發。它是 UnicodeError 的子類。

exception ValueError

當操作或函式接收到型別正確但值不適當的引數時引發，並且這種情況不能用更精確的異常（例如 IndexError）來描述。

exception ZeroDivisionError

當除法或取模運算的第二個引數為零時引發。關聯的值是一個字串，指示運算元和運算的型別。

以下異常是為了與以前的版本相容而保留的；從 Python 3.3 開始，它們是 OSError 的別名。

exception EnvironmentError

exception IOError

exception WindowsError

僅在 Windows 上可用。

OS 異常

以下異常是 OSError 的子類，它們會根據系統錯誤程式碼引發。

exception BlockingIOError

當在設定為非阻塞操作的物件（例如，套接字）上進行操作會導致阻塞時引發。對應於 errno EAGAIN、EALREADY、EWOULDBLOCK 和 EINPROGRESS。

除了 OSError 的屬性之外，BlockingIOError 還可以有一個附加屬性

characters_written

一個整數，包含在流阻塞之前寫入流的字元數。 當使用來自 io 模組的緩衝 I/O 類時，此屬性可用。

exception ChildProcessError

當對子程序的操作失敗時引發。 對應於 errno ECHILD。

exception ConnectionError

與連線相關問題的基類。

子類包括 BrokenPipeError, ConnectionAbortedError, ConnectionRefusedError 和 ConnectionResetError。

exception BrokenPipeError

ConnectionError 的子類，當嘗試寫入管道而另一端已關閉時，或嘗試寫入已關閉寫入的套接字時引發。對應於 errno EPIPE 和 ESHUTDOWN。

exception ConnectionAbortedError

ConnectionError 的子類，當連線嘗試被對等方中止時引發。 對應於 errno ECONNABORTED。

exception ConnectionRefusedError

ConnectionError 的子類，當連線嘗試被對等方拒絕時引發。 對應於 errno ECONNREFUSED。

exception ConnectionResetError

ConnectionError 的子類，當連線被對等方重置時引發。 對應於 errno ECONNRESET。

exception FileExistsError

當嘗試建立已存在的檔案或目錄時引發。 對應於 errno EEXIST。

exception FileNotFoundError

當請求檔案或目錄但不存在時引發。 對應於 errno ENOENT。

exception InterruptedError

當系統呼叫被傳入訊號中斷時引發。 對應於 errno EINTR。

在 3.5 版本中更改: Python 現在會在系統呼叫被訊號中斷時重試系統呼叫，除非訊號處理程式引發異常 (請參閱 PEP 475 瞭解原因)，而不是引發 InterruptedError。

exception IsADirectoryError

當對目錄請求檔案操作（例如 os.remove()）時引發。 對應於 errno EISDIR。

exception NotADirectoryError

當對不是目錄的內容請求目錄操作（例如 os.listdir()）時引發。 在大多數 POSIX 平臺上，如果操作嘗試將非目錄檔案作為目錄開啟或遍歷，也可能會引發此錯誤。 對應於 errno ENOTDIR。

exception PermissionError

當嘗試在沒有足夠訪問許可權的情況下執行操作時引發，例如檔案系統許可權。 對應於 errno EACCES、EPERM 和 ENOTCAPABLE。

在 3.11.1 版本中更改: WASI 的 ENOTCAPABLE 現在對映到 PermissionError。

exception ProcessLookupError

當給定的程序不存在時引發。 對應於 errno ESRCH。

exception TimeoutError

當系統函式在系統級別超時時引發。 對應於 errno ETIMEDOUT。

在 3.3 版本中新增: 添加了以上所有 OSError 子類。

參見

PEP 3151 - 重新設計 OS 和 IO 異常層次結構

警告

以下異常用作警告類別；請參閱 警告類別 文件以瞭解更多詳細資訊。

exception Warning

警告類別的基類。

exception UserWarning

使用者程式碼生成的警告的基類。

exception DeprecationWarning

關於已棄用功能的警告的基類，這些警告旨在供其他 Python 開發人員使用。

預設警告過濾器會忽略此警告，除非在 __main__ 模組中（PEP 565）。啟用Python 開發模式會顯示此警告。

棄用策略在 PEP 387 中描述。

exception PendingDeprecationWarning

用於警告那些過時且預計將來會被棄用，但目前尚未棄用的功能的基類。

這個類很少使用，因為發出關於將來可能棄用的警告是不尋常的，並且對於已經處於活動狀態的棄用，首選DeprecationWarning。

預設警告過濾器會忽略此警告。啟用Python 開發模式會顯示此警告。

棄用策略在 PEP 387 中描述。

exception SyntaxWarning

用於警告可疑語法的基類。

exception RuntimeWarning

用於警告可疑執行時行為的基類。

exception FutureWarning

用於警告已棄用功能的基類，當這些警告的目標是使用 Python 編寫的應用程式的終端使用者時。

exception ImportWarning

用於警告模組匯入中可能錯誤的基類。

預設警告過濾器會忽略此警告。啟用Python 開發模式會顯示此警告。

exception UnicodeWarning

用於警告與 Unicode 相關的基類。

exception EncodingWarning

用於警告與編碼相關的基類。

有關詳細資訊，請參閱選擇加入 EncodingWarning。

在版本 3.10 中新增。

exception BytesWarning

用於警告與 bytes 和 bytearray 相關的基類。

exception ResourceWarning

用於警告與資源使用相關的基類。

預設警告過濾器會忽略此警告。啟用Python 開發模式會顯示此警告。

在版本 3.2 中新增。

異常組

以下異常組用於需要引發多個不相關異常的情況。它們是異常層次結構的一部分，因此可以像所有其他異常一樣使用 except 進行處理。此外，except* 可以識別它們，該語句根據包含的異常型別匹配其子組。

exception ExceptionGroup(msg, excs)

exception BaseExceptionGroup(msg, excs)

這兩種異常型別都包裝了序列 excs 中的異常。msg 引數必須是字串。這兩個類之間的區別在於，BaseExceptionGroup 繼承自 BaseException，它可以包裝任何異常，而 ExceptionGroup 繼承自 Exception，它只能包裝 Exception 的子類。這種設計是為了使 except Exception 捕獲 ExceptionGroup，但不捕獲 BaseExceptionGroup。

如果所有包含的異常都是 Exception 的例項，則 BaseExceptionGroup 建構函式返回一個 ExceptionGroup 而不是 BaseExceptionGroup，因此它可以用於使選擇自動化。另一方面，如果任何包含的異常不是 Exception 的子類，則 ExceptionGroup 建構函式會引發 TypeError。

message

建構函式的 msg 引數。這是一個只讀屬性。

exceptions

傳遞給建構函式的 excs 序列中異常的元組。這是一個只讀屬性。

subgroup(condition)

返回一個異常組，其中僅包含當前組中與 *condition* 匹配的異常，如果結果為空，則返回 None。

條件可以是異常型別或異常型別元組，在這種情況下，將使用 except 子句中使用的相同檢查來檢查每個異常是否匹配。條件也可以是可呼叫物件（型別物件除外），它接受一個異常作為其單個引數，併為應該在子組中的異常返回 true。

當前異常的巢狀結構將保留在結果中，其 message、__traceback__、__cause__、__context__ 和 __notes__ 欄位的值也將保留。結果中將省略空的巢狀組。

將檢查巢狀異常組（包括頂層和任何巢狀異常組）中的所有異常的條件。如果條件對於這樣的異常組為 true，則將其完整地包含在結果中。

在 3.13 版本中新增: condition 可以是任何不是型別物件的可呼叫物件。

split(condition)

與 subgroup() 類似，但返回對 (match, rest)，其中 match 為 subgroup(condition)，而 rest 為剩餘的不匹配部分。

derive(excs)

返回一個具有相同 message 的異常組，但包裝了 excs 中的異常。

此方法由 subgroup() 和 split() 使用，它們在各種上下文中使用以分解異常組。子類需要覆蓋它，以使 subgroup() 和 split() 返回子類的例項而不是 ExceptionGroup 的例項。

subgroup() 和 split() 會將 __traceback__, __cause__, __context__ 和 __notes__ 欄位從原始異常組複製到由 derive() 返回的異常組，因此這些欄位不需要由 derive() 更新。

>>> class MyGroup(ExceptionGroup):
...     def derive(self, excs):
...         return MyGroup(self.message, excs)
...
>>> e = MyGroup("eg", [ValueError(1), TypeError(2)])
>>> e.add_note("a note")
>>> e.__context__ = Exception("context")
>>> e.__cause__ = Exception("cause")
>>> try:
...    raise e
... except Exception as e:
...    exc = e
...
>>> match, rest = exc.split(ValueError)
>>> exc, exc.__context__, exc.__cause__, exc.__notes__
(MyGroup('eg', [ValueError(1), TypeError(2)]), Exception('context'), Exception('cause'), ['a note'])
>>> match, match.__context__, match.__cause__, match.__notes__
(MyGroup('eg', [ValueError(1)]), Exception('context'), Exception('cause'), ['a note'])
>>> rest, rest.__context__, rest.__cause__, rest.__notes__
(MyGroup('eg', [TypeError(2)]), Exception('context'), Exception('cause'), ['a note'])
>>> exc.__traceback__ is match.__traceback__ is rest.__traceback__
True

請注意，BaseExceptionGroup 定義了 __new__()，因此需要不同建構函式簽名的子類需要重寫該方法，而不是 __init__()。 例如，以下程式碼定義了一個接受 exit_code 並從中構造組訊息的異常組子類。

class Errors(ExceptionGroup):
   def __new__(cls, errors, exit_code):
      self = super().__new__(Errors, f"exit code: {exit_code}", errors)
      self.exit_code = exit_code
      return self

   def derive(self, excs):
      return Errors(excs, self.exit_code)

與 ExceptionGroup 類似，任何也是 Exception 子類的 BaseExceptionGroup 子類，只能包裝 Exception 的例項。

在 3.11 版本中新增。

異常層級結構

內建異常的類層級結構是

BaseException
 ├── BaseExceptionGroup
 ├── GeneratorExit
 ├── KeyboardInterrupt
 ├── SystemExit
 └── Exception
      ├── ArithmeticError
      │    ├── FloatingPointError
      │    ├── OverflowError
      │    └── ZeroDivisionError
      ├── AssertionError
      ├── AttributeError
      ├── BufferError
      ├── EOFError
      ├── ExceptionGroup [BaseExceptionGroup]
      ├── ImportError
      │    └── ModuleNotFoundError
      ├── LookupError
      │    ├── IndexError
      │    └── KeyError
      ├── MemoryError
      ├── NameError
      │    └── UnboundLocalError
      ├── OSError
      │    ├── BlockingIOError
      │    ├── ChildProcessError
      │    ├── ConnectionError
      │    │    ├── BrokenPipeError
      │    │    ├── ConnectionAbortedError
      │    │    ├── ConnectionRefusedError
      │    │    └── ConnectionResetError
      │    ├── FileExistsError
      │    ├── FileNotFoundError
      │    ├── InterruptedError
      │    ├── IsADirectoryError
      │    ├── NotADirectoryError
      │    ├── PermissionError
      │    ├── ProcessLookupError
      │    └── TimeoutError
      ├── ReferenceError
      ├── RuntimeError
      │    ├── NotImplementedError
      │    ├── PythonFinalizationError
      │    └── RecursionError
      ├── StopAsyncIteration
      ├── StopIteration
      ├── SyntaxError
      │    └── IndentationError
      │         └── TabError
      ├── SystemError
      ├── TypeError
      ├── ValueError
      │    └── UnicodeError
      │         ├── UnicodeDecodeError
      │         ├── UnicodeEncodeError
      │         └── UnicodeTranslateError
      └── Warning
           ├── BytesWarning
           ├── DeprecationWarning
           ├── EncodingWarning
           ├── FutureWarning
           ├── ImportWarning
           ├── PendingDeprecationWarning
           ├── ResourceWarning
           ├── RuntimeWarning
           ├── SyntaxWarning
           ├── UnicodeWarning
           └── UserWarning