Python標準庫---1七、內置異常

上一篇文章： Python標準庫---1六、內置類型：上下文管理器類型、其餘、特殊屬性
下一篇文章：

在 Python 中，全部異常必須爲一個派生自 BaseException 的類的實例。 在帶有說起一個特定類的 except 子句的 try 語句中，該子句也會處理任何派生自該類的異常類（但不處理 它 所派生出的異常類）。 經過子類化建立的兩個不相關異常類永遠是不等效的，既使它們具備相同的名稱。

下面列出的內置異常可經過解釋器或內置函數來生成。除非另有說明，它們都會具備一個提示致使錯誤詳細緣由的「關聯值」。 這能夠是一個字符串或由多個信息項（例如一個錯誤碼和一個解釋錯誤的字符串）組成的元組。 關聯值一般會做爲參數被傳遞給異常類的構造器。

用戶代碼能夠引起內置異常。 這可被用於測試異常處理程序或報告錯誤條件，「就像」 在解釋器引起了相同異常的狀況時同樣；可是請注意，沒有任何機制能防止用戶代碼引起不適當的錯誤。

內置異常類能夠被子類化以定義新的異常；鼓勵程序員從 Exception 類或它的某個子類而不是從 BaseException 來派生新的異常。 關於定義異常的更多信息能夠在 Python 教程的 用戶自定義異常 部分查看。

當在 except 或 finally 子句中引起（或從新引起）異常時，__context__ 會被自動設爲所捕獲的最後一個異常；若是新的異常未被處理，則最終顯示的回溯信息將包括原始的異常和最後的異常。

當引起一個新的異常（而不是簡單地使用 raise 來從新引起當前在處理的異常）時，隱式的異常上下文能夠經過使用帶有 raise 的 from 來補充一個顯式的緣由:

raise new_exc from original_exc

跟在 from 以後的表達式必須爲一個異常或 None。 它將在所引起的異常上被設置爲 cause__。 設置 __cause 還會隱式地將 suppress_context 屬性設爲 True，這樣使用 raise new_exc from None 能夠有效地將舊異常替換爲新異常來顯示其目的 (例如將 KeyError 轉換爲 AttributeError)，同時讓舊異常在 context 中保持可用狀態以便在調試時進行內省。

除了異常自己的回溯之外，默認的回溯還會顯示這些串連的異常。 cause 中的顯式串連異常若是存在將老是顯示。 context 中的隱式串連異常僅在 cause 爲 None 而且 suppress_context 爲假值時顯示。

不論在哪一種狀況下，異常自己總會在任何串連異常以後顯示，以便回溯的最後一行老是顯示所引起的最後一個異常。

基類

下列異常主要被用做其餘異常的基類。

exception BaseException

全部內置異常的基類。 它不該該被用戶自定義類直接繼承 (這種狀況請使用 Exception)。 若是在此類的實例上調用 str()，則會返回實例的參數表示，或者當沒有參數時返回空字符串。

args

傳給異常構造器的參數元組。 某些內置異常 (例如 OSError) 接受特定數量的參數並賦予此元組中的元素特殊的含義，而其餘異常一般只接受一個給出錯誤信息的單獨字符串。

with_traceback(tb)

此方法將 tb 設爲異常的新回溯信息並返回該異常對象。 它一般以以下的形式在異常處理程序中使用:

try:
            ...
        except SomeException:
            tb = sys.exc_info()[2]
            raise OtherException(...).with_traceback(tb)

exception Exception

全部內置的非系統退出類異常都派生自此類。 全部用戶自定義異常也應當派生自此類。

exception ArithmeticError

此基類用於派生針對各類算術類錯誤而引起的內置異常: OverflowError, ZeroDivisionError, FloatingPointError。

exception BufferError

當與 緩衝區 相關的操做沒法執行時將被引起。

exception LookupError

此基類用於派生當映射或序列所使用的鍵或索引無效時引起的異常: IndexError, KeyError。 這能夠經過 codecs.lookup() 來直接引起。

具體異常

如下異常屬於常常被引起的異常。

exception AssertionError

當 assert 語句失敗時將被引起。

exception AttributeError

當屬性引用 (參見 屬性引用) 或賦值失敗時將被引起。 （當一個對象根本不支持屬性引用或屬性賦值時則將引起 TypeError。）

exception EOFError

當 input() 函數未讀取任何數據即達到文件結束條件 (EOF) 時將被引起。 （另外，io.IOBase.read() 和 io.IOBase.readline() 方法在遇到 EOF 則將返回一個空字符串。）

exception FloatingPointError

目前未被使用。

exception GeneratorExit

當一個 generator 或 coroutine 被關閉時將被引起；參見 generator.close() 和 coroutine.close()。 它直接繼承自 BaseException 而不是 Exception，由於從技術上來講它並非一個錯誤。

exception ImportError

當 import 語句嘗試加載模塊遇到麻煩時將被引起。 而且當 from ... import 中的 "from list" 存在沒法找到的名稱時也會被引起。

name 與 path 屬性可經過對構造器使用僅關鍵字參數來設定。 設定後它們將分別表示被嘗試導入的模塊名稱與觸發異常的任意文件所在路徑。

在 3.3 版更改: 添加了 name 與 path 屬性。

exception ModuleNotFoundError

ImportError 的子類，當一個模塊沒法被定位時將由 import 引起。 當在 sys.modules 中找到 None 時也會被引起。

3.6 新版功能.

exception IndexError

當序列抽取超出範圍時將被引起。 （切片索引會被靜默截短到容許的範圍；若是指定索引不是整數則 TypeError 會被引起。）

exception KeyError

當在現有鍵集合中找不到指定的映射（字典）鍵時將被引起。

exception KeyboardInterrupt

當用戶按下中斷鍵 (一般爲 Control-C 或 Delete) 時將被引起。 在執行期間，會按期檢測中斷信號。 該異常繼承自 BaseException 以確保不會被處理 Exception 的代碼意外捕獲，這樣能夠避免退出解釋器。

exception MemoryError

當一個操做耗盡內存但狀況仍可（經過刪除一些對象）進行挽救時將被引起。 關聯的值是一個字符串，指明是哪一種（內部）操做耗盡了內存。 請注意因爲底層的內存管理架構（C 的 malloc() 函數），解釋器也許並不老是可以從這種狀況下徹底恢復；但它畢竟能夠引起一個異常，這樣就能打印出棧回溯信息，以便找出致使問題的失控程序。

exception NameError

當某個局部或全局名稱未找到時將被引起。 此異常僅用於非限定名稱。 關聯的值是一條錯誤信息，其中包含未找到的名稱。

exception NotImplementedError

此異常派生自 RuntimeError。 在用戶自定義的基類中，抽象方法應當在其要求所派生類重載該方法，或是在其要求所開發的類提示具體實現尚待添加時引起此異常。

註解

它不該當用來表示一個運算符或方法根本不能被支持 -- 在此狀況下應當讓特定運算符 / 方法保持未定義，或者在子類中將其設爲 None。

註解

NotImplementedError 和 NotImplemented 不可互換，即便它們有類似的名稱和用途。 請參閱 NotImplemented 瞭解有關什麼時候使用它們的詳細說明。

exception OSError([arg])

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

此異常在一個系統函數返回系統相關的錯誤時將被引起，此類錯誤包括 I/O 操做失敗例如 "文件未找到" 或 "磁盤已滿" 等（不包括非法參數類型或其餘偶然性錯誤）。

構造器的第二種形式可設置以下所述的相應屬性。 若是未指定這些屬性則默認爲 None。 爲了能向下兼容，若是傳入了三個參數，則 args 屬性將僅包含由前兩個構造器參數組成的 2 元組。

構造器實際返回的每每是 OSError 的某個子類，以下文 OS exceptions 中所描述的。 具體的子類取決於最終的 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 RecursionError

此異常派生自 RuntimeError。 它會在解釋器檢測發現超過最大遞歸深度 (參見 sys.getrecursionlimit()) 時被引起。

3.5 新版功能: 在此以前將只引起 RuntimeError。

exception ReferenceError

此異常將在使用 weakref.proxy() 函數所建立的弱引用來訪問該引用的某個已被做爲垃圾回收的屬性時被引起。 有關弱引用的更多信息請參閱 weakref 模塊。

exception RuntimeError

當檢測到一個不歸屬於任何其餘類別的錯誤時將被引起。 關聯的值是一個指明究竟發生了什麼問題的字符串。

exception StopIteration

由內置函數 next() 和 iterator 的 __next__() 方法所引起，用來表示該迭代器不能產生下一項。

該異常對象只有一個屬性 value，它在構造該異常時做爲參數給出，默認值爲 None。

當一個 generator 或 coroutine 函數返回時，將引起一個新的 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

必須由一個 asynchronous iterator 對象的 __anext__() 方法來引起以中止迭代操做。

3.5 新版功能.

exception SyntaxError

當解析器遇到語法錯誤時將被引起。 這能夠發生在 import 語句，對內置函數 exec() 或 eval() 的調用，或者讀取原始腳本或標準輸入（也包括交互模式）的時候。

該類的實例包含有屬性 filename, lineno, offset 和 text 用於方便地訪問相應的詳細信息。 異常實例的 str() 僅返回消息文本。

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，則退出狀態碼爲零；若是該值爲其餘類型（例如字符串），則會打印對象的值並將退出狀態碼設爲一。

對 sys.exit() 的調用會被轉換爲一個異常以便能執行清理處理程序 (try 語句的 finally 子句)，而且使得調試器能夠執行一段腳本而沒必要冒失去控制的風險。 若是絕對確實地須要當即退出（例如在調用 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()) 時將被引起。 對應於 errno ENOTDIR。

exception PermissionError

當在沒有足夠操做權限的狀況下試圖執行某個操做時將被引起 —— 例如缺乏文件系統權限。 對應於 errno EACCES 和 EPERM。

exception ProcessLookupError

當給定的進程不存在時將被引起。 對應於 errno ESRCH。

exception TimeoutError

當一個系統函數發生系統級超時的狀況下將被引起。 對應於 errno ETIMEDOUT。

3.3 新版功能: 添加了以上全部 OSError 的子類。

參見

PEP 3151 - 重寫 OS 和 IO 異常的層次結構

警告

下列異常被用做警告類別；請參閱 警告類別 文檔瞭解詳情。

exception Warning

警告類別的基類。

exception UserWarning

用戶代碼所產生警告的基類。

exception DeprecationWarning

若是所發出的警告是針對其餘 Python 開發者的，則以此做爲與已棄用特性相關警告的基類。

exception PendingDeprecationWarning

對於已過期並預計在將來棄用，但目前還沒有棄用的特性相關警告的基類。

這個類不多被使用，由於針對將來可能的棄用發出警告的作法並不常見，而針對當前已有的棄用則推薦使用 DeprecationWarning。

exception SyntaxWarning

與模糊的語法相關的警告的基類。

exception RuntimeWarning

與模糊的運行時行爲相關的警告的基類。

exception FutureWarning

若是所發出的警告是針對以 Python 所編寫應用的最終用戶的，則以此做爲與已棄用特性相關警告的基類。

exception ImportWarning

與在模塊導入中可能的錯誤相關的警告的基類。

exception UnicodeWarning

與 Unicode 相關的警告的基類。

exception BytesWarning

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

exception ResourceWarning

與資源使用相關的警告的基類。 會被默認的警告過濾器忽略。

3.2 新版功能.

異常層次結構

內置異常的類層級結構以下：