例外処理

この章で説明する関数を使うと、 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.

Legacy variant of PyErr_DisplayException().

Print the exception value with its traceback to sys.stderr. If value has no traceback set, tb is used as its traceback. The first argument is ignored.

If sys.stderr is None, nothing is printed. If sys.stderr is not set, the exception is dumped to the C stderr stream instead.

バージョン 3.12 で非推奨: Use PyErr_DisplayException() instead.

例外の送出

以下の関数は、現在のスレッドのエラーインジケータの設定を補助します。利便性のため、これらの関数のいくつかは、 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)

Similar to PyErr_SyntaxLocationObject(), but also sets the end_lineno and end_col_offset information for the current exception.

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)

Get the source line in filename at line lineno. filename should be a Python str object.

On success, this function returns a Python string object with the found line. On failure, this function returns NULL without an exception set.

PyObject *PyErr_ProgramText(const char *filename, int lineno)

次に属します: Stable ABI.

Similar to PyErr_ProgramTextObject(), but filename is a const char*, which is decoded with the filesystem encoding and error handler, instead of a Python object reference.

警告

以下の関数を使い、 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 警告カテゴリは、 Warning types で名前が列挙されているグローバル変数として利用可能です。

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

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.

Function similar to PyErr_WarnEx(), but uses PyUnicode_FromFormat() to format the warning message. format is an ASCII-encoded string.

Added in version 3.2.

int PyErr_WarnExplicitFormat(PyObject *category, const char *filename, int lineno, const char *module, PyObject *registry, const char *format, ...)

Similar to PyErr_WarnExplicit(), but uses PyUnicode_FromFormat() to format the warning message. format is an ASCII-encoded string.

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() する必要はありません。

The caller must hold the GIL.

注釈

戻り値を特定の例外と比較しないでください。その代わりに、下に示す 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 より).

Set exc as the exception currently being raised, clearing the existing exception if one is set. If exc is NULL, just clear the existing exception.

exc must be a valid exception or NULL.

This call "steals" a reference to 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 より).

Set the exception info, as known from sys.exc_info(). This refers to an exception that was already caught, not to an exception that was freshly raised. This function "steals" the references of the arguments. To clear the exception state, pass NULL for all three arguments. This function is kept for backwards compatibility. Prefer using PyErr_SetHandledException().

注釈

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

Added in version 3.3.

バージョン 3.11 で変更: The type and traceback arguments are no longer used and can be NULL. The interpreter now derives them from the exception instance (the value argument). The function still "steals" references of all three arguments.

シグナルハンドリング

int PyErr_CheckSignals()

次に属します: Stable ABI.

Handle external interruptions, such as signals or activating a debugger, whose processing has been delayed until it is safe to run Python code and/or raise exceptions.

For example, pressing Ctrl-C causes a terminal to send the signal.SIGINT signal. This function executes the corresponding Python signal handler, which, by default, raises the KeyboardInterrupt exception.

PyErr_CheckSignals() should be called by long-running C code frequently enough so that the response appears immediate to humans.

Handlers invoked by this function currently include:

• Signal handlers, including Python functions registered using the signal module.

  Signal handlers are only run in the main thread of the main interpreter.

  (This is where the function got the name: originally, signals were the only way to interrupt the interpreter.)

• Running the garbage collector, if necessary.

If any handler raises an exception, immediately return -1 with that exception set. Any remaining interruptions are left to be processed on the next PyErr_CheckSignals() invocation, if appropriate.

If all handlers finish successfully, or there are no handlers to run, return 0.

バージョン 3.12 で変更: This function may now invoke the garbage collector.

void PyErr_SetInterrupt()

次に属します: Stable ABI.

SIGINT シグナルが到達したときの効果をシミュレートします。 PyErr_SetInterruptEx(SIGINT) と等価です。

注釈

This function is async-signal-safe. It can be called without the GIL and from a C signal handler.

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 を返します。 この関数がエラーインジケータを変更することはありません。

注釈

This function is async-signal-safe. It can be called without the GIL and from a C signal handler.

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)

Return non-zero if ob is an exception class, zero otherwise. This function always succeeds.

const char *PyExceptionClass_Name(PyObject *ob)

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

Return tp_name of the exception class ob.

例外オブジェクト

int PyExceptionInstance_Check(PyObject *op)

Return true if op is an instance of BaseException, false otherwise. This function always succeeds.

PyExceptionInstance_Class(op)

Equivalent to 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.

Set the context associated with the exception to ctx. Use NULL to clear it. There is no type check to make sure that ctx is an exception instance. This "steals" a reference to 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.

Set the cause associated with the exception to cause. Use NULL to clear it. There is no type check to make sure that cause is either an exception instance or None. This "steals" a reference to 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 を返します。

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.

Set the start attribute of the given exception object to start. Return 0 on success, -1 on failure.

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 を返します。

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 を返します。

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 レベルの再帰呼び出しをしようとしているところに印を付けます。

If USE_STACKCHECK is defined, this function checks if the OS stack overflowed using PyOS_CheckStack(). If this is the case, it sets a MemoryError and returns a nonzero value.

The function then checks if the recursion limit is reached. If this is the case, a RecursionError is set and a nonzero value is returned. Otherwise, zero is returned.

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

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

void Py_LeaveRecursiveCall(void)

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

Py_EnterRecursiveCall() を終了させます。 Py_EnterRecursiveCall() の 成功した 呼び出しに対し 1 回呼ばなければなりません。

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

Properly implementing tp_repr for container types requires special recursion handling. In addition to protecting the stack, tp_repr also needs to track objects to prevent cycles. The following two functions facilitate this functionality. Effectively, these are the C equivalent to @reprlib.recursive_repr.

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.

Get the recursion limit for the current interpreter. It can be set with Py_SetRecursionLimit(). The recursion limit prevents the Python interpreter stack from growing infinitely.

This function cannot fail, and the caller must hold the GIL.

参考

sys.getrecursionlimit()

void Py_SetRecursionLimit(int new_limit)

次に属します: Stable ABI.

Set the recursion limit for the current interpreter.

This function cannot fail, and the caller must hold the GIL.

参考

sys.setrecursionlimit()

Exception and warning types

All standard Python exceptions and warning categories are available as global variables whose names are PyExc_ followed by the Python exception name. These have the type PyObject*; they are all class objects.

For completeness, here are all the variables:

Exception types

C name	Python name
PyObject *PyExc_BaseException 次に属します: Stable ABI.	BaseException
PyObject *PyExc_BaseExceptionGroup 次に属します: Stable ABI (バージョン 3.11 より).	BaseExceptionGroup
PyObject *PyExc_Exception 次に属します: Stable ABI.	Exception
PyObject *PyExc_ArithmeticError 次に属します: Stable ABI.	ArithmeticError
PyObject *PyExc_AssertionError 次に属します: Stable ABI.	AssertionError
PyObject *PyExc_AttributeError 次に属します: Stable ABI.	AttributeError
PyObject *PyExc_BlockingIOError 次に属します: Stable ABI (バージョン 3.7 より).	BlockingIOError
PyObject *PyExc_BrokenPipeError 次に属します: Stable ABI (バージョン 3.7 より).	BrokenPipeError
PyObject *PyExc_BufferError 次に属します: Stable ABI.	BufferError
PyObject *PyExc_ChildProcessError 次に属します: Stable ABI (バージョン 3.7 より).	ChildProcessError
PyObject *PyExc_ConnectionAbortedError 次に属します: Stable ABI (バージョン 3.7 より).	ConnectionAbortedError
PyObject *PyExc_ConnectionError 次に属します: Stable ABI (バージョン 3.7 より).	ConnectionError
PyObject *PyExc_ConnectionRefusedError 次に属します: Stable ABI (バージョン 3.7 より).	ConnectionRefusedError
PyObject *PyExc_ConnectionResetError 次に属します: Stable ABI (バージョン 3.7 より).	ConnectionResetError
PyObject *PyExc_EOFError 次に属します: Stable ABI.	EOFError
PyObject *PyExc_FileExistsError 次に属します: Stable ABI (バージョン 3.7 より).	FileExistsError
PyObject *PyExc_FileNotFoundError 次に属します: Stable ABI (バージョン 3.7 より).	FileNotFoundError
PyObject *PyExc_FloatingPointError 次に属します: Stable ABI.	FloatingPointError
PyObject *PyExc_GeneratorExit 次に属します: Stable ABI.	GeneratorExit
PyObject *PyExc_ImportError 次に属します: Stable ABI.	ImportError
PyObject *PyExc_IndentationError 次に属します: Stable ABI.	IndentationError
PyObject *PyExc_IndexError 次に属します: Stable ABI.	IndexError
PyObject *PyExc_InterruptedError 次に属します: Stable ABI (バージョン 3.7 より).	InterruptedError
PyObject *PyExc_IsADirectoryError 次に属します: Stable ABI (バージョン 3.7 より).	IsADirectoryError
PyObject *PyExc_KeyError 次に属します: Stable ABI.	KeyError
PyObject *PyExc_KeyboardInterrupt 次に属します: Stable ABI.	KeyboardInterrupt
PyObject *PyExc_LookupError 次に属します: Stable ABI.	LookupError
PyObject *PyExc_MemoryError 次に属します: Stable ABI.	MemoryError
PyObject *PyExc_ModuleNotFoundError 次に属します: Stable ABI (バージョン 3.6 より).	ModuleNotFoundError
PyObject *PyExc_NameError 次に属します: Stable ABI.	NameError
PyObject *PyExc_NotADirectoryError 次に属します: Stable ABI (バージョン 3.7 より).	NotADirectoryError
PyObject *PyExc_NotImplementedError 次に属します: Stable ABI.	NotImplementedError
PyObject *PyExc_OSError 次に属します: Stable ABI.	OSError
PyObject *PyExc_OverflowError 次に属します: Stable ABI.	OverflowError
PyObject *PyExc_PermissionError 次に属します: Stable ABI (バージョン 3.7 より).	PermissionError
PyObject *PyExc_ProcessLookupError 次に属します: Stable ABI (バージョン 3.7 より).	ProcessLookupError
PyObject *PyExc_PythonFinalizationError	PythonFinalizationError
PyObject *PyExc_RecursionError 次に属します: Stable ABI (バージョン 3.7 より).	RecursionError
PyObject *PyExc_ReferenceError 次に属します: Stable ABI.	ReferenceError
PyObject *PyExc_RuntimeError 次に属します: Stable ABI.	RuntimeError
PyObject *PyExc_StopAsyncIteration 次に属します: Stable ABI (バージョン 3.7 より).	StopAsyncIteration
PyObject *PyExc_StopIteration 次に属します: Stable ABI.	StopIteration
PyObject *PyExc_SyntaxError 次に属します: Stable ABI.	SyntaxError
PyObject *PyExc_SystemError 次に属します: Stable ABI.	SystemError
PyObject *PyExc_SystemExit 次に属します: Stable ABI.	SystemExit
PyObject *PyExc_TabError 次に属します: Stable ABI.	TabError
PyObject *PyExc_TimeoutError 次に属します: Stable ABI (バージョン 3.7 より).	TimeoutError
PyObject *PyExc_TypeError 次に属します: Stable ABI.	TypeError
PyObject *PyExc_UnboundLocalError 次に属します: Stable ABI.	UnboundLocalError
PyObject *PyExc_UnicodeDecodeError 次に属します: Stable ABI.	UnicodeDecodeError
PyObject *PyExc_UnicodeEncodeError 次に属します: Stable ABI.	UnicodeEncodeError
PyObject *PyExc_UnicodeError 次に属します: Stable ABI.	UnicodeError
PyObject *PyExc_UnicodeTranslateError 次に属します: Stable ABI.	UnicodeTranslateError
PyObject *PyExc_ValueError 次に属します: Stable ABI.	ValueError
PyObject *PyExc_ZeroDivisionError 次に属します: Stable ABI.	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 aliases

The following are a compatibility aliases to PyExc_OSError.

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

C name	Python name	注釈
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 is only defined on Windows; protect code that uses this by testing that the preprocessor macro MS_WINDOWS is defined.

Warning types

C name	Python name
PyObject *PyExc_Warning 次に属します: Stable ABI.	Warning
PyObject *PyExc_BytesWarning 次に属します: Stable ABI.	BytesWarning
PyObject *PyExc_DeprecationWarning 次に属します: Stable ABI.	DeprecationWarning
PyObject *PyExc_EncodingWarning 次に属します: Stable ABI (バージョン 3.10 より).	EncodingWarning
PyObject *PyExc_FutureWarning 次に属します: Stable ABI.	FutureWarning
PyObject *PyExc_ImportWarning 次に属します: Stable ABI.	ImportWarning
PyObject *PyExc_PendingDeprecationWarning 次に属します: Stable ABI.	PendingDeprecationWarning
PyObject *PyExc_ResourceWarning 次に属します: Stable ABI (バージョン 3.7 より).	ResourceWarning
PyObject *PyExc_RuntimeWarning 次に属します: Stable ABI.	RuntimeWarning
PyObject *PyExc_SyntaxWarning 次に属します: Stable ABI.	SyntaxWarning
PyObject *PyExc_UnicodeWarning 次に属します: Stable ABI.	UnicodeWarning
PyObject *PyExc_UserWarning 次に属します: Stable ABI.	UserWarning

Added in version 3.2: PyExc_ResourceWarning.

Added in version 3.10: PyExc_EncodingWarning.

Tracebacks

PyTypeObject PyTraceBack_Type

次に属します: Stable ABI.

Type object for traceback objects. This is available as types.TracebackType in the Python layer.

int PyTraceBack_Check(PyObject *op)

Return true if op is a traceback object, false otherwise. This function does not account for subtypes.

int PyTraceBack_Here(PyFrameObject *f)

次に属します: Stable ABI.

Replace the __traceback__ attribute on the current exception with a new traceback prepending f to the existing chain.

Calling this function without an exception set is undefined behavior.

This function returns 0 on success, and returns -1 with an exception set on failure.

int PyTraceBack_Print(PyObject *tb, PyObject *f)

次に属します: Stable ABI.

Write the traceback tb into the file f.

This function returns 0 on success, and returns -1 with an exception set on failure.