例外処理¶

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

具体的には、エラーインジケータは、例外の型、例外の値、トレースバックオブジェクトの３つのオブジェクトポインタで構成されます。これらのポインタはどれでも、設定されない場合は NULL になりえます（ただし、いくつかの組み合わせは禁止されており、例えば、例外の型が NULL の場合は、トレースバックは非 NULL の値になりません）

呼び出した関数が失敗したために自分も失敗する必要がある場合、通常はエラーインジケータを設定しません。呼び出した関数がすでに設定しているためです。その関数には、エラーを処理して例外をクリアするか、保持しているリソース (オブジェクトへの参照や割り当てたメモリなど) を解放してから戻る責任があります。エラーを処理する準備がないなら、通常どおり実行を続けては いけません。エラーのために戻る場合は、エラーが設定されていることを呼び出し側に通知することが重要です。エラーを処理せず、適切に伝播させることもしなければ、その後の Python/C API の呼び出しは意図どおりに動作せず、不可解な形で失敗する可能性があります。

注釈

エラーインジケータは sys.exc_info() の結果とは 異なります。前者はまだ捕捉されていない例外 (したがって伝播中の例外) に対応し、後者は捕捉された後の例外 (したがって伝播が止まった例外) を返します。

出力とクリア¶

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

void PyErr_PrintEx(int set_sys_last_vars)¶

次に属します: Stable ABI.

標準のトレースバックを sys.stderr に出力し、エラーインジケータをクリアします。ただし、エラーが SystemExit である場合を除いて です。その場合、トレースバックは出力されず、 Python プロセスは SystemExit インスタンスで指定されたエラーコードで終了します。

エラーインジケータが設定されているときにだけ、この関数を呼び出してください。それ以外の場合、致命的なエラーを引き起こすでしょう!

set_sys_last_vars がゼロでない場合、表示した例外を変数 sys.last_exc に設定します。後方互換性のため、非推奨の変数 sys.last_type、sys.last_value、sys.last_traceback にも、この例外の型、値、トレースバックをそれぞれ設定します。

バージョン 3.12 で変更: sys.last_exc の設定が追加されました。

void PyErr_Print()¶: 次に属します: Stable ABI.
PyErr_PrintEx(1) のエイリアスです。

void PyErr_WriteUnraisable(PyObject *obj)¶

次に属します: Stable ABI.

現在の例外と obj 引数で sys.unraisablehook() を呼び出します。

このユーティリティ関数は、例外が設定されているものの、インタープリタが実際にはその例外を送出できない場合に、sys.stderr に警告メッセージを表示します。例えば __del__() メソッド内で例外が発生した場合に使われます。

この関数は、送出できない例外が発生した状況を示す 1 つの引数 obj を指定して呼び出します。可能であれば、警告メッセージに obj の repr を表示します。 obj が NULL の場合はトレースバックだけを表示します。

この関数を呼び出すときには、例外がセットされていなければなりません。

バージョン 3.4 で変更: トレースバックを表示するようになりました。 obj が NULL の場合はトレースバックだけを表示します。

バージョン 3.8 で変更: sys.unraisablehook() を使うようになりました。

void PyErr_FormatUnraisable(const char *format, ...)¶: PyErr_WriteUnraisable() と同様ですが、format とそれ以降の引数を使って警告メッセージを書式化します。これらの意味と値は PyUnicode_FromFormat() と同じです。 PyErr_WriteUnraisable(obj) は、おおよそ PyErr_FormatUnraisable("Exception ignored in: %R", obj) と等価です。 format が NULL の場合はトレースバックだけを表示します。

Added in version 3.13.

void PyErr_DisplayException(PyObject *exc)¶: 次に属します: Stable ABI (バージョン 3.12 より).
連鎖した例外と注釈を含め、exc のトレースバックを標準の形式で sys.stderr に表示します。

Added in version 3.12.

void PyErr_Display(PyObject *unused, PyObject *value, PyObject *tb)¶

次に属します: Stable ABI.

PyErr_DisplayException() の従来の版です。

例外 value とそのトレースバックを sys.stderr に表示します。 value にトレースバックが設定されていない場合は、tb をトレースバックとして使います。最初の引数は無視します。

sys.stderr が None の場合は何も表示しません。 sys.stderr が設定されていない場合は、代わりに C の stderr ストリームに例外をダンプします。

バージョン 3.12 で非推奨: 代わりに PyErr_DisplayException() を使ってください。

例外の送出¶

以下の関数は、現在のスレッドのエラーインジケータの設定を補助します。利便性のため、これらの関数のいくつかは、 return 文で利用できるように常に NULL ポインタを返します。

void PyErr_SetString(PyObject *type, const char *message)¶: 次に属します: Stable ABI.
エラーインジケータを設定する最も一般的な方法です。最初の引数は例外の型で、通常は PyExc_RuntimeError などの標準の例外のいずれかです。その型への新しい強参照を作成する必要はありません (例えば Py_INCREF() は不要です)。 2 番目の引数はエラーメッセージで、'utf-8' からデコードします。

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

PyObject *PyErr_Format(PyObject *exception, const char *format, ...)¶: 戻り値: 常に NULL 。 次に属します: Stable ABI.
この関数はエラーインジケータを設定し NULL を返します。 exception はPython例外クラスであるべきです。 format と以降の引数はエラーメッセージを作るためのもので, PyUnicode_FromFormat() の引数と同じ意味を持っています。 format は ASCII エンコードされた文字列です。

PyObject *PyErr_FormatV(PyObject *exception, const char *format, va_list vargs)¶: 戻り値: 常に NULL 。 次に属します: Stable ABI (バージョン 3.5 より).
PyErr_Format() と同じですが、可変長引数の代わりに va_list 引数を受け取ります。

Added in version 3.5.

void PyErr_SetNone(PyObject *type)¶: 次に属します: Stable ABI.
これは PyErr_SetObject(type, Py_None) を省略したものです。

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

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

PyObject *PyErr_SetFromErrno(PyObject *type)¶: 戻り値: 常に NULL 。 次に属します: Stable ABI.
C ライブラリ関数がエラーを返し、C の変数 errno を設定した場合に、例外を送出するための便利関数です。最初の要素が errno の整数値、2 番目の要素が対応するエラーメッセージ (strerror() から取得) であるタプルオブジェクトを作成し、PyErr_SetObject(type, object) を呼び出します。 Unix で errno がシステムコールの中断を示す EINTR の場合は、PyErr_CheckSignals() を呼び出します。それによってエラーインジケータが設定された場合は、そのままにします。この関数は常に NULL を返すため、システムコールのラッパー関数は、システムコールがエラーを返したときに return PyErr_SetFromErrno(type); と書けます。

PyObject *PyErr_SetFromErrnoWithFilenameObject(PyObject *type, PyObject *filenameObject)¶: 戻り値: 常に NULL 。 次に属します: Stable ABI.
PyErr_SetFromErrno() と同様ですが、filenameObject が NULL でなければ、type のコンストラクタに 3 番目の引数として渡します。 OSError 例外では、これは例外インスタンスの filename 属性の定義に使われます。

PyObject *PyErr_SetFromErrnoWithFilenameObjects(PyObject *type, PyObject *filenameObject, PyObject *filenameObject2)¶: 戻り値: 常に NULL 。 次に属します: Stable ABI (バージョン 3.7 より).
PyErr_SetFromErrnoWithFilenameObject() に似てますが、ファイル名を2つ取る関数が失敗したときに例外を送出するために、2つ目のファイル名オブジェクトを受け取ります。

Added in version 3.4.

PyObject *PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename)¶: 戻り値: 常に NULL 。 次に属します: Stable ABI.
PyErr_SetFromErrnoWithFilenameObject() に似ていますが、ファイル名は C 文字列として与えられます。 filename はファイルシステムのエンコーディングとエラーハンドラでデコードされます。

PyObject *PyErr_SetFromWindowsErr(int ierr)¶: 戻り値: 常に NULL 。 次に属します: Stable ABI on Windows (バージョン 3.7 より).
OSError を送出するための便利関数です。 ierr に 0 を指定して呼び出すと、代わりに GetLastError() の呼び出しで返されたエラーコードを使います。 Win32 関数 FormatMessage() を呼び出し、ierr または GetLastError() で指定されたエラーコードの Windows による説明を取得します。次に、winerror 属性をエラーコード、strerror 属性を対応するエラーメッセージ (FormatMessage() から取得) に設定した OSError オブジェクトを作成し、PyErr_SetObject(PyExc_OSError, object) を呼び出します。この関数は常に NULL を返します。

利用可能な環境: Windows.

PyObject *PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)¶: 戻り値: 常に NULL 。 次に属します: Stable ABI on Windows (バージョン 3.7 より).
PyErr_SetFromWindowsErr() に似ていますが、送出する例外の型を指定する引数が追加されています。

利用可能な環境: Windows.

PyObject *PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)¶: 戻り値: 常に NULL 。 次に属します: Stable ABI on Windows (バージョン 3.7 より).
PyErr_SetFromWindowsErr() と同様ですが、filename が NULL でなければ、ファイルシステムのエンコーディング (os.fsdecode()) でデコードし、OSError のコンストラクタに 3 番目の引数として渡します。これは例外インスタンスの filename 属性の定義に使われます。

利用可能な環境: Windows.

PyObject *PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject *type, int ierr, PyObject *filename)¶: 戻り値: 常に NULL 。 次に属します: Stable ABI on Windows (バージョン 3.7 より).
Similar to PyErr_SetExcFromWindowsErr(), with the additional behavior that if filename is not NULL, it is passed to the constructor of OSError as a third parameter to be used to define the filename attribute of the exception instance.

利用可能な環境: Windows.

PyObject *PyErr_SetExcFromWindowsErrWithFilenameObjects(PyObject *type, int ierr, PyObject *filename, PyObject *filename2)¶: 戻り値: 常に NULL 。 次に属します: Stable ABI on Windows (バージョン 3.7 より).
PyErr_SetExcFromWindowsErrWithFilenameObject() に似てますが、2つ目のファイル名オブジェクトを受け取ります。

利用可能な環境: Windows.

Added in version 3.4.

PyObject *PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, const char *filename)¶: 戻り値: 常に NULL 。 次に属します: Stable ABI on Windows (バージョン 3.7 より).
PyErr_SetFromWindowsErrWithFilename() に似ていますが、送出する例外の型を指定する引数が追加されています。

利用可能な環境: Windows.

PyObject *PyErr_SetImportError(PyObject *msg, PyObject *name, PyObject *path)¶: 戻り値: 常に NULL 。 次に属します: Stable ABI (バージョン 3.7 より).
ImportError を簡単に送出するための関数です。 msg は例外のメッセージ文字列としてセットされます。 name と path はどちらも NULL にしてよく、それぞれ ImportError の name 属性と path 属性としてセットされます。

Added in version 3.3.

PyObject *PyErr_SetImportErrorSubclass(PyObject *exception, PyObject *msg, PyObject *name, PyObject *path)¶: 戻り値: 常に NULL 。 次に属します: Stable ABI (バージョン 3.6 より).
PyErr_SetImportError() とよく似ていますが、この関数は送出する例外として、 ImportError のサブクラスを指定できます。

Added in version 3.6.

void PyErr_SyntaxLocationObject(PyObject *filename, int lineno, int col_offset)¶: 現在の例外のファイル、行、オフセットの情報をセットします。現在の例外が SyntaxError でない場合は、例外を表示するサブシステムが、例外が SyntaxError であると思えるように属性を追加します。

Added in version 3.4.

void PyErr_RangedSyntaxLocationObject(PyObject *filename, int lineno, int col_offset, int end_lineno, int end_col_offset)¶: PyErr_SyntaxLocationObject() と同様ですが、現在の例外の end_lineno と end_col_offset の情報も設定します。

Added in version 3.10.

void PyErr_SyntaxLocationEx(const char *filename, int lineno, int col_offset)¶: 次に属します: Stable ABI (バージョン 3.7 より).
PyErr_SyntaxLocationObject() と似ていますが、 filename はファイルシステムのエンコーディングとエラーハンドラでデコードされたバイト文字列です。

Added in version 3.2.

void PyErr_SyntaxLocation(const char *filename, int lineno)¶: 次に属します: Stable ABI.
PyErr_SyntaxLocationEx() と似ていますが、 col_offset 引数が除去されています。

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

PyObject *PyErr_ProgramTextObject(PyObject *filename, int lineno)¶

filename の lineno 行目のソース行を取得します。 filename は Python の str オブジェクトでなければなりません。

成功すると、見つかった行を格納する Python の文字列オブジェクトを返します。失敗すると例外を設定せずに NULL を返します。

PyObject *PyErr_ProgramText(const char *filename, int lineno)¶: 次に属します: Stable ABI.
PyErr_ProgramTextObject() と同様ですが、filename は Python オブジェクトへの参照ではなく、ファイルシステムのエンコーディングとエラーハンドラでデコードする const char* です。

警告¶

以下の関数を使い、 C コードで起きた警告を報告します。 Python の warnings モジュールで公開されている同様の関数とよく似てます。これらの関数は通常警告メッセージを sys.stderr へ出力しますが、ユーザが警告をエラーへ変更するように指定することもでき、その場合は、関数は例外を送出します。警告機構がもつ問題のためにその関数が例外を送出するということも有り得ます。例外が送出されない場合は戻り値は 0 で、例外が送出された場合は -1 です。 (警告メッセージが実際に出力されるか、およびその例外の原因が何かについては判断できません; これは意図的なものです。) 例外が送出された場合、呼び出し元は通常の例外処理を行います (例えば、保持していた参照に対し Py_DECREF() を行い、エラー値を返します)。

int PyErr_WarnEx(PyObject *category, const char *message, Py_ssize_t stack_level)¶

次に属します: Stable ABI.

警告メッセージを発行します。 category 引数は警告カテゴリ (後述) または NULL、message 引数は UTF-8 でエンコードされた文字列です。 stack_level はスタックフレーム数を指定する正の値で、そのフレームで現在実行中のコードの行を発行元として警告を発行します。 stack_level が 1 なら PyErr_WarnEx() を呼び出す関数、2 ならその 1 つ上の関数、というようになります。

警告カテゴリは PyExc_Warning のサブクラスでなければなりません。 PyExc_Warning は PyExc_Exception のサブクラスです。デフォルトの警告カテゴリは PyExc_RuntimeWarning です。標準の Python 警告カテゴリは、警告の型で名前が列挙されているグローバル変数として利用可能です。

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

int PyErr_Warn(PyObject *category, const char *message)¶: PyErr_WarnEx(category, message, 1) と等価です。

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

Added in version 3.4.

int PyErr_WarnExplicit(PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry)¶: 次に属します: Stable ABI.
PyErr_WarnExplicitObject() に似ていますが、 message と module が UTF-8 エンコードされた文字列であるところが異なり、 filename はファイルシステムのエンコーディングとエラーハンドラでデコードされます。

int PyErr_WarnFormat(PyObject *category, Py_ssize_t stack_level, const char *format, ...)¶: 次に属します: Stable ABI.
PyErr_WarnEx() と同様の関数ですが、警告メッセージの書式化に PyUnicode_FromFormat() を使います。 format は ASCII でエンコードされた文字列です。

Added in version 3.2.

int PyErr_WarnExplicitFormat(PyObject *category, const char *filename, int lineno, const char *module, PyObject *registry, const char *format, ...)¶: PyErr_WarnExplicit() と同様ですが、警告メッセージの書式化に PyUnicode_FromFormat() を使います。 format は ASCII でエンコードされた文字列です。

Added in version 3.2.

int PyErr_ResourceWarning(PyObject *source, Py_ssize_t stack_level, const char *format, ...)¶: 次に属します: Stable ABI (バージョン 3.6 より).
PyErr_WarnFormat() と同様の関数ですが、category は ResourceWarning で、source を warnings.WarningMessage に渡します。

Added in version 3.6.

エラーインジケータの問い合わせ¶

PyObject *PyErr_Occurred()¶

戻り値: 借用参照。 次に属します: Stable ABI.

エラーインジケータが設定されているかテストします。設定されている場合は、例外の型 (PyErr_Set* 関数の一つあるいは PyErr_Restore() への最も新しい呼び出しに対する第一引数)を返します。設定されていない場合は NULL を返します。あなたは戻り値への参照を持っていませんので、それに Py_DECREF() する必要はありません。

呼び出し側にはアタッチされたスレッド状態が必要です。

注釈

戻り値を特定の例外と比較しないでください。その代わりに、下に示す PyErr_ExceptionMatches() を使ってください。(比較は簡単に失敗するでしょう。なぜなら、例外はクラスではなくインスタンスかもしれないし、あるいは、クラス例外の場合は期待される例外のサブクラスかもしれないからです。)

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

int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)¶: 次に属します: Stable ABI.
例外 given が exc の例外型と適合する場合に真を返します。 exc がクラスオブジェクトである場合も、 given がサブクラスのインスタンスであるときに真を返します。 exc がタプルの場合は、タプルにある (およびそのサブタプルに再帰的にある) すべての例外型が適合するか調べられます。

PyObject *PyErr_GetRaisedException(void)¶

戻り値: 新しい参照。 次に属します: Stable ABI (バージョン 3.12 より).

現在発生している例外を返し、同時にエラーインジケータを消去します。エラーインジケータが設定されていない場合は NULL を返します。

この関数は、例外をキャッチする必要があるコード、または一時的にエラーインジケータを保存・復元する必要があるコードに使用されます。

例えば:

{
   PyObject *exc = PyErr_GetRaisedException();

   /* ... 他のエラーを発生させる可能性があるコード ... */

   PyErr_SetRaisedException(exc);
}

参考

現在処理中の例外を保存するには PyErr_GetHandledException() を使います。

Added in version 3.12.

void PyErr_SetRaisedException(PyObject *exc)¶

次に属します: Stable ABI (バージョン 3.12 より).

既存の例外が設定されていればクリアし、現在送出中の例外に exc を設定します。 exc が NULL の場合は、既存の例外をクリアするだけです。

exc は有効な例外または NULL でなければなりません。

この呼び出しは exc への参照を「盗みます」。

Added in version 3.12.

void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)¶

次に属します: Stable ABI.

バージョン 3.12 で非推奨: 代わりに PyErr_GetRaisedException() を使ってください。

エラーインジケータをアドレスを渡す三つの変数の中へ取り出します。エラーインジケータが設定されていない場合は、三つすべての変数を NULL に設定します。エラーインジケータが設定されている場合はクリアされ、あなたは取り出されたそれぞれのオブジェクトへの参照を持つことになります。型オブジェクトが NULL でないときでさえ、その値とトレースバックオブジェクトは NULL かもしれません。

注釈

通常、この関数を使うのは、例外の捕捉やエラーインジケータの一時的な保存と復元が必要な従来のコードだけです。

例えば:

{
   PyObject *type, *value, *traceback;
   PyErr_Fetch(&type, &value, &traceback);

   /* ... 他のエラーを発生させる可能性があるコード ... */

   PyErr_Restore(type, value, traceback);
}

void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback)¶: 次に属します: Stable ABI.

バージョン 3.12 で非推奨: 代わりに PyErr_SetRaisedException() を使ってください。

3 つのオブジェクト type、value、traceback からエラーインジケータを設定し、既存の例外が設定されていればクリアします。これらのオブジェクトが NULL の場合はエラーインジケータをクリアします。 NULL の型と、NULL でない値やトレースバックを組み合わせて渡してはいけません。例外の型はクラスでなければなりません。無効な例外の型や値を渡してはいけません (これらの規則を破ると、後で気づきにくい問題を引き起こします)。この呼び出しは各オブジェクトへの参照を奪います。呼び出し前には各オブジェクトへの参照を所有している必要があり、呼び出し後にはそれらの参照を所有しなくなります。 (この意味が分からない場合は、この関数を使わないでください。十分に注意してください。)

注釈

通常、この関数を使うのは、エラーインジケータの一時的な保存と復元が必要な従来のコードだけです。現在のエラーインジケータを保存するには PyErr_Fetch() を使ってください。

void PyErr_NormalizeException(PyObject **exc, PyObject **val, PyObject **tb)¶

次に属します: Stable ABI.

バージョン 3.12 で非推奨: 正規化が失われる可能性を避けるため、代わりに PyErr_GetRaisedException() を使ってください。

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

注釈

この関数は、例外の値に __traceback__ 属性を暗黙に設定することは ありません。トレースバックを適切に設定するには、次のコードを追加する必要があります。

if (tb != NULL) {
  PyException_SetTraceback(val, tb);
}

PyObject *PyErr_GetHandledException(void)¶: 次に属します: Stable ABI (バージョン 3.11 より).
sys.exception() が返すような、現在有効な例外インスタンスを取得します。これは新たに送出された例外ではなく、すでに捕捉された 例外を指します。例外への新しい参照、または NULL を返します。インタープリタの例外状態は変更しません。

注釈

この関数は、通常は例外を扱うコードでは使用されません。正確に言うと、これは例外の状態を一時的に保存し、元に戻す必要があるコードで使用することができます。例外の状態を元に戻す、もしくはクリアするには PyErr_SetHandledException() を使ってください。

Added in version 3.11.

void PyErr_SetHandledException(PyObject *exc)¶: 次に属します: Stable ABI (バージョン 3.11 より).
sys.exception() で得られる、現在有効な例外を設定します。これは新たに送出された例外ではなく、すでに捕捉された 例外を指します。例外状態をクリアするには NULL を渡してください。

注釈

この関数は、通常は例外を扱うコードでは使用されません。正確に言うと、これは例外の状態を一時的に保存し、元に戻す必要があるコードで使用することができます。例外の状態を取得するには PyErr_GetHandledException() を使ってください。

Added in version 3.11.

void PyErr_GetExcInfo(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)¶: 次に属します: Stable ABI (バージョン 3.7 より).
sys.exc_info() で得られる、従来の形式の例外情報を取得します。これは新たに送出された例外ではなく、すでに捕捉された 例外を指します。 3 つのオブジェクトへの新しい参照を返しますが、いずれも NULL の場合があります。例外情報の状態は変更しません。この関数は後方互換性のために残されています。 PyErr_GetHandledException() を使うことを推奨します。

注釈

この関数は、通常は例外を扱うコードでは使用されません。正確に言うと、これは例外の状態を一時的に保存し、元に戻す必要があるコードで使用することができます。例外の状態を元に戻す、もしくはクリアするには PyErr_SetExcInfo() を使ってください。

Added in version 3.3.

void PyErr_SetExcInfo(PyObject *type, PyObject *value, PyObject *traceback)¶: 次に属します: Stable ABI (バージョン 3.7 より).
sys.exc_info() で得られる例外情報を設定します。これは新たに送出された例外ではなく、すでに捕捉された 例外を指します。この関数は引数の参照を「盗みます」。例外状態をクリアするには、3 つの引数すべてに NULL を渡してください。この関数は後方互換性のために残されています。 PyErr_SetHandledException() を使うことを推奨します。

注釈

この関数は、通常は例外を扱うコードでは使用されません。正確に言うと、これは例外の状態を一時的に保存し、元に戻す必要があるコードで使用することができます。例外の状態を取得するには PyErr_GetExcInfo() を使ってください。

Added in version 3.3.

バージョン 3.11 で変更: type 引数と traceback 引数は使われなくなり、NULL にできます。インタープリタはこれらを例外インスタンス (value 引数) から取得するようになりました。この関数は引き続き 3 つの引数すべての参照を「盗みます」。

シグナルハンドリング¶

int PyErr_CheckSignals()¶

次に属します: Stable ABI.

シグナルやデバッガの起動など、Python コードの実行や例外の送出が安全になるまで処理を遅らせていた外部からの割り込みを処理します。

例えば Ctrl-C を押すと、端末は signal.SIGINT シグナルを送信します。この関数は対応する Python のシグナルハンドラを実行します。デフォルトでは KeyboardInterrupt 例外を送出します。

長時間実行する C コードは、人間にとって即座に応答したように見える程度の頻度で PyErr_CheckSignals() を呼び出す必要があります。

現在、この関数が呼び出すハンドラには以下があります:

signal モジュールで登録した Python 関数などのシグナルハンドラ。

シグナルハンドラを実行するのは、メインインタープリタのメインスレッドだけです。

(これが関数名の由来です。もともと、インタープリタに割り込む方法はシグナルだけでした。)
必要に応じてガベージコレクタを実行します。
実行待ちのリモートデバッガスクリプトを実行します。
PyThreadState_SetAsyncExc() で設定された例外を送出します。

いずれかのハンドラが例外を送出すると、その例外を設定して直ちに -1 を返します。残りの割り込みは、適切であれば次回の PyErr_CheckSignals() の呼び出しで処理するために残します。

すべてのハンドラが正常に終了した場合や、実行するハンドラがない場合は 0 を返します。

バージョン 3.12 で変更: この関数がガベージコレクタを呼び出す場合があるようになりました。

バージョン 3.14 で変更: リモートデバッグが有効な場合、この関数がリモートデバッガのスクリプトを実行する場合があるようになりました。

バージョン 3.15 で変更: PyThreadState_SetAsyncExc() で設定された例外を送出するようになりました。

void PyErr_SetInterrupt()¶: 次に属します: Stable ABI.
SIGINT シグナルが到達したときの効果をシミュレートします。 PyErr_SetInterruptEx(SIGINT) と等価です。

注釈

この関数は非同期シグナルセーフです。アタッチされたスレッド状態なしでも、C のシグナルハンドラからでも呼び出せます。

int PyErr_SetInterruptEx(int signum)¶

次に属します: Stable ABI (バージョン 3.10 より).

シグナルが到達した効果をシミュレートします。次に PyErr_CheckSignals() が呼ばれたとき、与えられたシグナル番号用の Python のシグナルハンドラが呼び出されます。

この関数は、独自のシグナル処理を設定し、割り込みが要求されたとき (例えばユーザーが Ctrl-C を押して操作を中断するとき) に、Python のシグナルハンドラを期待どおりに呼び出したい C コードから使えます。

指定されたシグナルを Python が処理しない場合 (signal.SIG_DFL または signal.SIG_IGN が設定されている場合)、そのシグナルは無視します。

signum が許されるシグナル番号の範囲外の場合は -1 を返します。それ以外の場合は 0 を返します。この関数がエラーインジケータを変更することはありません。

注釈

この関数は非同期シグナルセーフです。アタッチされたスレッド状態なしでも、C のシグナルハンドラからでも呼び出せます。

Added in version 3.10.

int PySignal_SetWakeupFd(int fd)¶

このユーティリティ関数は、シグナルを受け取ったときにシグナル番号をバイトとして書き込むファイル記述子を指定します。 fd はノンブロッキングでなければなりません。この関数は、1つ前のファイル記述子を返します。

値 -1 を渡すと、この機能を無効にします; これが初期状態です。この関数は Python の signal.set_wakeup_fd() と同等ですが、どんなエラーチェックも行いません。 fd は有効なファイル記述子であるべきです。この関数はメインスレッドからのみ呼び出されるべきです。

バージョン 3.5 で変更: Windowsで、この関数はソケットハンドルをサポートするようになりました。

例外クラス¶

PyObject *PyErr_NewException(const char *name, PyObject *base, PyObject *dict)¶

戻り値: 新しい参照。 次に属します: Stable ABI.

このユーティリティ関数は、新しい例外クラスを作成して返します。 name 引数は新しい例外の名前で、module.classname 形式の C 文字列でなければなりません。 base 引数と dict 引数は通常 NULL です。これにより Exception (C では PyExc_Exception としてアクセスできます) から派生したクラスオブジェクトを作成します。

新しいクラスの __module__ 属性には name 引数の先頭部分 (最後のドットまで) を設定し、クラス名には末尾の部分 (最後のドットの後) を設定します。 base 引数を使うと別の基底クラスを指定でき、クラスを 1 つ、またはクラスのタプルを渡せます。 dict 引数を使うと、クラス変数とメソッドの辞書を指定できます。

PyObject *PyErr_NewExceptionWithDoc(const char *name, const char *doc, PyObject *base, PyObject *dict)¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
PyErr_NewException() とほぼ同じですが、新しい例外クラスに簡単に docstring を設定できます。 doc が NULL で無い場合、それが例外クラスの docstring になります。

Added in version 3.2.

int PyExceptionClass_Check(PyObject *ob)¶: ob が例外クラスならゼロ以外、それ以外ならゼロを返します。この関数は常に成功します。

const char *PyExceptionClass_Name(PyObject *ob)¶: 次に属します: Stable ABI (バージョン 3.8 より).
例外クラス ob の tp_name を返します。

PyException_HEAD¶

例外オブジェクトの基本的なフィールドを含むマクロです。

これは誤って Python の C API に含まれたもので、拡張モジュールで使うための設計にはなっていません。独自の例外オブジェクトを作成するには、PyErr_NewException() を使うか、他の方法で PyExc_BaseException を継承するクラスを作成してください。

バージョン 3.15 でソフト非推奨 <Soft deprecated>.

例外オブジェクト¶

int PyExceptionInstance_Check(PyObject *op)¶: op が BaseException のインスタンスなら真、それ以外なら偽を返します。この関数は常に成功します。

PyExceptionInstance_Class(op)¶: Py_TYPE(op) と等価です。

PyObject *PyException_GetTraceback(PyObject *ex)¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
Python で __traceback__ 属性からアクセスできるものと同じ、例外に関する traceback の新しい参照を返します。関係する traceback が無い場合は、 NULL を返します。

int PyException_SetTraceback(PyObject *ex, PyObject *tb)¶: 次に属します: Stable ABI.
その例外に関する traceback に tb をセットします。クリアするには Py_None を使用してください。

PyObject *PyException_GetContext(PyObject *ex)¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
例外に関連づけられたコンテキスト (ex が送出された時点で処理中だった別の例外インスタンス) への新しい参照を返します。 Python の __context__ 属性からアクセスできるものと同じです。関連づけられたコンテキストがなければ NULL を返します。

void PyException_SetContext(PyObject *ex, PyObject *ctx)¶: 次に属します: Stable ABI.
例外に関連づけるコンテキストを ctx に設定します。クリアするには NULL を使ってください。 ctx が例外インスタンスかどうかの型チェックは行いません。この関数は ctx への参照を「盗みます」。

PyObject *PyException_GetCause(PyObject *ex)¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
Return the cause (either an exception instance, or None, set by raise ... from ...) associated with the exception as a new reference, as accessible from Python through the __cause__ attribute.

void PyException_SetCause(PyObject *ex, PyObject *cause)¶

次に属します: Stable ABI.

例外に関連づける原因を cause に設定します。クリアするには NULL を使ってください。 cause が例外インスタンスまたは None かどうかの型チェックは行いません。この関数は cause への参照を「盗みます」。

この関数は __suppress_context__ 属性を暗黙に True に設定します。

PyObject *PyException_GetArgs(PyObject *ex)¶: 戻り値: 新しい参照。 次に属します: Stable ABI (バージョン 3.12 より).
例外 ex の args を返します。

void PyException_SetArgs(PyObject *ex, PyObject *args)¶: 次に属します: Stable ABI (バージョン 3.12 より).
例外 ex の args を args に設定します。

PyObject *PyUnstable_Exc_PrepReraiseStar(PyObject *orig, PyObject *excs)¶: これは Unstable APIです。マイナーリリースで予告なく変更されることがあります。

Implement part of the interpreter's implementation of except*. orig is the original exception that was caught, and excs is the list of the exceptions that need to be raised. This list contains the unhandled part of orig, if any, as well as the exceptions that were raised from the except* clauses (so they have a different traceback from orig) and those that were reraised (and have the same traceback as orig). Return the ExceptionGroup that needs to be reraised in the end, or None if there is nothing to reraise.

Added in version 3.12.

Unicode 例外オブジェクト¶

以下の関数は C言語から Unicode 例外を作ったり修正したりするために利用します。

PyObject *PyUnicodeDecodeError_Create(const char *encoding, const char *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
encoding, object, length, start, end, reason 属性をもった UnicodeDecodeError オブジェクトを作成します。 encoding および reason は UTF-8 エンコードされた文字列です。

PyObject *PyUnicodeDecodeError_GetEncoding(PyObject *exc)¶
PyObject *PyUnicodeEncodeError_GetEncoding(PyObject *exc)¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
与えられた例外オブジェクトの encoding 属性を返します。

PyObject *PyUnicodeDecodeError_GetObject(PyObject *exc)¶
PyObject *PyUnicodeEncodeError_GetObject(PyObject *exc)¶
PyObject *PyUnicodeTranslateError_GetObject(PyObject *exc)¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
与えられた例外オブジェクトの object 属性を返します。

int PyUnicodeDecodeError_GetStart(PyObject *exc, Py_ssize_t *start)¶

int PyUnicodeEncodeError_GetStart(PyObject *exc, Py_ssize_t *start)¶

int PyUnicodeTranslateError_GetStart(PyObject *exc, Py_ssize_t *start)¶

次に属します: Stable ABI.

渡された例外オブジェクトから start 属性を取得して *start に格納します。start は NULL であってはなりません。成功したら 0 を、失敗したら -1 を返します。

UnicodeError.object が空のシーケンスであれば、結果の start は 0 です。それ以外の場合は [0, len(object) - 1] の範囲に収まるように調整します。

参考

UnicodeError.start

int PyUnicodeDecodeError_SetStart(PyObject *exc, Py_ssize_t start)¶
int PyUnicodeEncodeError_SetStart(PyObject *exc, Py_ssize_t start)¶
int PyUnicodeTranslateError_SetStart(PyObject *exc, Py_ssize_t start)¶: 次に属します: Stable ABI.
指定された例外オブジェクトの start 属性を start に設定します。成功すると 0、失敗すると -1 を返します。

注釈

負の start を渡しても例外は送出しませんが、対応する取得関数はそれを相対オフセットとして扱いません。

int PyUnicodeDecodeError_GetEnd(PyObject *exc, Py_ssize_t *end)¶

int PyUnicodeEncodeError_GetEnd(PyObject *exc, Py_ssize_t *end)¶

int PyUnicodeTranslateError_GetEnd(PyObject *exc, Py_ssize_t *end)¶

次に属します: Stable ABI.

渡された例外オブジェクトから end 属性を取得して *end に格納します。end は NULL であってはなりません。成功したら 0 を、失敗したら -1 を返します。

UnicodeError.object が空のシーケンスであれば、結果の end は 0 です。それ以外の場合は [1, len(object)] の範囲に収まるように調整します。

int PyUnicodeDecodeError_SetEnd(PyObject *exc, Py_ssize_t end)¶
int PyUnicodeEncodeError_SetEnd(PyObject *exc, Py_ssize_t end)¶
int PyUnicodeTranslateError_SetEnd(PyObject *exc, Py_ssize_t end)¶: 次に属します: Stable ABI.
渡された例外オブジェクトの end 属性を end に設定します。成功したら 0 を、失敗したら -1 を返します。

参考

UnicodeError.end

PyObject *PyUnicodeDecodeError_GetReason(PyObject *exc)¶
PyObject *PyUnicodeEncodeError_GetReason(PyObject *exc)¶
PyObject *PyUnicodeTranslateError_GetReason(PyObject *exc)¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
渡された例外オブジェクトの reason 属性を返します。

int PyUnicodeDecodeError_SetReason(PyObject *exc, const char *reason)¶
int PyUnicodeEncodeError_SetReason(PyObject *exc, const char *reason)¶
int PyUnicodeTranslateError_SetReason(PyObject *exc, const char *reason)¶: 次に属します: Stable ABI.
渡された例外オブジェクトの reason 属性を reason に設定します。成功したら 0 を、失敗したら -1 を返します。

再帰の管理¶

次の 2 つの関数は、コアと拡張モジュールの両方で、C レベルの再帰呼び出しを安全に行う方法を提供します。再帰するコードが、再帰の深さを自動的に追跡する Python コードを必ずしも呼び出さない場合に必要です。また、tp_call の実装では呼び出しプロトコルが再帰を管理するため、これらの関数は不要です。

int Py_EnterRecursiveCall(const char *where)¶

次に属します: Stable ABI (バージョン 3.9 より).

C レベルの再帰呼び出しをしようとしているところに印を付けます。

この関数はスタックの上限に達したか確認します。達していれば RecursionError を設定し、ゼロ以外の値を返します。それ以外の場合はゼロを返します。

この検査は呼び出し回数ではなく、現在のスレッドの C スタックの残り領域に基づくため、Py_SetRecursionLimit() や sys.setrecursionlimit() の影響を受けません。

where は " in instance check" のような UTF-8 エンコードされた文字列にして、再帰の深さの限界に達したことで送出される RecursionError のメッセージに連結できるようにすべきです。

参考

PyUnstable_ThreadState_SetStackProtection() 関数。

バージョン 3.9 で変更: この関数が制限付き API でも利用できるようになりました。

バージョン 3.14 で変更: この検査は C スタックの残り領域に基づくようになりました。以前は C レベルの呼び出し回数を数える別のカウンタを使っていました。

void Py_LeaveRecursiveCall(void)¶: 次に属します: Stable ABI (バージョン 3.9 より).
Py_EnterRecursiveCall() を終了させます。 Py_EnterRecursiveCall() の 成功した 呼び出しに対し 1 回呼ばなければなりません。

バージョン 3.9 で変更: この関数が制限付き API でも利用できるようになりました。

コンテナ型の tp_repr を正しく実装するには、特別な再帰処理が必要です。 tp_repr はスタックを保護するだけでなく、循環を防ぐためにオブジェクトも追跡する必要があります。次の 2 つの関数はこの機能の実装を助けます。実質的に、@reprlib.recursive_repr の C 版に相当します。

int Py_ReprEnter(PyObject *object)¶

次に属します: Stable ABI.

循環処理を検知するために、 tp_repr の実装の先頭で呼び出します。

そのオブジェクトが既に処理されたものだった場合、この関数は正の整数を返します。その場合、 tp_repr の実装は、循環を示す文字列オブジェクトを返すべきです。例えば、 dict オブジェクトは {...} を返しますし、 list オブジェクトは [...] を返します。

再帰回数の上限に達した場合は、この関数は負の整数を返します。この場合、 tp_repr の実装は一般的には NULL を返すべきです。

それ以外の場合は、関数はゼロを返し、 tp_repr の実装は通常どおり処理を続けてかまいません。

void Py_ReprLeave(PyObject *object)¶: 次に属します: Stable ABI.
Py_ReprEnter() を終了させます。 0 を返した Py_ReprEnter() の呼び出しに対し 1 回呼ばなければなりません。

int Py_GetRecursionLimit(void)¶

次に属します: Stable ABI.

現在のインタープリタの再帰の上限を取得します。この上限は Py_SetRecursionLimit() で設定できます。再帰の上限は、Python インタープリタのスタックが無限に大きくなることを防ぎます。

この関数は失敗しません。呼び出し側にはアタッチされたスレッド状態が必要です。

参考

sys.getrecursionlimit()

void Py_SetRecursionLimit(int new_limit)¶

次に属します: Stable ABI.

現在のインタープリタの再帰の上限を設定します。

この関数は失敗しません。呼び出し側にはアタッチされたスレッド状態が必要です。

参考

sys.setrecursionlimit()

例外と警告の型¶

Python のすべての標準の例外と警告カテゴリは、PyExc_ に Python の例外名を続けた名前のグローバル変数として利用できます。これらの型は PyObject* で、すべてクラスオブジェクトです。

すべての変数を以下に示します:

例外の型¶

これらのポインタは、S.ABI 列のバージョン以降 (列が空なら 3.2 以降)、安定 ABI の一部です。 N/A と記された例外は、安定 ABI の一部では ありません。

C での名前	S.ABI	Python での名前
PyObject *PyExc_BaseException¶		`BaseException`
PyObject *PyExc_BaseExceptionGroup¶	3.11	`BaseExceptionGroup`
PyObject *PyExc_Exception¶		`Exception`
PyObject *PyExc_ArithmeticError¶		`ArithmeticError`
PyObject *PyExc_AssertionError¶		`AssertionError`
PyObject *PyExc_AttributeError¶		`AttributeError`
PyObject *PyExc_BlockingIOError¶	3.7	`BlockingIOError`
PyObject *PyExc_BrokenPipeError¶	3.7	`BrokenPipeError`
PyObject *PyExc_BufferError¶		`BufferError`
PyObject *PyExc_ChildProcessError¶	3.7	`ChildProcessError`
PyObject *PyExc_ConnectionAbortedError¶	3.7	`ConnectionAbortedError`
PyObject *PyExc_ConnectionError¶	3.7	`ConnectionError`
PyObject *PyExc_ConnectionRefusedError¶	3.7	`ConnectionRefusedError`
PyObject *PyExc_ConnectionResetError¶	3.7	`ConnectionResetError`
PyObject *PyExc_EOFError¶		`EOFError`
PyObject *PyExc_FileExistsError¶	3.7	`FileExistsError`
PyObject *PyExc_FileNotFoundError¶	3.7	`FileNotFoundError`
PyObject *PyExc_FloatingPointError¶		`FloatingPointError`
PyObject *PyExc_GeneratorExit¶		`GeneratorExit`
PyObject *PyExc_ImportCycleError¶	N/A	`ImportCycleError`
PyObject *PyExc_ImportError¶		`ImportError`
PyObject *PyExc_IndentationError¶		`IndentationError`
PyObject *PyExc_IndexError¶		`IndexError`
PyObject *PyExc_InterruptedError¶	3.7	`InterruptedError`
PyObject *PyExc_IsADirectoryError¶	3.7	`IsADirectoryError`
PyObject *PyExc_KeyError¶		`KeyError`
PyObject *PyExc_KeyboardInterrupt¶		`KeyboardInterrupt`
PyObject *PyExc_LookupError¶		`LookupError`
PyObject *PyExc_MemoryError¶		`MemoryError`
PyObject *PyExc_ModuleNotFoundError¶	3.6	`ModuleNotFoundError`
PyObject *PyExc_NameError¶		`NameError`
PyObject *PyExc_NotADirectoryError¶	3.7	`NotADirectoryError`
PyObject *PyExc_NotImplementedError¶		`NotImplementedError`
PyObject *PyExc_OSError¶		`OSError`
PyObject *PyExc_OverflowError¶		`OverflowError`
PyObject *PyExc_PermissionError¶	3.7	`PermissionError`
PyObject *PyExc_ProcessLookupError¶	3.7	`ProcessLookupError`
PyObject *PyExc_PythonFinalizationError¶		`PythonFinalizationError`
PyObject *PyExc_RecursionError¶	3.7	`RecursionError`
PyObject *PyExc_ReferenceError¶		`ReferenceError`
PyObject *PyExc_RuntimeError¶		`RuntimeError`
PyObject *PyExc_StopAsyncIteration¶	3.7	`StopAsyncIteration`
PyObject *PyExc_StopIteration¶		`StopIteration`
PyObject *PyExc_SyntaxError¶		`SyntaxError`
PyObject *PyExc_SystemError¶		`SystemError`
PyObject *PyExc_SystemExit¶		`SystemExit`
PyObject *PyExc_TabError¶		`TabError`
PyObject *PyExc_TimeoutError¶	3.7	`TimeoutError`
PyObject *PyExc_TypeError¶		`TypeError`
PyObject *PyExc_UnboundLocalError¶		`UnboundLocalError`
PyObject *PyExc_UnicodeDecodeError¶		`UnicodeDecodeError`
PyObject *PyExc_UnicodeEncodeError¶		`UnicodeEncodeError`
PyObject *PyExc_UnicodeError¶		`UnicodeError`
PyObject *PyExc_UnicodeTranslateError¶		`UnicodeTranslateError`
PyObject *PyExc_ValueError¶		`ValueError`
PyObject *PyExc_ZeroDivisionError¶		`ZeroDivisionError`

Added in version 3.3: PyExc_BlockingIOError 、 PyExc_BrokenPipeError 、 PyExc_ChildProcessError 、 PyExc_ConnectionError 、 PyExc_ConnectionAbortedError 、 PyExc_ConnectionRefusedError 、 PyExc_ConnectionResetError 、 PyExc_FileExistsError 、 PyExc_FileNotFoundError 、 PyExc_InterruptedError 、 PyExc_IsADirectoryError 、 PyExc_NotADirectoryError 、 PyExc_PermissionError 、 PyExc_ProcessLookupError 、 PyExc_TimeoutError は PEP 3151 により導入されました。

Added in version 3.5: PyExc_StopAsyncIteration および PyExc_RecursionError 。

Added in version 3.6: PyExc_ModuleNotFoundError.

Added in version 3.11: PyExc_BaseExceptionGroup.

OSError の別名¶

以下は互換性のための PyExc_OSError の別名です。

バージョン 3.3 で変更: これらの別名は、以前はそれぞれ独立した例外型でした。

C での名前	Python での名前	注釈
PyObject PyExc_EnvironmentError¶ 次に属します: Stable ABI.*	`OSError`
PyObject PyExc_IOError¶ 次に属します: Stable ABI.*	`OSError`
PyObject PyExc_WindowsError¶ 次に属します: Stable ABI on Windows (バージョン 3.7 より).*	`OSError`	[win]

注釈:

[win]

PyExc_WindowsError は Windows でのみ定義されます。これを使うコードは、プリプロセッサマクロ MS_WINDOWS が定義されているか検査して保護してください。

警告の型¶

これらのポインタは、S.ABI 列のバージョン以降 (列が空なら 3.2 以降)、安定 ABI の一部です。

C での名前	S.ABI	Python での名前
PyObject *PyExc_Warning¶		`Warning`
PyObject *PyExc_BytesWarning¶		`BytesWarning`
PyObject *PyExc_DeprecationWarning¶		`DeprecationWarning`
PyObject *PyExc_EncodingWarning¶	3.10	`EncodingWarning`
PyObject *PyExc_FutureWarning¶		`FutureWarning`
PyObject *PyExc_ImportWarning¶		`ImportWarning`
PyObject *PyExc_PendingDeprecationWarning¶		`PendingDeprecationWarning`
PyObject *PyExc_ResourceWarning¶	3.7	`ResourceWarning`
PyObject *PyExc_RuntimeWarning¶		`RuntimeWarning`
PyObject *PyExc_SyntaxWarning¶		`SyntaxWarning`
PyObject *PyExc_UnicodeWarning¶		`UnicodeWarning`
PyObject *PyExc_UserWarning¶		`UserWarning`

Added in version 3.2: PyExc_ResourceWarning.

Added in version 3.10: PyExc_EncodingWarning.

トレースバック¶

PyTypeObject PyTraceBack_Type¶: 次に属します: Stable ABI.
トレースバックオブジェクトの型オブジェクトです。 Python レイヤでは types.TracebackType として利用できます。

int PyTraceBack_Check(PyObject *op)¶: op がトレースバックオブジェクトなら真、それ以外なら偽を返します。この関数はサブタイプを考慮しません。

int PyTraceBack_Here(PyFrameObject *f)¶

次に属します: Stable ABI.

現在の例外の __traceback__ 属性を、既存の連鎖の先頭に f を追加した新しいトレースバックに置き換えます。

例外が設定されていない状態でこの関数を呼び出すと、動作は未定義です。

この関数は成功すると 0、失敗すると例外を設定して -1 を返します。

int PyTraceBack_Print(PyObject *tb, PyObject *f)¶

次に属します: Stable ABI.

トレースバック tb をファイル f に書き込みます。

この関数は成功すると 0、失敗すると例外を設定して -1 を返します。

const char *PyUnstable_DumpTraceback(int fd, PyThreadState *tstate)¶

これは Unstable APIです。マイナーリリースで予告なく変更されることがあります。

tstate の Python スタックのトレースをファイル fd に書き込みます。形式は次のようになります。

Traceback (most recent call first):
  File "xxx", line xxx in <xxx>
  File "xxx", line xxx in <xxx>
  ...
  File "xxx", line xxx in <xxx>

この関数は、セグメンテーション違反や致命的なエラーなどの状況をデバッグするためのものです。出力するファイル名と関数名は backslashreplace で ASCII にエンコードし、500 文字で切り詰めます。最初の 100 フレームだけを書き込み、それ以降のフレームは ... という行で省略します。

この関数は成功すると NULL、エラー時にはエラーメッセージを返します。

この関数は、インタープリタが不整合な状態になっている可能性のある、SIGSEGV のシグナルハンドラなどのクラッシュ時の状況で使うことを想定しています。変更の途中かもしれないインタープリタのデータ構造を読み取るため、出力が不完全になる可能性があり、関数自体がクラッシュすることもあります。

呼び出し側にアタッチされたスレッド状態は不要で、tstate がアタッチされている必要もありません。

Added in version 3.15.

const char *PyUnstable_DumpTracebackThreads(int fd, PyInterpreterState *interp, PyThreadState *current_tstate, Py_ssize_t max_threads)¶

これは Unstable APIです。マイナーリリースで予告なく変更されることがあります。

interp のすべての Python スレッドのトレースをファイル fd に書き込みます。

interp が NULL の場合、この関数はスレッド固有の記憶域を使って現在のインタープリタの特定を試みます。特定できなければエラーを返します。

current_tstate が NULL でなければ、出力内で現在のスレッドを示すために使います。 NULL の場合は、スレッド固有の記憶域を使って現在のスレッドを特定します。現在の Python スレッド状態を取得できなくてもエラーにはなりません。

この関数は成功すると NULL、エラー時にはエラーメッセージを返します。

この関数は、セグメンテーション違反や致命的なエラーなどの状況をデバッグするためのものです。各スレッドについて PyUnstable_DumpTraceback() を呼び出します。最初の max_threads 個のスレッドのトレースバックだけを書き込み、それ以降の出力は ... という行で省略します。 max_threads が 0 の場合は、この引数にデフォルト値の 100 を使います。

この関数は、インタープリタが不整合な状態になっている可能性のある、SIGSEGV のシグナルハンドラなどのクラッシュ時の状況で使うことを想定しています。変更の途中かもしれないインタープリタのデータ構造を読み取るため、出力が不完全になる可能性があり、関数自体がクラッシュすることもあります。

呼び出し側にアタッチされたスレッド状態は不要で、current_tstate がアタッチされている必要もありません。

警告

フリースレッドビルドでは、この関数はスレッドセーフではありません。この関数の呼び出し中に別のスレッドが自身のスレッド状態を削除すると、プロセスがクラッシュする可能性が高くなります。

Added in version 3.15.

例外処理¶

出力とクリア¶

例外の送出¶

警告¶

エラーインジケータの問い合わせ¶

シグナルハンドリング¶

例外クラス¶

例外オブジェクト¶

Unicode 例外オブジェクト¶

再帰の管理¶

例外と警告の型¶

例外の型¶

OSError の別名¶

警告の型¶

トレースバック¶

目次

前のトピックへ

次のトピックへ

このページ