例外処理—Pythonドキュメント

提供:Dev Guides
< PythonPython/docs/2.7/c-api/exceptions
移動先:案内検索

例外処理

この章で説明する関数を使用すると、Python例外を処理して発生させることができます。 Pythonの例外処理の基本を理解することが重要です。 これは、Unix errno変数のように機能します。最後に発生したエラーのグローバルインジケーター(スレッドごと)があります。 ほとんどの関数は成功時にこれをクリアしませんが、失敗時にエラーの原因を示すように設定します。 ほとんどの関数はエラーインジケータも返します。通常、ポインタを返すことになっている場合は NULL 、整数を返す場合は-1です(例外:PyArg_*()関数は[成功の場合はX193X] 、失敗の場合は0)。

呼び出された関数の一部が失敗したために関数が失敗しなければならない場合、通常、エラーインジケーターは設定されません。 それが呼び出した関数はすでにそれを設定しました。 エラーを処理して例外をクリアするか、保持しているリソース(オブジェクト参照やメモリ割り当てなど)をクリーンアップした後に戻る責任があります。 エラーを処理する準備ができていない場合は、通常どおりしない必要があります。 エラーが原因で戻ってきた場合は、エラーが設定されたことを発信者に示すことが重要です。 エラーが処理されないか、注意深く伝播されない場合、Python / C APIへの追加の呼び出しが意図したとおりに動作せず、不思議な方法で失敗する可能性があります。

エラーインジケータは、Python変数sys.exc_typesys.exc_value、およびsys.exc_tracebackに対応する3つのPythonオブジェクトで構成されています。 API関数は、さまざまな方法でエラーインジケータと対話するために存在します。 スレッドごとに個別のエラーインジケータがあります。

void PyErr_PrintEx(int set_sys_last_vars)

sys.stderrへの標準トレースバックを印刷し、エラーインジケータをクリアします。 ' でない限り、エラーはSystemExitです。 その場合、トレースバックは出力されず、PythonプロセスはSystemExitインスタンスで指定されたエラーコードで終了します。

エラーインジケータが設定されている場合は、この関数をのみで呼び出します。 そうしないと、致命的なエラーが発生します。

set_sys_last_vars がゼロ以外の場合、変数 sys.last_typesys.last_value 、および sys.last_traceback は、タイプ、値に設定されます。印刷された例外のトレースバック。

void PyErr_Print()
PyErr_PrintEx(1)のエイリアス。
PyObject *PyErr_Occurred()

エラーインジケータが設定されているかどうかをテストします。 設定されている場合は、例外 typePyErr_Set*()関数の1つまたは PyErr_Restore()への最後の呼び出しに対する最初の引数)を返します。 設定されていない場合は、 NULL を返します。 戻り値への参照を所有していないため、 Py_DECREF()する必要はありません。

ノート

戻り値を特定の例外と比較しないでください。 以下に示すように、代わりに PyErr_ExceptionMatches()を使用してください。 (クラス例外の場合、例外はクラスではなくインスタンスである可能性があるため、または予期される例外のサブクラスである可能性があるため、比較は簡単に失敗する可能性があります。)

int PyErr_ExceptionMatches(PyObject *exc)
PyErr_GivenExceptionMatches(PyErr_Occurred(), exc)と同等です。 これは、例外が実際に設定されている場合にのみ呼び出す必要があります。 例外が発生していない場合、メモリアクセス違反が発生します。
int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)
give 例外が exc の例外と一致する場合はtrueを返します。 exc がクラスオブジェクトの場合、 give がサブクラスのインスタンスである場合もtrueを返します。 exc がタプルの場合、タプル内の(およびサブタプル内の再帰的な)すべての例外が一致するものを検索されます。
void PyErr_NormalizeException(PyObject **exc, PyObject **val, PyObject **tb)
特定の状況下では、以下の PyErr_Fetch()によって返される値は「正規化されていない」可能性があります。つまり、*excはクラスオブジェクトですが、*valは同じインスタンスではありません。クラス。 その場合、この関数を使用してクラスをインスタンス化できます。 値がすでに正規化されている場合、何も起こりません。 遅延正規化は、パフォーマンスを向上させるために実装されています。
void PyErr_Clear()
エラーインジケータをクリアします。 エラーインジケータが設定されていない場合、効果はありません。
void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)

エラーインジケータを、アドレスが渡される3つの変数に取得します。 エラーインジケータが設定されていない場合は、3つの変数すべてを NULL に設定します。 設定されている場合はクリアされ、取得した各オブジェクトへの参照を所有します。 型オブジェクトがそうでない場合でも、値およびトレースバックオブジェクトは NULL である可能性があります。

ノート

この関数は通常、例外を処理する必要があるコード、またはエラーインジケータを一時的に保存および復元する必要があるコードによってのみ使用されます。

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

3つのオブジェクトからエラーインジケータを設定します。 エラーインジケータがすでに設定されている場合は、最初にクリアされます。 オブジェクトが NULL の場合、エラーインジケータはクリアされます。 NULL タイプおよび非 NULL 値またはトレースバックを渡さないでください。 例外タイプはクラスである必要があります。 無効な例外タイプまたは値を渡さないでください。 (これらのルールに違反すると、後で微妙な問題が発生します。)この呼び出しでは、各オブジェクトへの参照が削除されます。呼び出しの前と呼び出し後に、これらの参照を所有しなくなった場合は、各オブジェクトへの参照を所有する必要があります。 (これがわからない場合は、この機能を使用しないでください。 警告しました。)

ノート

この関数は通常、エラーインジケータを一時的に保存および復元する必要があるコードでのみ使用されます。 PyErr_Fetch()を使用して、現在の例外状態を保存します。

void PyErr_SetString(PyObject *type, const char *message)
これは、エラーインジケータを設定する最も一般的な方法です。 最初の引数は例外タイプを指定します。 これは通常、標準的な例外の1つです。 PyExc_RuntimeError。 参照カウントをインクリメントする必要はありません。 2番目の引数はエラーメッセージです。 文字列オブジェクトに変換されます。
void PyErr_SetObject(PyObject *type, PyObject *value)
この関数は PyErr_SetString()に似ていますが、例外の「値」に任意のPythonオブジェクトを指定できます。
PyObject *PyErr_Format(PyObject *exception, const char *format, ...)
この関数はエラーインジケータを設定し、 NULL を返します。 exception はPython例外クラスである必要があります。 format 以降のパラメーターは、エラーメッセージのフォーマットに役立ちます。 これらは、 PyString_FromFormat()と同じ意味と値を持っています。
void PyErr_SetNone(PyObject *type)
これはPyErr_SetObject(type, Py_None)の省略形です。
int PyErr_BadArgument()
これはPyErr_SetString(PyExc_TypeError, message)の省略形です。ここで、 message は、組み込み操作が不正な引数で呼び出されたことを示します。 これは主に内部使用のためのものです。
PyObject *PyErr_NoMemory()
これはPyErr_SetNone(PyExc_MemoryError)の省略形です。 NULL を返すため、オブジェクト割り当て関数は、メモリが不足したときにreturn PyErr_NoMemory();を書き込むことができます。
PyObject *PyErr_SetFromErrno(PyObject *type)
これは、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)
PyErr_SetFromErrno()と同様ですが、 filenameObjectNULL でない場合、 type のコンストラクターに次のように渡されるという追加の動作があります。 3番目のパラメーター。 IOErrorOSErrorなどの例外の場合、これは例外インスタンスのfilename属性を定義するために使用されます。
PyObject *PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename)
PyErr_SetFromErrnoWithFilenameObject()に似ていますが、ファイル名はC文字列として指定されます。
PyObject *PyErr_SetFromWindowsErr(int ierr)
WindowsErrorを上げるための便利な関数です。 0ierr で呼び出された場合、代わりにGetLastError()の呼び出しによって返されたエラーコードが使用されます。 Win32関数FormatMessage()を呼び出して、 ierr またはGetLastError()で指定されたエラーコードのWindows記述を取得し、最初の項目がであるタプルオブジェクトを作成します。 ierr 値で、2番目の項目が対応するエラーメッセージ(FormatMessage()から取得)である場合、PyErr_SetObject(PyExc_WindowsError, object)を呼び出します。 この関数は常に NULL を返します。 可用性:Windows。
PyObject *PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)

PyErr_SetFromWindowsErr()と同様ですが、発生する例外タイプを指定する追加のパラメーターがあります。 可用性:Windows。

バージョン2.3の新機能。

PyObject *PyErr_SetFromWindowsErrWithFilenameObject(int ierr, PyObject *filenameObject)
PyErr_SetFromWindowsErr()と同様ですが、 filenameObjectNULL でない場合、WindowsErrorのコンストラクターに3番目のパラメーター。 可用性:Windows。
PyObject *PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)
PyErr_SetFromWindowsErrWithFilenameObject()に似ていますが、ファイル名はC文字列として指定されます。 可用性:Windows。
PyObject *PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject *type, int ierr, PyObject *filename)

PyErr_SetFromWindowsErrWithFilenameObject()に似ていますが、発生する例外タイプを指定する追加のパラメーターがあります。 可用性:Windows。

バージョン2.3の新機能。

PyObject *PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, const char *filename)

PyErr_SetFromWindowsErrWithFilename()に似ていますが、発生する例外タイプを指定する追加のパラメーターがあります。 可用性:Windows。

バージョン2.3の新機能。

void PyErr_BadInternalCall()
これはPyErr_SetString(PyExc_SystemError, message)の省略形であり、メッセージは内部操作(例: Python / C API関数)が不正な引数で呼び出されました。 これは主に内部使用のためのものです。
int PyErr_WarnEx(PyObject *category, char *message, int stacklevel)

警告メッセージを発行します。 category 引数は、警告カテゴリ(以下を参照)または NULL です。 message 引数はメッセージ文字列です。 stacklevel は正の数で、スタックフレームの数を示します。 警告は、そのスタックフレームで現在実行中のコード行から発行されます。 1の stacklevel は、 PyErr_WarnEx()を呼び出す関数、2はその上の関数などです。

この関数は通常、警告メッセージを sys.stderr に出力します。 ただし、警告をエラーに変換するようにユーザーが指定した可能性もあります。その場合、例外が発生します。 警告機構の問題が原因で関数が例外を発生させる可能性もあります(実装は警告モジュールをインポートして手間のかかる作業を行います)。 戻り値は、例外が発生しなかった場合は0、例外が発生した場合は-1です。 (警告メッセージが実際に出力されるかどうか、または例外の理由を判別することはできません。これは意図的なものです。)例外が発生した場合、呼び出し元は通常の例外処理を実行する必要があります(たとえば、 Py_DECREF()が所有する参照であり、エラー値を返します)。

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

警告制御の詳細については、 warnings モジュールのドキュメントおよびコマンドラインドキュメントの -W オプションを参照してください。 警告制御用のCAPIはありません。

int PyErr_Warn(PyObject *category, char *message)

警告メッセージを発行します。 category 引数は、警告カテゴリ(以下を参照)または NULL です。 message 引数はメッセージ文字列です。 警告は、 stacklevel を1にして PyErr_WarnEx()を呼び出すのと同じように、 PyErr_Warn()を呼び出す関数から発行されたように見えます。

非推奨。 代わりに PyErr_WarnEx()を使用してください。

int PyErr_WarnExplicit(PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry)
すべての警告属性を明示的に制御して警告メッセージを発行します。 これはPython関数 warnings.warn_explicit()の簡単なラッパーです。詳細については、こちらを参照してください。 module および registry 引数を NULL に設定して、そこに記載されているデフォルトの効果を得ることができます。
int PyErr_WarnPy3k(char *message, int stacklevel)

Py_Py3kWarningFlagフラグが有効になっている場合は、指定されたメッセージおよびスタックレベルDeprecationWarningを発行します。

バージョン2.6の新機能。

int PyErr_CheckSignals()
この関数は、Pythonの信号処理と相互作用します。 シグナルがプロセスに送信されたかどうかをチェックし、送信された場合は、対応するシグナルハンドラーを呼び出します。 signal モジュールがサポートされている場合、Pythonで記述されたシグナルハンドラーを呼び出すことができます。 すべての場合において、SIGINTのデフォルトの効果は、KeyboardInterrupt例外を発生させることです。 例外が発生すると、エラーインジケータが設定され、関数は-1を返します。 それ以外の場合、関数は0を返します。 エラーインジケータは、以前に設定されている場合はクリアされる場合とクリアされない場合があります。
void PyErr_SetInterrupt()
この関数は、到着するSIGINT信号の効果をシミュレートします—次に PyErr_CheckSignals()が呼び出されると、KeyboardInterruptが発生します。 インタプリタロックを保持せずに呼び出すことができます。
int PySignal_SetWakeupFd(int fd)

このユーティリティ関数は、信号を受信するたびに'\0'バイトが書き込まれるファイル記述子を指定します。 以前のそのようなファイル記述子を返します。 値-1は機能を無効にします。 これが初期状態です。 これは、Pythonの signal.set_wakeup_fd()と同等ですが、エラーチェックはありません。 fd は有効なファイル記述子である必要があります。 関数はメインスレッドからのみ呼び出す必要があります。

バージョン2.6の新機能。

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

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

新しいクラスの__module__属性は、 name 引数の最初の部分(最後のドットまで)に設定され、クラス名は最後の部分(最後の後)に設定されますドット)。 base 引数を使用して、代替の基本クラスを指定できます。 1つのクラスのみ、またはクラスのタプルにすることができます。 dict 引数を使用して、クラス変数とメソッドのディクショナリを指定できます。

PyObject *PyErr_NewExceptionWithDoc(char *name, char *doc, PyObject *base, PyObject *dict)

PyErr_NewException()と同じですが、新しい例外クラスにdocstringを簡単に指定できる点が異なります。 docNULL 以外の場合、例外クラスのdocstring。

バージョン2.7の新機能。

void PyErr_WriteUnraisable(PyObject *obj)

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

この関数は、発生不可能な例外が発生したコンテキストを識別する単一の引数 obj で呼び出されます。 可能であれば、 obj のreprが警告メッセージに出力されます。

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)
属性 encodingobjectlengthstartend を使用してUnicodeDecodeErrorオブジェクトを作成します]および理由
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)
属性 encodingobjectlengthstartend を使用してUnicodeEncodeErrorオブジェクトを作成します]および理由
PyObject *PyUnicodeTranslateError_Create(const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
属性 objectlengthstartendreason を使用してUnicodeTranslateErrorオブジェクトを作成します]。
PyObject *PyUnicodeDecodeError_GetEncoding(PyObject *exc)


PyObject *PyUnicodeEncodeError_GetEncoding(PyObject *exc)

指定された例外オブジェクトの encoding 属性を返します。
PyObject *PyUnicodeDecodeError_GetObject(PyObject *exc)


PyObject *PyUnicodeEncodeError_GetObject(PyObject *exc)

PyObject *PyUnicodeTranslateError_GetObject(PyObject *exc)

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

指定された例外オブジェクトの start 属性を取得し、 * start に配置します。 startNULL であってはなりません。 成功した場合は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)

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

指定された例外オブジェクトの end 属性を取得し、 * end に配置します。 endNULL であってはなりません。 成功した場合は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)

指定された例外オブジェクトの end 属性を end に設定します。 成功した場合は0を返し、失敗した場合は-1を返します。
PyObject *PyUnicodeDecodeError_GetReason(PyObject *exc)


PyObject *PyUnicodeEncodeError_GetReason(PyObject *exc)

PyObject *PyUnicodeTranslateError_GetReason(PyObject *exc)

指定された例外オブジェクトの 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コード(再帰の深さを自動的に追跡する)を呼び出すとは限らない場合に必要です。

int Py_EnterRecursiveCall(const char *where)

再帰的な経営幹部レベルの呼び出しが実行されようとしているポイントをマークします。

USE_STACKCHECKが定義されている場合、この関数は PyOS_CheckStack()を使用してOSスタックがオーバーフローしたかどうかをチェックします。 この場合、MemoryErrorを設定し、ゼロ以外の値を返します。

次に、関数は再帰制限に達しているかどうかを確認します。 この場合、RuntimeErrorが設定され、ゼロ以外の値が返されます。 それ以外の場合は、ゼロが返されます。

ここで、は、再帰深度制限によって発生するRuntimeErrorメッセージに連結される" in instance check"などの文字列である必要があります。

void Py_LeaveRecursiveCall()
Py_EnterRecursiveCall()を終了します。 Py_EnterRecursiveCall()成功呼び出しごとに1回呼び出す必要があります。


標準例外

すべての標準Python例外は、名前がPyExc_の後にPython例外名が続くグローバル変数として使用できます。 これらのタイプはPyObject*です。 それらはすべてクラスオブジェクトです。 完全を期すために、ここにすべての変数があります:

C名 Python名 ノート
PyExc_BaseException BaseException (1), (4)
PyExc_Exception Exception (1)
PyExc_StandardError StandardError (1)
PyExc_ArithmeticError ArithmeticError (1)
PyExc_AssertionError AssertionError
PyExc_AttributeError AttributeError
PyExc_BufferError BufferError
PyExc_EnvironmentError EnvironmentError (1)
PyExc_EOFError EOFError
PyExc_FloatingPointError FloatingPointError
PyExc_GeneratorExit GeneratorExit
PyExc_ImportError ImportError
PyExc_IndentationError IndentationError
PyExc_IndexError IndexError
PyExc_IOError IOError
PyExc_KeyError KeyError
PyExc_KeyboardInterrupt KeyboardInterrupt
PyExc_LookupError LookupError (1)
PyExc_MemoryError MemoryError
PyExc_NameError NameError
PyExc_NotImplementedError NotImplementedError
PyExc_OSError OSError
PyExc_OverflowError OverflowError
PyExc_ReferenceError ReferenceError (2)
PyExc_RuntimeError RuntimeError
PyExc_StopIteration StopIteration
PyExc_SyntaxError SyntaxError
PyExc_SystemError SystemError
PyExc_SystemExit SystemExit
PyExc_TabError TabError
PyExc_TypeError TypeError
PyExc_UnboundLocalError UnboundLocalError
PyExc_UnicodeDecodeError UnicodeDecodeError
PyExc_UnicodeEncodeError UnicodeEncodeError
PyExc_UnicodeError UnicodeError
PyExc_UnicodeTranslateError UnicodeTranslateError
PyExc_VMSError VMSError (5)
PyExc_ValueError ValueError
PyExc_WindowsError WindowsError (3)
PyExc_ZeroDivisionError ZeroDivisionError

ノート:

  1. これは、他の標準例外の基本クラスです。

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

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

  4. バージョン2.5の新機能。

  5. VMSでのみ定義されています。 プリプロセッサマクロ__VMSが定義されていることをテストして、これを使用するコードを保護します。


標準の警告カテゴリ

すべての標準Python警告カテゴリは、名前がPyExc_の後にPython例外名が続くグローバル変数として使用できます。 これらのタイプはPyObject*です。 それらはすべてクラスオブジェクトです。 完全を期すために、ここにすべての変数があります:

C名 Python名 ノート
PyExc_Warning Warning (1)
PyExc_BytesWarning BytesWarning
PyExc_DeprecationWarning DeprecationWarning
PyExc_FutureWarning FutureWarning
PyExc_ImportWarning ImportWarning
PyExc_PendingDeprecationWarning PendingDeprecationWarning
PyExc_RuntimeWarning RuntimeWarning
PyExc_SyntaxWarning SyntaxWarning
PyExc_UnicodeWarning UnicodeWarning
PyExc_UserWarning UserWarning

ノート:

  1. これは、他の標準的な警告カテゴリの基本クラスです。


文字列の例外

バージョン2.6で変更:発生またはキャッチされるすべての例外は、BaseExceptionから派生する必要があります。 文字列例外を発生させようとすると、TypeErrorが発生するようになりました。