5. 組み込み例外

Python において、すべての例外は BaseException から派生したクラスのインスタンスでなければなりません。特定のクラスを挙げた except 節を伴う try 文において、その節は挙げられたクラスから派生したクラスも処理します (が、派生 の例外クラスは処理されません)。サブクラス化の関係にない 2 つの例外クラスは、それらが同じ名前だったとしてさえ等しくなりえません。

以下に挙げる組み込み例外は、インタプリタや組み込み関数によって生成されます。特に注記しないかぎり、これらはエラーの詳しい原因を示す “関連値 (associated value)” を持ちます。この値は、文字列か複数の情報 (例えば、エラーコードやそのコードを説明する文字列) のタプルかです。この関連値は、通常、例外クラスのコンストラクタに引数として渡されます。

ユーザによるコードも組み込み例外を送出できます。これを使って、例外ハンドラをテストしたり、インタプリタが同じ例外を送出する状況と “ちょうど同じような” エラー条件であることを報告したりできます。しかし、ユーザのコードが適切でないエラーを送出するのを妨げる方法はないので注意してください。

組み込み例外クラスをサブクラス化して新たな例外を定義できます。新しい例外は、BaseException ではなく少なくとも Exception クラスから派生することをお勧めします。例外の定義について詳しくは、 Python チュートリアルの ユーザー定義例外 の項目にあります。

except 節内で例外を送出 (または再送出) するとき、__context__ は自動的に最後に捕まった例外に設定されます。新しい例外が処理されなければ、最終的に表示されるトレースバックは先に起きた例外も最後の例外も含みます。

現在処理中の例外を raise を使って再送出するのではなく新規に例外を送出する場合、raise と一緒に from を使うことで暗黙の例外コンテキストを補足することができます。

raise new_exc from original_exc

from に続く式 (expression) は例外か None でなくてはなりません。式は送出される例外の __cause__ として設定されます。 __cause__ を設定することは、 __suppress_context__ 属性を True にすることも意味するので、 raise new_exc from None を使うことで効率的に古い例外を新しいもので置き換えて表示する (たとえば KeyErrorAttributeError に置き換え、古い例外はデバッグ時の調査で使えるよう __context__ に残す) ことができます。

デフォルトの traceback 表示コードは、例外自体の traceback に加え、これらの連鎖された例外を表示します。__cause__ で明示的に連鎖させた例外は、存在するならば常に表示されます。__context__ で暗黙に連鎖させた例外は、__cause__None かつ __suppress_context__ が false の場合にのみ表示されます。

いずれにせよ、連鎖された例外に続いて、その例外自体は常に表示されます。そのため、traceback の最終行には、常に送出された最後の例外が表示されます。

5.1. 基底クラス

以下の例外は、主に他の例外の基底クラスとして使われます。

exception BaseException

全ての組み込み例外の基底クラスです。このクラスはユーザ定義例外に直接を継承されることを意図していません (継承するなら、Exception を使ってください)。このクラスのインスタンスに str() が呼ばれた場合、インスタンスへの引数の表現か、引数が無かったら空文字列が返されます。

args

例外コンストラクタに与えられた引数のタプルです。組み込み例外は普通、エラーメッセージを与える一つの文字列だけを引数として呼ばれますが、中には (IOError など) いくつかの引数を必要とし、このタプルの要素に特別な意味を込めるものもあります。

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

バッファ (buffer) に関連する演算が行えなかったときに送出されます。

exception LookupError

マッピングまたはシーケンスで使われたキーやインデクスが無効な場合に送出される例外 IndexError および KeyError の基底クラスです。 codecs.lookup() によって直接送出されることもあります。

5.2. 具体的な例外

以下の例外は、通常送出される例外です。

exception AssertionError

assert 文が失敗した場合に送出されます。

exception AttributeError

属性参照 (属性参照 を参照) や代入が失敗した場合に送出されます (オブジェクトが属性の参照や属性の代入をまったくサポートしていない場合には TypeError が送出されます)。

exception EOFError

input() が何もデータを読まずに end-of-file (EOF) に達した場合に送出されます。(注意: io.IOBase.read()io.IOBase.readline() メソッドは、EOF に達すると空文字列を返します。)

exception FloatingPointError

浮動小数点演算が失敗した場合に送出されます。この例外は Python のどのバージョンでも常に定義されていますが、 Python が --with-fpectl オプションを有効にしてコンパイルされているか、 pyconfig.h ファイルにシンボル WANT_SIGFPE_HANDLER が定義されている場合にのみ送出されます。

exception GeneratorExit

ジェネレータ (generator) の close() メソッドが呼び出されたときに送出されます。この例外は厳密にはエラーではないので、 Exception ではなく BaseException を直接継承しています。

exception ImportError

import 文でモジュール定義を見つけられなかった場合や、 from ... import 文で指定した名前をインポートすることができなかった場合に送出されます。

name および path 属性はコンストラクタのキーワード専用引数を使って設定されえます。設定されたなら、インポートを試みられたモジュールの名前と、冷害を引き起こしたファイルへのパスとを、それぞれ表します。

バージョン 3.3 で変更: name および path 属性が追加されました。

exception IndexError

シーケンスの添字が範囲外の場合に送出されます (スライスのインデクスはシーケンスの範囲に収まるように暗黙のうちに調整されます; インデクスが整数でない場合、 TypeError が送出されます)。

exception KeyError

マッピング (辞書) のキーが、存在するキーの集合内に見つからなかった場合に送出されます。

exception KeyboardInterrupt

ユーザが割り込みキー (通常は Control-C または Delete) を押した場合に送出されます。実行中、割り込みが定期的に監視されます。この例外は Exception を捕捉するコードに誤って捕捉されてインタプリタの終了が阻害されないように、 BaseException を継承しています。

exception MemoryError

ある操作中にメモリが不足したが、その状況は (オブジェクトをいくつか消去することで) まだ復旧可能かもしれない場合に送出されます。例外の関連値は、どんな種類の (内部) 操作がメモリ不足になっているかを示す文字列です。背後にあるメモリ管理アーキテクチャ (C の malloc() 関数) のために、インタプリタが状況を完璧に復旧できるとはかぎらないので注意してください; プログラムの暴走が原因の場合にも、やはり実行スタックの追跡結果を出力できるようにするために例外が送出されます。

exception NameError

ローカルまたはグローバルの名前が見つからなかった場合に送出されます。これは非限定の名前のみに適用されます。関連値は見つからなかった名前を含むエラーメッセージです。

exception NotImplementedError

この例外は RuntimeError から派生しています。ユーザ定義の基底クラスにおいて、抽象メソッドが派生クラスでオーバライドされることを要求する場合、この例外を送出しなくてはなりません。

exception OSError

この例外は、システム関数が “file not found” や “disk full” のような I/O の失敗などのシステム関連のエラーを返した場合に送出されます (引数の型が間違っている場合や、他の偶発的なエラーは除きます)。たいてい実際には OSError のサブクラスが以下の `OS exceptions`_ で記述されているように送出されます。 errno 属性は errno に基づく数字のエラーコードです。

Windows において、winerror 属性はネイティブ Windows エラーコードを与えます。そして errno 属性は POSIX でいうネイティブエラーコードへのおよその翻訳です。

すべてのプラットフォームにおいて、strerror 属性はオペレーティングシステムから与えられた (POSIX においては perror() 、Windows においては FormatMessage() C 関数でフォーマットされた) のと一致する対応するエラーメッセージです。

ファイルシステムパスを含む例外 (open()os.unlink() など) について、例外インスタンスは関数に渡されたファイル名である追加の属性、filename を含みます。

バージョン 3.3 で変更: EnvironmentError, IOError, WindowsError, VMSError, socket.error, select.error and mmap.errorOSError に統合されました。

exception OverflowError

算術演算の結果が表現できない大きな値になった場合に送出されます。これは整数では起こりません (むしろ MemoryError が送出されることになるでしょう)。 C の浮動小数点演算の例外処理は標準化されていないので、ほとんどの浮動小数点演算もチェックされません。

exception ReferenceError

weakref.proxy() によって生成された弱参照 (weak reference) プロキシを使って、ガーベジコレクションによって回収された後の参照対象オブジェクトの属性にアクセスした場合に送出されます。弱参照については weakref モジュールを参照してください。

exception RuntimeError

他のどのカテゴリにも属さないエラーが検出された場合に送出されます。関連値は何が問題だったのかを示す文字列です。

exception StopIteration

組込み関数 next()iterator__next__() メソッドによって、そのイテレータが生成するアイテムがこれ以上ないことを伝えるために送出されます。

この例外オブジェクトには一つの属性 value があり、例外を構成する際に引数として与えられ、デフォルトは None です。

ジェネレータ関数が返るとき、新しい StopIteration インスタンスが送出され、関数の返り値が例外のコンストラクタの value パラメタとして使われます。

バージョン 3.3 で変更: value 属性とジェネレータ関数が値を返すためにそれを使う機能が追加されました。

exception SyntaxError

パーザが構文エラーに遭遇した場合に送出されます。この例外は import 文、組み込み関数 exec()evel() 、初期化スクリプトの読み込みや標準入力で (対話的な実行時にも) 起こる可能性があります。

このクラスのインスタンスは、例外の詳細に簡単にアクセスできるようにするために、属性 filename, lineno, offset, text を持ちます。例外インスタンスの str() はメッセージのみを返します。

exception IndentationError

正しくないインデントに関する構文エラーの基底クラスです。これは SyntaxError のサブクラスです。

exception TabError

タブとスペースを一貫しない方法でインデントに使っているときに送出されます。これは IndentationError のサブクラスです。

exception SystemError

インタプリタが内部エラーを発見したが、状況は全ての望みを棄てさせるほど深刻ではないと思われる場合に送出されます。関連値は (下位層の言葉で) 何がまずいのかを示す文字列です。

Python の作者か、あなたの Python インタプリタを保守している人にこのエラーを報告してください。このとき、 Python インタプリタのバージョン (sys.version; Python の対話的セッションを開始した際にも出力されます)、正確なエラーメッセージ (例外の関連値) を忘れずに報告してください。そしてもし可能ならエラーを引き起こしたプログラムのソースコードを報告してください。

exception SystemExit

この例外は sys.exit() 関数によって送出されます。この例外が処理されなかった場合、スタックのトレースバックを全く表示することなく Python インタプリタは終了します。関連値が整数であれば、システム終了ステータスを表します (exit() 関数に渡されます)。値が None の場合、終了ステータスは 0 です。 (文字列のような) 他の型の場合、そのオブジェクトの値が表示され、終了ステータスは 1 になります。

この例外のインスタンスは属性 code を持ちます。この値は終了ステータスまたはエラーメッセージ (標準では None) に設定されます。また、この例外は厳密にはエラーではないため、Exception ではなく BaseException から派生しています。

sys.exit() は、クリーンアップのための処理 (try 文の finally 節) が実行されるようにするため、またデバッガが制御不能になるリスクを冒さずにスクリプトを実行できるようにするために例外に翻訳されます。即座に終了することが真に強く必要であるとき (例えば、os.fork() を呼んだ後の子プロセス内) には os._exit() 関数を使うことができます。

この例外は Exception を捕まえるコードに間違って捕まえられないように、 Exception からではなく BaseException を継承しています。これにより、この例外は着実に呼出し元の方に伝わっていってインタプリタを終了させます。

exception TypeError

組み込み演算または関数が適切でない型のオブジェクトに対して適用された際に送出されます。関連値は型の不整合に関して詳細を述べた文字列です。

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

除算やモジュロ演算の第二引数が 0 であった場合に送出されます。関連値は文字列で、その演算における被演算子と演算子の型を示します。

以下の例外は、過去のバージョンとの後方互換性のために残されています; Python 3.3 より、これらは OSError のエイリアスです。

exception EnvironmentError
exception IOError
exception VMSError

VMS でのみ利用できます。

exception WindowsError

Windows でのみ利用できます。

5.2.1. OS 例外

以下の例外は OSError のサブクラスで、システムエラーコードに依存して送出されます。

exception BlockingIOError

ある操作が、ノンブロッキング操作に設定されたオブジェクト (例えばソケット) をブロックしそうになった場合に送出されます。errno EAGAIN, EALREADY, EWOULDBLOCK および EINPROGRESS に対応します。

BlockingIOError は、 OSError の属性に加えて一つの属性を持ちます:

characters_written

ストリームがブロックされるまでに書き込まれた文字数を含む整数です。この属性は io からのバッファ I/O クラスを使っているときに利用できます。

exception ChildProcessError

子プロセスの操作が失敗した場合に送出されます。errno ECHILD に対応します。

exception ConnectionError

コネクション関係の問題の基底クラス。

サブクラスは BrokenPipeError, ConnectionAbortedError, ConnectionRefusedError, ConnectionResetError です。

exception BrokenPipeError

ConnectionError のサブクラスで、もう一方の端が閉じられたパイプに書き込こもうとするか、書き込みのためにシャットダウンされたソケットに書き込こもうとした場合に発生します。 errno EPIPEESHUTDOWN に対応します。

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 に対応します。

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 例外階層の手直し

5.3. 警告

以下の例外は警告カテゴリとして使われます。詳細は warnings モジュールを参照してください。

exception Warning

警告カテゴリの基底クラスです。

exception UserWarning

ユーザコードによって生成される警告の基底クラスです。

exception DeprecationWarning

廃止された機能に対する警告の基底クラスです。

exception PendingDeprecationWarning

将来廃止される予定の機能に対する警告の基底クラスです。

exception SyntaxWarning

曖昧な構文に対する警告の基底クラスです。

exception RuntimeWarning

あいまいなランタイム挙動に対する警告の基底クラスです。

exception FutureWarning

将来意味構成が変わることになっている文の構成に対する警告の基底クラスです。

exception ImportWarning

モジュールインポートの誤りと思われるものに対する警告の基底クラスです。

exception UnicodeWarning

Unicode に関連した警告の基底クラスです。

exception BytesWarning

bytesbytearray に関連した警告の基底クラスです。

exception ResourceWarning

リソースの使用に関連した警告の基底クラスです。

バージョン 3.2 で追加.

5.4. 例外階層

組み込み例外のクラス階層は以下のとおりです:

BaseException
 +-- SystemExit
 +-- KeyboardInterrupt
 +-- GeneratorExit
 +-- Exception
      +-- StopIteration
      +-- ArithmeticError
      |    +-- FloatingPointError
      |    +-- OverflowError
      |    +-- ZeroDivisionError
      +-- AssertionError
      +-- AttributeError
      +-- BufferError
      +-- EOFError
      +-- ImportError
      +-- 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
      +-- SyntaxError
      |    +-- IndentationError
      |         +-- TabError
      +-- SystemError
      +-- TypeError
      +-- ValueError
      |    +-- UnicodeError
      |         +-- UnicodeDecodeError
      |         +-- UnicodeEncodeError
      |         +-- UnicodeTranslateError
      +-- Warning
           +-- DeprecationWarning
           +-- PendingDeprecationWarning
           +-- RuntimeWarning
           +-- SyntaxWarning
           +-- UserWarning
           +-- FutureWarning
           +-- ImportWarning
           +-- UnicodeWarning
           +-- BytesWarning
           +-- ResourceWarning