例外処理

The functions described in this chapter will let you handle and raise Python exceptions. It is important to understand some of the basics of Python exception handling. It works somewhat like the POSIX errno variable: there is a global indicator (per thread) of the last error that occurred. Most C API functions don't clear this on success, but will set it to indicate the cause of the error on failure. Most C API functions also return an error indicator, usually NULL if they are supposed to return a pointer, or -1 if they return an integer (exception: the PyArg_*() functions return 1 for success and 0 for failure).

Concretely, the error indicator consists of three object pointers: the exception's type, the exception's value, and the traceback object. Any of those pointers can be NULL if non-set (although some combinations are forbidden, for example you can't have a non-NULL traceback if the exception type is NULL).

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

注釈

エラー識別子は sys.exc_info() の結果 ではありません。エラー識別子はまだ捕捉されていない例外 (したがってまだ伝播します) に対応しているのに対し、 sys.exc_info() の結果は捕捉された後の例外を返します (したがってもう伝播しません)。

出力とクリア

void PyErr_Clear()

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

void PyErr_PrintEx(int set_sys_last_vars)

Print a standard traceback to sys.stderr and clear the error indicator. Unless the error is a SystemExit, in that case no traceback is printed and the Python process will exit with the error code specified by the SystemExit instance.

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

set_sys_last_vars が非ゼロであれば、 sys.last_type, sys.last_value, sys.last_traceback 変数が、表示される例外のタイプ、値、トレースバックそれぞれに反映されます。

void PyErr_Print()

PyErr_PrintEx(1) のエイリアスです。

void PyErr_WriteUnraisable(PyObject *obj)

Call sys.unraisablehook() using the current exception and obj argument.

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

発生させられない例外が起きたコンテキストを指し示す単一の引数 obj で関数が呼び出されます。 可能な場合は、 obj の repr 文字列が警告メッセージに出力されます。

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

例外の送出

These functions help you set the current thread's error indicator. For convenience, some of these functions will always return a NULL pointer for use in a return statement.

void PyErr_SetString(PyObject *type, const char *message)

これはエラーインジケータを設定するための最も一般的な方法です。第一引数は例外の型を指定します。通常は標準例外の一つ、例えば PyExc_RuntimeError です。その参照カウントを増加させる必要はありません。第二引数はエラーメッセージで、 'utf-8' からデコードされます。

void PyErr_SetObject(PyObject *type, PyObject *value)

この関数は PyErr_SetString() に似ていますが、例外の "値(value)" として任意のPythonオブジェクトを指定することができます。

PyObject* PyErr_Format(PyObject *exception, const char *format, ...)
Return value: Always NULL.

This function sets the error indicator and returns NULL. exception should be a Python exception class. The format and subsequent parameters help format the error message; they have the same meaning and values as in PyUnicode_FromFormat(). format is an ASCII-encoded string.

PyObject* PyErr_FormatV(PyObject *exception, const char *format, va_list vargs)
Return value: Always NULL.

PyErr_Format() と同じですが、可変長引数の代わりに va_list 引数を受け取ります。

バージョン 3.5 で追加.

void PyErr_SetNone(PyObject *type)

これは PyErr_SetObject(type, Py_None) を省略したものです。

int PyErr_BadArgument()

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

PyObject* PyErr_NoMemory()
Return value: Always NULL.

This is a shorthand for PyErr_SetNone(PyExc_MemoryError); it returns NULL so an object allocation function can write return PyErr_NoMemory(); when it runs out of memory.

PyObject* PyErr_SetFromErrno(PyObject *type)
Return value: Always NULL.

This is a convenience function to raise an exception when a C library function has returned an error and set the C variable errno. It constructs a tuple object whose first item is the integer errno value and whose second item is the corresponding error message (gotten from strerror()), and then calls PyErr_SetObject(type, object). On Unix, when the errno value is EINTR, indicating an interrupted system call, this calls PyErr_CheckSignals(), and if that set the error indicator, leaves it set to that. The function always returns NULL, so a wrapper function around a system call can write return PyErr_SetFromErrno(type); when the system call returns an error.

PyObject* PyErr_SetFromErrnoWithFilenameObject(PyObject *type, PyObject *filenameObject)
Return value: Always NULL.

Similar to PyErr_SetFromErrno(), with the additional behavior that if filenameObject is not NULL, it is passed to the constructor of type as a third parameter. In the case of OSError exception, this is used to define the filename attribute of the exception instance.

PyObject* PyErr_SetFromErrnoWithFilenameObjects(PyObject *type, PyObject *filenameObject, PyObject *filenameObject2)
Return value: Always NULL.

PyErr_SetFromErrnoWithFilenameObject() に似てますが、ファイル名を2つ取る関数が失敗したときに例外を送出するために、2つ目のファイル名オブジェクトを受け取ります。

バージョン 3.4 で追加.

PyObject* PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename)
Return value: Always NULL.

PyErr_SetFromErrnoWithFilenameObject() に似ていますが、ファイル名は C 文字列として与えられます。 filename はファイルシステムのエンコーディング (os.fsdecode()) でデコードされます。

PyObject* PyErr_SetFromWindowsErr(int ierr)
Return value: Always NULL.

This is a convenience function to raise WindowsError. If called with ierr of 0, the error code returned by a call to GetLastError() is used instead. It calls the Win32 function FormatMessage() to retrieve the Windows description of error code given by ierr or GetLastError(), then it constructs a tuple object whose first item is the ierr value and whose second item is the corresponding error message (gotten from FormatMessage()), and then calls PyErr_SetObject(PyExc_WindowsError, object). This function always returns NULL.

利用可能な環境: Windows 。

PyObject* PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)
Return value: Always NULL.

PyErr_SetFromWindowsErr() に似ていますが、送出する例外の型を指定する引数が追加されています。

利用可能な環境: Windows 。

PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)
Return value: Always NULL.

PyErr_SetFromWindowsErrWithFilenameObject() に似ていますが、ファイル名は C 文字列として与えられます。 filename はファイルシステムのエンコーディング (os.fsdecode()) でデコードされます。

利用可能な環境: Windows 。

PyObject* PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject *type, int ierr, PyObject *filename)
Return value: Always NULL.

PyErr_SetFromWindowsErrWithFilenameObject() に似ていますが、送出する例外の型を指定する引数が追加されています。

利用可能な環境: Windows 。

PyObject* PyErr_SetExcFromWindowsErrWithFilenameObjects(PyObject *type, int ierr, PyObject *filename, PyObject *filename2)
Return value: Always NULL.

PyErr_SetExcFromWindowsErrWithFilenameObject() に似てますが、2つ目のファイル名オブジェクトを受け取ります。

利用可能な環境: Windows 。

バージョン 3.4 で追加.

PyObject* PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, const char *filename)
Return value: Always NULL.

PyErr_SetFromWindowsErrWithFilename() に似ていますが、送出する例外の型を指定する引数が追加されています。

利用可能な環境: Windows 。

PyObject* PyErr_SetImportError(PyObject *msg, PyObject *name, PyObject *path)
Return value: Always NULL.

ImportError を簡単に送出するための関数です。 msg は例外のメッセージ文字列としてセットされます。 namepath はどちらも NULL にしてよく、それぞれ ImportErrorname 属性と path 属性としてセットされます。

バージョン 3.3 で追加.

void PyErr_SyntaxLocationObject(PyObject *filename, int lineno, int col_offset)

現在の例外のファイル、行、オフセットの情報をセットします。 現在の例外が SyntaxError でない場合は、例外を表示するサブシステムが、例外が SyntaxError であると思えるように属性を追加します。

バージョン 3.4 で追加.

void PyErr_SyntaxLocationEx(const char *filename, int lineno, int col_offset)

PyErr_SyntaxLocationObject() と似ていますが、 filename はファイルシステムのエンコーディングでデコードされた (os.fsdecode()) バイト文字列です。

バージョン 3.2 で追加.

void PyErr_SyntaxLocation(const char *filename, int lineno)

PyErr_SyntaxLocationEx() と似ていますが、 col_offset 引数が除去されています。

void PyErr_BadInternalCall()

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

警告

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

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

Issue a warning message. The category argument is a warning category (see below) or NULL; the message argument is a UTF-8 encoded string. stack_level is a positive number giving a number of stack frames; the warning will be issued from the currently executing line of code in that stack frame. A stack_level of 1 is the function calling PyErr_WarnEx(), 2 is the function above that, and so forth.

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

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

PyObject* PyErr_SetImportErrorSubclass(PyObject *exception, PyObject *msg, PyObject *name, PyObject *path)
Return value: Always NULL.

PyErr_SetImportError() とよく似ていますが、この関数は送出する例外として、 ImportError のサブクラスを指定できます。

バージョン 3.6 で追加.

int PyErr_WarnExplicitObject(PyObject *category, PyObject *message, PyObject *filename, int lineno, PyObject *module, PyObject *registry)

Issue a warning message with explicit control over all warning attributes. This is a straightforward wrapper around the Python function warnings.warn_explicit(), see there for more information. The module and registry arguments may be set to NULL to get the default effect described there.

バージョン 3.4 で追加.

int PyErr_WarnExplicit(PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry)

PyErr_WarnExplicitObject() に似ていますが、 messagemodule が UTF-8 エンコードされた文字列であるところが異なり、 filename はファイルシステムのエンコーディング (os.fsdecode()) でデコードされます。

int PyErr_WarnFormat(PyObject *category, Py_ssize_t stack_level, const char *format, ...)

PyErr_WarnEx() に似たような関数ですが、警告メッセージをフォーマットするのに PyUnicode_FromFormat() を使用します。 format は ASCII にエンコードされた文字列です。

バージョン 3.2 で追加.

int PyErr_ResourceWarning(PyObject *source, Py_ssize_t stack_level, const char *format, ...)

PyErr_WarnFormat() に似た関数で、categoryResourceWarning であり、 sourcewarnings.WarningMessage() に渡されます。

バージョン 3.6 で追加.

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

PyObject* PyErr_Occurred()
Return value: Borrowed reference.

Test whether the error indicator is set. If set, return the exception type (the first argument to the last call to one of the PyErr_Set*() functions or to PyErr_Restore()). If not set, return NULL. You do not own a reference to the return value, so you do not need to Py_DECREF() it.

注釈

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

int PyErr_ExceptionMatches(PyObject *exc)

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

int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)

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

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

Retrieve the error indicator into three variables whose addresses are passed. If the error indicator is not set, set all three variables to NULL. If it is set, it will be cleared and you own a reference to each object retrieved. The value and traceback object may be NULL even when the type object is not.

注釈

通常、この関数は例外を捕捉する必要のあるコードや、エラーインジケータを一時的に保存して復元する必要のあるコードでのみ使います。

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

   /* ... code that might produce other errors ... */

   PyErr_Restore(type, value, traceback);
}
void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback)

Set the error indicator from the three objects. If the error indicator is already set, it is cleared first. If the objects are NULL, the error indicator is cleared. Do not pass a NULL type and non-NULL value or traceback. The exception type should be a class. Do not pass an invalid exception type or value. (Violating these rules will cause subtle problems later.) This call takes away a reference to each object: you must own a reference to each object before the call and after the call you no longer own these references. (If you don't understand this, don't use this function. I warned you.)

注釈

通常、この関数はエラーインジケータを一時的に保存し復元する必要のあるコードでのみ使います。 現在のエラーインジケータを保存するためには PyErr_Fetch() を使ってください。

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

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

注釈

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

if (tb != NULL) {
  PyException_SetTraceback(val, tb);
}
void PyErr_GetExcInfo(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)

Retrieve 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. Returns new references for the three objects, any of which may be NULL. Does not modify the exception info state.

注釈

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

バージョン 3.3 で追加.

void PyErr_SetExcInfo(PyObject *type, PyObject *value, PyObject *traceback)

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. For general rules about the three arguments, see PyErr_Restore().

注釈

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

バージョン 3.3 で追加.

シグナルハンドリング

int PyErr_CheckSignals()

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

void PyErr_SetInterrupt()

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

SIGINT が Python に対処されなかった (signal.SIG_DFL または signal.SIG_IGN に設定されていた) 場合、この関数は何もしません。

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)
Return value: New reference.

This utility function creates and returns a new exception class. The name argument must be the name of the new exception, a C string of the form module.classname. The base and dict arguments are normally NULL. This creates a class object derived from Exception (accessible in C as PyExc_Exception).

新しいクラスの __module__ 属性は name 引数の前半部分(最後のドットまで)に設定され、クラス名は後半部分(最後のドットの後)に設定されます。 base 引数は代わりのベースクラスを指定するために使えます; 一つのクラスでも、クラスのタプルでも構いません。 dict 引数はクラス変数とメソッドの辞書を指定するために使えます。

PyObject* PyErr_NewExceptionWithDoc(const char *name, const char *doc, PyObject *base, PyObject *dict)
Return value: New reference.

Same as PyErr_NewException(), except that the new exception class can easily be given a docstring: If doc is non-NULL, it will be used as the docstring for the exception class.

バージョン 3.2 で追加.

例外オブジェクト

PyObject* PyException_GetTraceback(PyObject *ex)
Return value: New reference.

Return the traceback associated with the exception as a new reference, as accessible from Python through __traceback__. If there is no traceback associated, this returns NULL.

int PyException_SetTraceback(PyObject *ex, PyObject *tb)

その例外に関する traceback に tb をセットします。クリアするには Py_None を使用してください。

PyObject* PyException_GetContext(PyObject *ex)
Return value: New reference.

Return the context (another exception instance during whose handling ex was raised) associated with the exception as a new reference, as accessible from Python through __context__. If there is no context associated, this returns NULL.

void PyException_SetContext(PyObject *ex, PyObject *ctx)

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)
Return value: New reference.

Python で __cause__ 属性からアクセスできるものと同じ、例外に関する原因 (raise ... from ... によってセットされる例外インスタンス、もしくは None) の新しい参照を返します。

void PyException_SetCause(PyObject *ex, PyObject *cause)

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 がセットされます。

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)
Return value: New reference.

encoding, object, length, start, end, reason 属性をもった UnicodeDecodeError オブジェクトを作成します。 encoding および reason は UTF-8 エンコードされた文字列です。

PyObject* PyUnicodeEncodeError_Create(const char *encoding, const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
Return value: New reference.

encoding, object, length, start, end, reason 属性を持った UnicodeEncodeError オブジェクトを作成します。 encoding および reason は UTF-8 エンコードされた文字列です。

PyObject* PyUnicodeTranslateError_Create(const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
Return value: New reference.

object, length, start, end, reason 属性を持った UnicodeTranslateError オブジェクトを作成します。 reason は UTF-8 エンコードされた文字列です。

PyObject* PyUnicodeDecodeError_GetEncoding(PyObject *exc)
PyObject* PyUnicodeEncodeError_GetEncoding(PyObject *exc)
Return value: New reference.

与えられた例外オブジェクトの encoding 属性を返します。

PyObject* PyUnicodeDecodeError_GetObject(PyObject *exc)
PyObject* PyUnicodeEncodeError_GetObject(PyObject *exc)
PyObject* PyUnicodeTranslateError_GetObject(PyObject *exc)
Return value: New reference.

与えられた例外オブジェクトの 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)

Get the start attribute of the given exception object and place it into *start. start must not be NULL. Return 0 on success, -1 on failure.

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)

渡された例外オブジェクトの start 属性を start に設定します。成功したら 0 を、失敗したら -1 を返します。

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)

Get the end attribute of the given exception object and place it into *end. end must not be NULL. Return 0 on success, -1 on failure.

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)

渡された例外オブジェクトの end 属性を end に設定します。成功したら 0 を、失敗したら -1 を返します。

PyObject* PyUnicodeDecodeError_GetReason(PyObject *exc)
PyObject* PyUnicodeEncodeError_GetReason(PyObject *exc)
PyObject* PyUnicodeTranslateError_GetReason(PyObject *exc)
Return value: New reference.

渡された例外オブジェクトの 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)

渡された例外オブジェクトの reason 属性を reason に設定します。成功したら 0 を、失敗したら -1 を返します。

再帰の管理

これら2つの関数は C レベルの再帰呼び出しを安全に実行する方法を、コアモジュールにも拡張モジュールにも提供します。再帰を使ったコードが必ずしも Python コードを実行するわけではない場合 (Python コードは再帰の深さを自動的に追跡します)、これらの関数が必要となります。

int Py_EnterRecursiveCall(const char *where)

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

USE_STACKCHECK が定義されている場合、 OS のスタックがオーバーフローがしたかどうかを PyOS_CheckStack() を使ってチェックします。もしオーバーフローしているなら、 MemoryError をセットしゼロでない値を返します。

次にこの関数は再帰の上限に達していないかをチェックします。 上限に達している場合、 RecursionError をセットしゼロでない値を返します。 そうでない場合はゼロを返します。

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

void Py_LeaveRecursiveCall()

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

コンテナ型に対し tp_repr を適切に実装するには、特殊な再帰の処理が求められます。スタックの防護に加え、 tp_repr は循環処理を避けるためにオブジェクトを辿っていく必要があります。次の 2 つの関数はその機能を容易にします。実質的には、これらは reprlib.recursive_repr() と同等な C の実装です。

int Py_ReprEnter(PyObject *object)

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

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

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

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

void Py_ReprLeave(PyObject *object)

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

標準例外

PyExc_ の後ろにPythonの例外名が続く名前をもつグローバル変数として、すべての標準Python例外が利用可能です。これらは型 PyObject* を持ち、すべてクラスオブジェクトです。完璧を期するために、すべての変数を以下に列挙します:

C名

Python名

注釈

PyExc_BaseException

BaseException

(1)

PyExc_Exception

Exception

(1)

PyExc_ArithmeticError

ArithmeticError

(1)

PyExc_AssertionError

AssertionError

PyExc_AttributeError

AttributeError

PyExc_BlockingIOError

BlockingIOError

PyExc_BrokenPipeError

BrokenPipeError

PyExc_BufferError

BufferError

PyExc_ChildProcessError

ChildProcessError

PyExc_ConnectionAbortedError

ConnectionAbortedError

PyExc_ConnectionError

ConnectionError

PyExc_ConnectionRefusedError

ConnectionRefusedError

PyExc_ConnectionResetError

ConnectionResetError

PyExc_EOFError

EOFError

PyExc_FileExistsError

FileExistsError

PyExc_FileNotFoundError

FileNotFoundError

PyExc_FloatingPointError

FloatingPointError

PyExc_GeneratorExit

GeneratorExit

PyExc_ImportError

ImportError

PyExc_IndentationError

IndentationError

PyExc_IndexError

IndexError

PyExc_InterruptedError

InterruptedError

PyExc_IsADirectoryError

IsADirectoryError

PyExc_KeyError

KeyError

PyExc_KeyboardInterrupt

KeyboardInterrupt

PyExc_LookupError

LookupError

(1)

PyExc_MemoryError

MemoryError

PyExc_ModuleNotFoundError

ModuleNotFoundError

PyExc_NameError

NameError

PyExc_NotADirectoryError

NotADirectoryError

PyExc_NotImplementedError

NotImplementedError

PyExc_OSError

OSError

(1)

PyExc_OverflowError

OverflowError

PyExc_PermissionError

PermissionError

PyExc_ProcessLookupError

ProcessLookupError

PyExc_RecursionError

RecursionError

PyExc_ReferenceError

ReferenceError

(2)

PyExc_RuntimeError

RuntimeError

PyExc_StopAsyncIteration

StopAsyncIteration

PyExc_StopIteration

StopIteration

PyExc_SyntaxError

SyntaxError

PyExc_SystemError

SystemError

PyExc_SystemExit

SystemExit

PyExc_TabError

TabError

PyExc_TimeoutError

TimeoutError

PyExc_TypeError

TypeError

PyExc_UnboundLocalError

UnboundLocalError

PyExc_UnicodeDecodeError

UnicodeDecodeError

PyExc_UnicodeEncodeError

UnicodeEncodeError

PyExc_UnicodeError

UnicodeError

PyExc_UnicodeTranslateError

UnicodeTranslateError

PyExc_ValueError

ValueError

PyExc_ZeroDivisionError

ZeroDivisionError

バージョン 3.3 で追加: PyExc_BlockingIOErrorPyExc_BrokenPipeErrorPyExc_ChildProcessErrorPyExc_ConnectionErrorPyExc_ConnectionAbortedErrorPyExc_ConnectionRefusedErrorPyExc_ConnectionResetErrorPyExc_FileExistsErrorPyExc_FileNotFoundErrorPyExc_InterruptedErrorPyExc_IsADirectoryErrorPyExc_NotADirectoryErrorPyExc_PermissionErrorPyExc_ProcessLookupErrorPyExc_TimeoutErrorPEP 3151 により導入されました。

バージョン 3.5 で追加: PyExc_StopAsyncIteration および PyExc_RecursionError

バージョン 3.6 で追加: PyExc_ModuleNotFoundError.

これらは互換性のある PyExc_OSError のエイリアスです:

C名

注釈

PyExc_EnvironmentError

PyExc_IOError

PyExc_WindowsError

(3)

バージョン 3.3 で変更: これらのエイリアスは例外の種類を分けるために使われます。

注釈:

  1. これは別の標準例外のためのベースクラスです。

  2. これは weakref.ReferenceError と同じです。

  3. Windowsでのみ定義されています。プリプロセッサマクロ MS_WINDOWS が定義されているかテストすることで、これを使うコードを保護してください。

標準警告カテゴリ

PyExc_ の後ろにPythonの例外名が続く名前をもつグローバル変数として、すべての標準Python警告カテゴリが利用可能です。これらは型 PyObject* を持ち、すべてクラスオブジェクトです。完璧を期するために、すべての変数を以下に列挙します:

C名

Python名

注釈

PyExc_Warning

Warning

(1)

PyExc_BytesWarning

BytesWarning

PyExc_DeprecationWarning

DeprecationWarning

PyExc_FutureWarning

FutureWarning

PyExc_ImportWarning

ImportWarning

PyExc_PendingDeprecationWarning

PendingDeprecationWarning

PyExc_ResourceWarning

ResourceWarning

PyExc_RuntimeWarning

RuntimeWarning

PyExc_SyntaxWarning

SyntaxWarning

PyExc_UnicodeWarning

UnicodeWarning

PyExc_UserWarning

UserWarning

バージョン 3.2 で追加: PyExc_ResourceWarning.

注釈:

  1. これは別の標準警告カテゴリのためのベースクラスです。