この章で説明する関数を使うと、Pythonの例外の処理や送出ができるように
なります。Pythonの例外処理の基本をいくらか理解することが大切です。
例外はUnix errno変数にやや似た機能を果たします: 発生した
中で最も新しいエラーの(スレッド毎の)グローバルなインジケータがあります。
実行に成功した場合にはほとんどの関数がこれをクリアしませんが、失敗したときには
エラーの原因を示すために設定します。ほとんどの関数はエラーインジケータも
返し、通常は関数がポインタを返すことになっている場合はNULLであり、
関数が整数を返す場合は-1です。(例外: PyArg_*()関数は
実行に成功したときに1を返し、失敗したときに0を返します).
ある関数が呼び出した関数がいくつか失敗したために、その関数が失敗しなければ ならないとき、一般的にエラーインジケータを設定しません。呼び出した関数が すでに設定しています。エラーを処理して例外をクリアするか、あるいは (オブジェクト参照またはメモリ割り当てのような)それが持つどんなリソースも 取り除いた後に戻るかのどちらか一方を行う責任があります。エラーを処理する 準備をしていなければ、普通に続けるべきではありません。エラーのために 戻る場合は、エラーが設定されていると呼び出し元に知らせることが大切です。 エラーが処理されていない場合または丁寧に伝えられている場合には、 Python/C APIのさらなる呼び出しは意図した通りには動かない可能性があり、 不可解な形で失敗するかもしれません。
エラーインジケータはPython変数sys.exc_type, sys.exc_value および
sys.exc_tracebackに対応する三つのPythonオブジェクトからからなります。
いろいろな方法でエラーインジケータとやりとりするためにAPI関数が存在します。
各スレッドに別々のエラーインジケータがあります。
| ) |
sys.stderrへ標準トレースバックをプリントし、エラーインジケータを
クリアします。エラーインジケータが設定されているときにだけ、この関数を
呼び出してください。(それ以外の場合、致命的なエラーを引き起こすでしょう!)
| ) |
| PyObject *exc) |
| PyObject *given, PyObject *exc) |
| PyObject**exc, PyObject**val, PyObject**tb) |
*excは
クラスオブジェクトだが*valは同じクラスのインスタンスでは
ないという意味です。この関数はそのような場合にそのクラスをインスタンス化
するために使われます。その値がすでに正規化されている場合は何も起きません。
遅延正規化はパフォーマンスを改善するために実装されています。
| ) |
| PyObject **ptype, PyObject **pvalue, PyObject **ptraceback) |
| PyObject *type, PyObject *value, PyObject *traceback) |
| PyObject *type, const char *message) |
| PyObject *type, PyObject *value) |
| PyObject *exception, const char *format, ...) |
幅.精度(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")とほぼ同じ。 |
認識できない書式化文字があると書式化文字列の残りすべてがそのまま 結果の文字列へコピーされ、余分の引数はどれも捨てられます。
| PyObject *type) |
| ) |
| ) |
| PyObject *type) |
| PyObject *type, const char *filename) |
| int ierr) |
| PyObject *type, int ierr) |
| int ierr, const char *filename) |
| PyObject *type, int ierr, char *filename) |
| ) |
| PyObject *category, char *message, int stacklevel) |
この関数は通常警告メッセージを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はありません。
| PyObject *category, char *message) |
非推奨; PyErr_WarnEx() を使って下さい。
| PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry) |
| ) |
1を返します。
そうでなければ、関数は0を返します。エラーインジケータが以前に
設定されている場合は、それがクリアされるかどうかわからない。
| ) |
| char *name, PyObject *base, PyObject *dict) |
module.class形式の
C文字列でなければならない。
baseとdict引数は通常NULLです。
これはすべての例外のためのルート、組み込み名Exception
(CではPyExc_Exceptionとしてアクセス可能)を根として
導出されたクラスオブジェクトを作成します。
新しいクラスの__module__属性はname引数の前半部分(最後のドットまで)に 設定され、クラス名は後半部分(最後のドットの後)に設定されます。 base引数は代わりのベースクラスを指定するために使えます; 一つのクラスでも、 クラスのタプルでも構いません。 dict引数はクラス変数とメソッドの辞書を指定するために使えます。
| PyObject *obj) |
sys.stderrへプリントします。
例えば、例外が__del__()メソッドで発生したときに使われます。
発生させられない例外が生じたコンテキストを特定するための一つの引数objとともに 関数が呼び出されます。objのreprが警告メッセージにプリントされるでしょう。