4. 例外処理

この章で説明する関数を使うと、Pythonの例外の処理や送出ができるようになります。Pythonの例外処理の基本をいくらか理解することが大切です。例外はUnix errno変数にやや似た機能を果たします: 発生した中で最も新しいエラーの(スレッド毎の)グローバルなインジケータがあります。実行に成功した場合にはほとんどの関数がこれをクリアしませんが、失敗したときにはエラーの原因を示すために設定します。ほとんどの関数はエラーインジケータも返し、通常は関数がポインタを返すことになっている場合はNULLであり、関数が整数を返す場合は-1です。(例外: PyArg_*()関数は実行に成功したときに1を返し、失敗したときに0を返します).

ある関数が呼び出した関数がいくつか失敗したために、その関数が失敗しなければならないとき、一般的にエラーインジケータを設定しません。呼び出した関数がすでに設定しています。エラーを処理して例外をクリアするか、あるいは (オブジェクト参照またはメモリ割り当てのような)それが持つどんなリソースも取り除いた後に戻るかのどちらか一方を行う責任があります。エラーを処理する準備をしていなければ、普通に続けるべきではありません。エラーのために戻る場合は、エラーが設定されていると呼び出し元に知らせることが大切です。エラーが処理されていない場合または丁寧に伝えられている場合には、 Python/C APIのさらなる呼び出しは意図した通りには動かない可能性があり、不可解な形で失敗するかもしれません。

エラーインジケータはPython変数sys.exc_type, sys.exc_value および sys.exc_tracebackに対応する三つのPythonオブジェクトからからなります。いろいろな方法でエラーインジケータとやりとりするためにAPI関数が存在します。各スレッドに別々のエラーインジケータがあります。

void PyErr_Print( ): sys.stderrへ標準トレースバックをプリントし、エラーインジケータをクリアします。エラーインジケータが設定されているときにだけ、この関数を呼び出してください。(それ以外の場合、致命的なエラーを引き起こすでしょう!)

PyObject* PyErr_Occurred( ): 戻り値: 借りた参照.
エラーインジケータが設定されているかテストします。設定されている場合は、例外の型(PyErr_Set*()関数の一つあるいは PyErr_Restore()への最も新しい呼び出しに対する第一引数)を返します。設定されていない場合はNULLを返します。あなたは戻り値への参照を持っていませんので、それにPy_DECREF()する必要はありません。注意: 戻り値を特定の例外と比較しないでください。その代わり、下に示すPyErr_ExceptionMatches()を使ってください。(比較は簡単に失敗するでしょう。なぜなら、例外はクラスではなくインスタンスかもしれないし、あるいは、クラス例外の場合は期待される例外のサブクラスかもしれないからです。)

int PyErr_ExceptionMatches( PyObject *exc): "PyErr_GivenExceptionMatches(PyErr_Occurred(), exc)"と同じ。例外が実際に設定されたときにだけ、これを呼び出だすべきです。例外が発生していないならば、メモリアクセス違反が起きるでしょう。

int PyErr_GivenExceptionMatches( PyObject *given, PyObject *exc): given例外がexcの例外と一致するなら真を返します。これはexcがクラスオブジェクトである場合も真を返します。これはgivenがサブクラスのインスタンスであるときも真を返します。excがタプルならば、タプル内 (と再帰的にサブタプル内)のすべての例外が一致するか調べられます。 givenがNULLならば、メモリアクセス違反が起きるでしょう。

void PyErr_NormalizeException( PyObject**exc, PyObject**val, PyObject**tb): ある状況では、以下のPyErr_Fetch()が返す値は ``正規化されていない''可能性があります。つまり、*excはクラスオブジェクトだが*valは同じクラスのインスタンスではないという意味です。この関数はそのような場合にそのクラスをインスタンス化するために使われます。その値がすでに正規化されている場合は何も起きません。遅延正規化はパフォーマンスを改善するために実装されています。

void PyErr_Clear( ): エラーインジケータをクリアします。エラーインジケータが設定されていないならば、効果はありません。

void PyErr_Fetch( PyObject **ptype, PyObject **pvalue, PyObject **ptraceback): エラーインジケータをアドレスを渡す三つの変数の中へ取り出します。エラーインジケータが設定されていない場合は、三つすべての変数をNULLに設定します。エラーインジケータが設定されている場合はクリアされ、あなたは取り出されたそれぞれのオブジェクトへの参照を持つことになります。型オブジェクトがNULLでないときでさえ、その値とトレースバックオブジェクトは NULLかもしれません。注意: 通常、この関数は例外を扱う必要のあるコードあるいはエラーインジケータを一時的に保存して元に戻す必要のあるコードによってのみ使用されます。

void PyErr_Restore( PyObject *type, PyObject *value, PyObject *traceback): 三つのオブジェクトからエラーインジケータを設定します。エラーインジケータがすでに設定されている場合は、最初にクリアされます。オブジェクトがNULLならば、エラーインジケータがクリアされます。NULLのtypeと非NULLのvalueあるいは tracebackを渡してはいけません。例外の型(type)はクラスであるべきです。無効な例外の型(type)あるいは値(value)を渡してはいけません。 (これらの規則を破ると後で気付きにくい問題の原因となるでしょう。) この呼び出しはそれぞれのオブジェクトへの参照を取り除きます: あなたは呼び出しの前にそれぞれのオブジェクトへの参照を持たなければならないのであり、また呼び出しの後にはもはやこれらの参照を持っていません。 (これを理解していない場合は、この関数を使ってはいけません。注意しておきます。) 注意: 通常この関数はエラーインジケータを一時的に保存し元に戻す必要のあるコードによってのみに使われます。現在の例外状態を保存するためには PyErr_Fetch()を使ってください。

void PyErr_SetString( PyObject *type, const char *message): これはエラーインジケータを設定するための最も一般的な方法です。第一引数は例外の型を指定します。通常は標準例外の一つ、例えばPyExc_RuntimeErrorです。その参照カウントを増加させる必要はありません。第二引数はエラーメッセージで、文字列オブジェクトへ変換されます。

void PyErr_SetObject( PyObject *type, PyObject *value): この関数はPyErr_SetString()に似ていますが、例外の``値(value)''として任意のPythonオブジェクトを指定することができます。

PyObject* PyErr_Format( PyObject *exception, const char *format, ...)

戻り値: 常に NULL.

この関数はエラーインジケータを設定しNULLを返します。 exceptionはPython例外(インスタンスではなくクラス)であるべきです。 formatは文字列であるべきであり、printf()に似た書式化コードを含んでいます。書式化コードの前の幅.精度(width.precision)は解析されますが、幅の部分は無視されます。

書式文字	型	コメント
`%%`	n/a	リテラルの % 文字。
`%c`	int	一文字. Cのintで表現される。
`%d`	int	`printf("%d")` と完全に同じ。
`%u`	unsigned int	`printf("%u")` と完全に同じ。
`%ld`	long	`printf("%ld")` と完全に同じ。
`%lu`	unsigned long	`printf("%lu")` と完全に同じ。
`%zd`	Py_ssize_t	`printf("%zd")` と完全に同じ。
`%zu`	size_t	`printf("%zu")` と完全に同じ.
`%i`	int	`printf("%i")` と完全に同じ。
`%x`	int	`printf("%x")` と完全に同じ。
`%s`	char*	NULL終端の C の文字配列。
`%p`	void*	C ポインタの16進表現。プラットフォームのprintfによらず、必ずリテラル `0x` が頭につくことが保証されるという以外、`printf("%p")`とほぼ同じ。

認識できない書式化文字があると書式化文字列の残りすべてがそのまま結果の文字列へコピーされ、余分の引数はどれも捨てられます。

void PyErr_SetNone( PyObject *type): これは"PyErr_SetObject(type, Py_None)"を省略したものです。

int PyErr_BadArgument( ): これは"PyErr_SetString(PyExc_TypeError, message)"を省略したもので、ここでmessageは組み込み操作が不正な引数で呼び出されたということを表しています。主に内部で使用するためのものです。

PyObject* PyErr_NoMemory( ): 戻り値: 常に NULL.
これは"PyErr_SetNone(PyExc_MemoryError)"を省略したもので、 NULLを返します。したがって、メモリ不足になったとき、オブジェクト割り当て関数は"return PyErr_NoMemory();"と書くことができます。

PyObject* PyErr_SetFromErrno( PyObject *type): 戻り値: 常に NULL.
Cライブラリ関数がエラーを返してC変数errnoを設定したときに、これは例外を発生させるために便利な関数です。第一要素が整数errno値で、第二要素が (strerror()から得られる)対応するエラーメッセージであるタプルオブジェクトを構成します。それから、 "PyErr_SetObject(type, object)"を呼び出します。 Unixでは、errno値がEINTRであるとき、すなわち割り込まれたシステムコールを表しているとき、これは PyErr_CheckSignals()を呼び出し、それがエラーインジケータを設定した場合は設定されたままにしておきます。関数は常にNULLを返します。したがって、システムコールがエラーを返したとき、システムコールのラッパー関数は"return PyErr_SetFromErrno(type);"と書くことができます。

PyObject* PyErr_SetFromErrnoWithFilename( PyObject *type, const char *filename): 戻り値: 常に NULL.
PyErr_SetFromErrno()に似ていて、filenameがNULLでない場合に、それがtypeのコンストラクタに第三引数として渡されるというふるまいが追加されています。IOErrorとOSErrorのような例外の場合では、これが例外インスタンスのfilename属性を定義するために使われます。

PyObject* PyErr_SetFromWindowsErr( int ierr): 戻り値: 常に NULL.
これはWindowsErrorを発生させるために便利な関数です。 0のierrとともに呼び出された場合、GetLastError()が返すエラーコードが代りに使われます。ierrあるいは GetLastError()によって与えられるエラーコードのWindows用の説明を取り出すために、Win32関数FormatMessage()を呼び出します。それから、第一要素がierr値で第二要素が(FormatMessage()から得られる) 対応するエラーメッセージであるタプルオブジェクトを構成します。そして、 "PyErr_SetObject(PyExc_WindowsError, object)"を呼び出します。この関数は常にNULLを返します。利用可能範囲: Windows。

PyObject* PyErr_SetExcFromWindowsErr( PyObject *type, int ierr): 戻り値: 常に NULL.
PyErr_SetFromWindowsErr()に似ていて、送出する例外の型を指定する引数が追加されています。利用可能範囲: Windows。バージョン 2.3 で新たに追加された仕様です。

PyObject* PyErr_SetFromWindowsErrWithFilename( int ierr, const char *filename): 戻り値: 常に NULL.
PyErr_SetFromWindowsErr()に似ていて、filenameがNULLでない場合には WindowsErrorのコンストラクタへ第三引数として渡されるという振る舞いが追加されています。利用可能範囲: Windows。

PyObject* PyErr_SetExcFromWindowsErrWithFilename( PyObject *type, int ierr, char *filename): 戻り値: 常に NULL.
PyErr_SetFromWindowsErrWithFilename()に似ていて、発生させる例外の型を指定する引数が追加されています。利用可能範囲: Windows。バージョン 2.3 で新たに追加された仕様です。

void PyErr_BadInternalCall( ): "PyErr_SetString(PyExc_TypeError, message)"を省略したものです。ここでmessageは内部操作(例えば、Python/C API関数)が不正な引数とともに呼び出されたということを示しています。主に内部で使用するためのものです。

int PyErr_WarnEx( PyObject *category, char *message, int stacklevel)

警告メッセージを出します。category引数は警告カテゴリ(以下を参照) かまたはNULLで、message引数はメッセージ文字列です。stacklevelはフレームの数を示す正の整数です; 警告はそのスタックフレームの中の実行している行から発行されます。stacklevelが1だと、 PyErr_WarnEx() が、2だとその上の関数が、Warningの発行元になります。

この関数は通常警告メッセージをsys.stderrへプリントします。けれども、ユーザが警告をエラーへ変更するように指定することも可能です。そのような場合には、これは例外を発生させます。警告機構がもつ問題のためにその関数が例外を発生させるということも可能です。(実装ではその厄介な仕事を行うためにwarningsモジュールをインポートします)。例外が発生させられなければ、戻り値は0です。あるいは、例外が発生させられると-1です。(警告メッセージが実際にプリントされるかどうかを決定することはできず、また何がその例外の原因なのかを決定することもできない。これは意図的なものです。)例外が発生した場合、呼び出し元は通常の例外処理を行います(例えば、Py_DECREF()は参照を持っており、エラー値を返します)。

警告カテゴリはWarningのサブクラスでなければならない。デフォルト警告カテゴリはRuntimeWarningです。標準Python警告カテゴリは"PyExc_"にPython例外名が続く名前のグローバル変数を用いて変更できます。これらは型PyObject*を持ち、すべてクラスオブジェクトです。それらの名前は PyExc_Warning, PyExc_UserWarning, PyExc_UnicodeWarning, PyExc_DeprecationWarning, PyExc_SyntaxWarning, PyExc_RuntimeWarning, PyExc_FutureWarning です。 PyExc_WarningはPyExc_Exceptionのサブクラスです。その他の警告カテゴリはPyExc_Warningのサブクラスです。

警告をコントロールするための情報については、warningsモジュールのドキュメンテーションとコマンドライン・ドキュメンテーションの -Wオプションを参照してください。警告コントロールのためのC APIはありません。

int PyErr_Warn( PyObject *category, char *message): 警告メッセージを出します。category引数は警告カテゴリ(以下を参照) かまたはNULLで、message引数はメッセージ文字列です。警告は、 PyErr_WarnEx() を stacklevel に 1 を指定した時と同じく、 PyErr_Warn() を呼び出した関数から発行されます。
非推奨; PyErr_WarnEx() を使って下さい。

int PyErr_WarnExplicit( PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry): すべての警告の属性を明示的に制御した警告メッセージを出します。これはPython関数warnings.warn_explicit()の直接的なラッパで、さらに情報を得るにはそちらを参照してください。そこに説明されているデフォルトの効果を得るために、moduleとregistry引数はNULLに設定することができます。

int PyErr_CheckSignals( ): この関数はPythonのシグナル処理とやりとりすることができます。シグナルがそのプロセスへ送られたかどうかチェックし、そうならば対応するシグナルハンドラを呼び出します。 signalモジュールがサポートされている場合は、これはPythonで書かれたシグナルハンドラを呼び出せます。すべての場合で、 SIGINTのデフォルトの効果は KeyboardInterrupt例外を発生させることです。例外が発生した場合、エラーインジケータが設定され、関数は1を返します。そうでなければ、関数は0を返します。エラーインジケータが以前に設定されている場合は、それがクリアされるかどうかわからない。

void PyErr_SetInterrupt( ): この関数は廃止されています。SIGINTシグナルが到達した影響をシミュレートします -- 次に PyErr_CheckSignals()が呼ばれるとき、 KeyboardInterruptは送出されるでしょう。インタプリタロックを保持することなく呼び出すことができます。

PyObject* PyErr_NewException( char *name, PyObject *base, PyObject *dict): 戻り値: 新たな参照.
このユーティリティ関数は新しい例外オブジェクトを作成して返します。 name引数は新しい例外の名前、module.class形式の C文字列でなければならない。 baseとdict引数は通常NULLです。これはすべての例外のためのルート、組み込み名Exception (CではPyExc_Exceptionとしてアクセス可能)を根として導出されたクラスオブジェクトを作成します。
新しいクラスの__module__属性はname引数の前半部分(最後のドットまで)に設定され、クラス名は後半部分(最後のドットの後)に設定されます。 base引数は代わりのベースクラスを指定するために使えます; 一つのクラスでも、クラスのタプルでも構いません。 dict引数はクラス変数とメソッドの辞書を指定するために使えます。

void PyErr_WriteUnraisable( PyObject *obj): 例外が設定されているがインタプリタが実際に例外を発生させることができないときに、このユーティリティ関数は警告メッセージをsys.stderrへプリントします。例えば、例外が__del__()メソッドで発生したときに使われます。
発生させられない例外が生じたコンテキストを特定するための一つの引数objとともに関数が呼び出されます。objのreprが警告メッセージにプリントされるでしょう。

ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。