# 5. 組み込み例外

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

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

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

組み込み例外クラスは新たな例外を定義するためにサブクラス化することができます。新しい例外は、`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__` に残すことができます。

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

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

## 5.1. 基底クラス

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

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()` によって直接送出されることもあります。

## 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()` と `coroutine.close()` を参照してください。この例外はエラーではなく技術的なものなので、 `Exception` ではなく `BaseException` を直接継承しています。

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`) を押した場合に送出されます。実行中、割り込みは定期的に監視されます。`Exception` を捕捉するコードに誤って捕捉されてインタプリタの終了が阻害されないように、この例外は `BaseException` を継承しています。

exception `MemoryError`

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

exception `NameError`

  ローカルまたはグローバルの名前が見つからなかった場合に送出されます。これは非修飾の (訳注: `spam.egg` ではなく単に `egg` のような) 名前のみに適用されます。関連値は見つからなかった名前を含むエラーメッセージです。

exception `NotImplementedError`

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

  注釈

  演算子やメソッドがサポートされていないことを示す目的でこの例外を使用するべきではありません。そのようなケースではオペレータやメソッドを未定義のままとするか、サブクラスの場合は `None` を設定してください。

  注釈

  `NotImplementedError` と `NotImplemented` は、似たような名前と目的を持っていますが、相互に変換できません。 利用する際には、 `NotImplemented` を参照してください。

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

  この例外はシステム関数がシステム関連のエラーを返した場合に送出されます。例えば "file not found" や "disk full" のような I/O の失敗が発生したときです (引数の型が不正な場合や、他の偶発的なエラーは除きます)。

  コンストラクタの2番目の形式は下記の対応する属性を設定します。指定されなかった場合属性はデフォルトで `None` です。後方互換性のために、引数が3つ渡された場合、`args` 属性は最初の2つの要素のみからなるタプルを持ちます。

  コンストラクタは実際には、 OS exceptions で述べられている `OSError` のサブクラスを返すことがよくあります。特定のサブクラスは最終的な `errno` 値によります。この挙動は `OSError` を直接またはエイリアスで構築し、サブクラス化時に継承されなかった場合にのみ発生します。

  `errno`

    C 変数 `errno` に由来する数値エラーコードです。

  `winerror`

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

    Windows では、winerror コンストラクタ引数が整数の場合 `errno` 属性は Windows エラーコードから決定され、errno 引数は無視されます。他のプラットフォームでは winerror 引数は無視され、 `winerror` 属性は存在しません。

  `strerror`

    OS が提供するような、対応するエラーメッセージです。 POSIX では `perror()` で、Windows では `FormatMessage()` で体裁化されます。

  `filename`
  `filename2`

    ファイルシステムパスが1つ関与する例外 (例えば `open()` や `os.unlink()`) の場合、`filename` は関数に渡されたファイル名です。 ファイルシステムパスが2つ関与する関数 (例えば `os.rename()`) の場合、`filename2` は関数に渡された2つ目のファイル名です。

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

exception `RuntimeError`

  他のカテゴリに分類できないエラーが検出された場合に送出されます。関連値は、何が問題だったのかをより詳細に示す文字列です。

exception `StopIteration`

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

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

  generator や coroutine 関数が返るとき、新しい `StopIteration` インスタンスが送出されます。 関数の返り値は例外のコンストラクタの `value` 引数として使われます。

  `from __future__ import generator_stop` が宣言されている条件下では、ジェネレータ関数が投げる `StopIteration` は `RuntimeError` に変換されます (`StopIteration` は変換後の例外の原因例外として保持されます)。

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

  バージョン 3.5 で変更: 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()` 関数から送出されます。`Exception` をキャッチするコードに誤ってキャッチされないように、`Exception` ではなく `BaseException` を継承しています。これにより例外は上の階層に適切に伝わり、インタープリタを終了させます。この例外が処理されなかった場合はスタックのトレースバックを表示せずに Python インタープリタは終了します。コンストラクタは `sys.exit()` に渡されるオプション引数と同じものを受け取ります。値が整数の場合、システムの終了ステータス (C 言語の `exit()` 関数に渡すもの)を指定します。値が `None` の場合、終了ステータスは 0 です。それ以外の型の場合 (例えば str)、 オブジェクトの値が表示され、終了ステータスは 1 です。

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

  `code`

    コンストラクタに渡された終了ステータス又はエラーメッセージ。(デフォルトは `None`)

exception `TypeError`

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

  この例外は、そのオブジェクトで実行しようとした操作がサポートされておらず、その予定もない場合にユーザーコードから送出されるかもしれません。オブジェクトでその操作をサポートするつもりだが、まだ実装を提供していないのであれば、送出する適切な例外は `NotImplementedError` です。

  誤った型の引数が渡された場合は (例えば、`int` が期待されるのに、`list`が渡された) :exc:`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`

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

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

exception `EnvironmentError`

exception `IOError`

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` `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 は `InterruptedError` を送出する代わりにシステムコールを再試行するようになりました (論拠については PEP 475 を参照してください) 。

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`

  `bytes` や `bytearray` に関連した警告の基底クラスです。

exception `ResourceWarning`

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

  バージョン 3.2 で追加.

## 5.4. 例外のクラス階層

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

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