5. 組み込み例外¶
Python において、すべての例外は BaseException
から派生したクラスのインスタンスでなければなりません。特定のクラスを言及する except
節を伴う try
文において、その節はそのクラスから派生した例外クラスも処理しますが、そのクラスの派生 元 の例外クラスは処理しません。サブクラス化の関係にない 2 つの例外クラスは、それらが同じ名前だった場合でも等しくなりえません。
以下に挙げる組み込み例外は、インタプリタや組み込み関数によって生成されます。特に注記しないかぎり、これらはエラーの詳しい原因を示す "関連値 (associated value)" を持ちます。この値は、複数の情報 (エラーコードや、そのコードを説明する文字列など) の文字列かタプルです。関連値は通常、例外クラスのコンストラクタに引数として渡されます。
ユーザによるコードも組み込み例外を送出できます。これを使って、例外ハンドラをテストしたり、インタプリタが同じ例外を送出する状況と "ちょうど同じような" エラー条件であることを報告したりできます。しかし、ユーザのコードが適切でないエラーを送出するのを妨げる方法はないので注意してください。
組み込み例外クラスは新たな例外を定義するためにサブクラス化することができます。新しい例外は、Exception
クラスかそのサブクラスの一つから派生することをお勧めします。 BaseException
からは派生しないで下さい。例外を定義する上での詳しい情報は、 Python チュートリアルの ユーザー定義例外 の項目にあります。
except
または finally
節内で例外を送出 (または再送出) するとき、__context__
は自動的に最後に捕まった例外に設定されます。新しい例外が処理されなければ、最終的に表示されるトレースバックは先に起きた例外も最後の例外も含みます。
現在処理中の例外を raise
を使って再送出するのではなく新規に例外を送出する場合、raise
と一緒に from
を使うことで暗黙の例外コンテキストを捕捉することができます:
raise new_exc from original_exc
from
に続く式 (expression) は例外か 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
LookupError
¶ マッピングまたはシーケンスで使われたキーやインデクスが無効な場合に送出される例外
IndexError
およびKeyError
の基底クラスです。codecs.lookup()
によって直接送出されることもあります。
5.2. 具象例外¶
以下の例外は、通常送出される例外です。
-
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
¶ コーデックがエンコードまたはデコードしようとしたオブジェクトです。
-
-
exception
UnicodeEncodeError
¶ Unicode 関連のエラーがエンコード中に発生した際に送出されます。
UnicodeError
のサブクラスです。
-
exception
UnicodeDecodeError
¶ Unicode 関連のエラーがデコード中に発生した際に送出されます。
UnicodeError
のサブクラスです。
-
exception
UnicodeTranslateError
¶ Unicode 関連のエラーが変換中に発生した際に送出されます。
UnicodeError
のサブクラスです。
-
exception
ValueError
¶ Raised when a built-in operation or function receives an argument that has the right type but an inappropriate value, and the situation is not described by a more precise exception such as
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
の属性に加えて一つの属性を持ちます:
-
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
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