Обработка исключений¶
Функции, описанные в этой главе, позволят вам обрабатывать и вызывать исключения Python. Важно понять некоторые основы обработки исключений в Python. Она работает примерно так же, как переменная POSIX errno
: существует глобальный индикатор (для каждого потока) последней произошедшей ошибки. Большинство функций C API не очищают его при успехе, но устанавливают его, чтобы указать причину ошибки при неудаче. Большинство функций C API также возвращают индикатор ошибки, обычно NULL
, если они должны возвращать указатель, или -1
, если они возвращают целое число (исключение: функции PyArg_*
возвращают 1
для успеха и 0
для неудачи).
Конкретно, индикатор ошибки состоит из трех указателей на объекты: тип исключения, значение исключения и объект трассировки. Любой из этих указателей может быть NULL
, если он не установлен (хотя некоторые комбинации запрещены, например, вы не можете иметь не``NULL`` traceback, если тип исключения NULL
).
Когда функция должна завершиться неудачей, потому что какая-то вызванная ею функция не справилась с задачей, она обычно не устанавливает индикатор ошибки; вызванная ею функция уже установила его. Она отвечает либо за обработку ошибки и удаление исключения, либо за возврат после очистки всех имеющихся у нее ресурсов (например, ссылок на объекты или выделения памяти); она не должна не продолжать нормальную работу, если не готова обработать ошибку. Если возврат происходит из-за ошибки, важно указать вызывающей стороне, что ошибка была установлена. Если ошибка не будет обработана или тщательно передана, последующие вызовы Python/C API могут повести себя не так, как предполагалось, и завершиться загадочным образом.
Примечание
Индикатор ошибки не является результатом sys.exc_info()
. Первое соответствует исключению, которое еще не поймано (и поэтому продолжает распространяться), а второе возвращает исключение после того, как оно поймано (и поэтому перестало распространяться).
Печать и очистка¶
-
void PyErr_Clear()¶
- Часть Стабильный ABI.
Очистите индикатор ошибки. Если индикатор ошибки не установлен, эффекта не будет.
-
void PyErr_PrintEx(int set_sys_last_vars)¶
- Часть Стабильный ABI.
Выведите стандартный отслеживание в
sys.stderr
и очистите индикатор ошибки. Если ошибка не являетсяSystemExit
, в этом случае трассировка не печатается, а процесс Python завершается с кодом ошибки, указанным в экземпляреSystemExit
.Вызывайте эту функцию только, если установлен индикатор ошибки. В противном случае это приведет к фатальной ошибке!
Если set_sys_last_vars ненулевое, переменная
sys.last_exc
устанавливается в значение выведенного исключения. Для обратной совместимости устаревшие переменныеsys.last_type
,sys.last_value
иsys.last_traceback
также устанавливаются в тип, значение и traceback этого исключения, соответственно.Изменено в версии 3.12: Была добавлена настройка
sys.last_exc
.
-
void PyErr_Print()¶
- Часть Стабильный ABI.
Псевдоним для
PyErr_PrintEx(1)
.
-
void PyErr_WriteUnraisable(PyObject *obj)¶
- Часть Стабильный ABI.
Вызов
sys.unraisablehook()
с использованием текущего исключения и аргумента obj.Эта служебная функция печатает предупреждающее сообщение в
sys.stderr
, когда исключение было задано, но интерпретатор не может его вызвать. Она используется, например, когда исключение возникает в методе__del__()
.Функция вызывается с единственным аргументом obj, который идентифицирует контекст, в котором произошло неустранимое исключение. Если возможно, в предупреждении будет выведено значение obj. Если obj имеет значение
NULL
, выводится только обратная трассировка.При вызове этой функции должно быть установлено исключение.
Изменено в версии 3.4: Вывести обратный след. Выведите только обратный след, если obj равен
NULL
.Изменено в версии 3.8: Используйте
sys.unraisablehook()
.
-
void PyErr_FormatUnraisable(const char *format, ...)¶
Аналогично
PyErr_WriteUnraisable()
, но формат и последующие параметры помогают отформатировать предупреждение; они имеют тот же смысл и значения, что и вPyUnicode_FromFormat()
.PyErr_WriteUnraisable(obj)
примерно эквивалентенPyErr_FormatUnraisable("Exception ignored in: %R", obj)
. Если format равенNULL
, печатается только обратная трассировка.Added in version 3.13.
-
void PyErr_DisplayException(PyObject *exc)¶
- Часть Стабильный ABI с версии 3.12.
Выведите стандартное отображение обратных трассировок от
exc
доsys.stderr
, включая цепочку исключений и заметки.Added in version 3.12.
Воспроизведение исключений¶
Эти функции помогают установить индикатор ошибки текущего потока. Для удобства некоторые из этих функций всегда будут возвращать указатель NULL
для использования в операторе return
.
-
void PyErr_SetString(PyObject *type, const char *message)¶
- Часть Стабильный ABI.
Это наиболее распространенный способ установки индикатора ошибки. Первый аргумент задает тип исключения; обычно это одно из стандартных исключений, например
PyExc_RuntimeError
. Не нужно создавать для него новый strong reference (например, с помощьюPy_INCREF()
). Второй аргумент - сообщение об ошибке; оно декодируется из'utf-8'
.
-
void PyErr_SetObject(PyObject *type, PyObject *value)¶
- Часть Стабильный ABI.
Эта функция похожа на
PyErr_SetString()
, но позволяет указать произвольный объект Python в качестве «значения» исключения.
-
PyObject *PyErr_Format(PyObject *exception, const char *format, ...)¶
- Возвращаемое значение: Всегда NULL. Часть Стабильный ABI.
Эта функция устанавливает индикатор ошибки и возвращает
NULL
. exception должен быть классом исключений Python. Параметр format и последующие параметры помогают отформатировать сообщение об ошибке; они имеют тот же смысл и значения, что и вPyUnicode_FromFormat()
. format - это строка в ASCII-кодировке.
-
PyObject *PyErr_FormatV(PyObject *exception, const char *format, va_list vargs)¶
- Возвращаемое значение: Всегда NULL. Часть Стабильный ABI с версии 3.5.
То же самое, что и
PyErr_Format()
, но принимает аргументva_list
, а не переменное число аргументов.Added in version 3.5.
-
void PyErr_SetNone(PyObject *type)¶
- Часть Стабильный ABI.
Это сокращение для
PyErr_SetObject(type, Py_None)
.
-
int PyErr_BadArgument()¶
- Часть Стабильный ABI.
Это сокращение для
PyErr_SetString(PyExc_TypeError, message)
, где message указывает на то, что встроенная операция была вызвана с недопустимым аргументом. В основном используется для внутренних целей.
-
PyObject *PyErr_NoMemory()¶
- Возвращаемое значение: Всегда NULL. Часть Стабильный ABI.
Это сокращение для
PyErr_SetNone(PyExc_MemoryError)
; оно возвращаетNULL
, чтобы функция выделения объектов могла записатьreturn PyErr_NoMemory();
, когда у нее закончится память.
-
PyObject *PyErr_SetFromErrno(PyObject *type)¶
- Возвращаемое значение: Всегда NULL. Часть Стабильный ABI.
Это удобная функция для создания исключения, когда функция библиотеки C вернула ошибку и установила переменную C
errno
. Она строит кортеж, первым элементом которого является целочисленное значениеerrno
, а вторым - соответствующее сообщение об ошибке (полученное изstrerror()
), а затем вызываетPyErr_SetObject(type, object)
. В Unix, если значениеerrno
равноEINTR
, что указывает на прерванный системный вызов, функция вызываетPyErr_CheckSignals()
и, если при этом был установлен индикатор ошибки, оставляет его таким. Функция всегда возвращаетNULL
, поэтому функция-обертка вокруг системного вызова может записатьreturn PyErr_SetFromErrno(type);
, если системный вызов возвращает ошибку.
-
PyObject *PyErr_SetFromErrnoWithFilenameObject(PyObject *type, PyObject *filenameObject)¶
- Возвращаемое значение: Всегда NULL. Часть Стабильный ABI.
Аналогично
PyErr_SetFromErrno()
, с тем дополнительным поведением, что если filenameObject не являетсяNULL
, то он передается конструктору type в качестве третьего параметра. В случае исключенияOSError
он используется для определения атрибутаfilename
экземпляра исключения.
-
PyObject *PyErr_SetFromErrnoWithFilenameObjects(PyObject *type, PyObject *filenameObject, PyObject *filenameObject2)¶
- Возвращаемое значение: Всегда NULL. Часть Стабильный ABI с версии 3.7.
Аналогично
PyErr_SetFromErrnoWithFilenameObject()
, но принимает второй объект имени файла, чтобы выдать ошибку, когда функция, принимающая два имени файла, не работает.Added in version 3.4.
-
PyObject *PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename)¶
- Возвращаемое значение: Всегда NULL. Часть Стабильный ABI.
Аналогично
PyErr_SetFromErrnoWithFilenameObject()
, но имя файла задается в виде строки C. Имя filename декодируется из filesystem encoding and error handler.
-
PyObject *PyErr_SetFromWindowsErr(int ierr)¶
- Возвращаемое значение: Всегда NULL. Часть Стабильный ABI on Windows с версии 3.7.
Это удобная функция для повышения уровня
OSError
. Если она вызывается с ierr, равным0
, вместо него используется код ошибки, возвращенный вызовомGetLastError()
. Она вызывает функцию Win32FormatMessage()
для получения описания Windows кода ошибки, заданного ierr илиGetLastError()
, затем строит объектOSError
с атрибутомwinerror
, установленным на код ошибки, атрибутомstrerror
, установленным на соответствующее сообщение об ошибке (полученное изFormatMessage()
), и затем вызываетPyErr_SetObject(PyExc_OSError, object)
. Эта функция всегда возвращаетNULL
.Availability: Windows.
-
PyObject *PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)¶
- Возвращаемое значение: Всегда NULL. Часть Стабильный ABI on Windows с версии 3.7.
Аналогично
PyErr_SetFromWindowsErr()
, с дополнительным параметром, указывающим тип исключения, которое должно быть поднято.Availability: Windows.
-
PyObject *PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)¶
- Возвращаемое значение: Всегда NULL. Часть Стабильный ABI on Windows с версии 3.7.
Аналогично
PyErr_SetFromWindowsErr()
, с дополнительным поведением: если filename не являетсяNULL
, оно декодируется из кодировки файловой системы (os.fsdecode()
) и передается конструкторуOSError
в качестве третьего параметра, который используется для определения атрибутаfilename
экземпляра исключения.Availability: Windows.
-
PyObject *PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject *type, int ierr, PyObject *filename)¶
- Возвращаемое значение: Всегда NULL. Часть Стабильный ABI on Windows с версии 3.7.
Аналогично
PyErr_SetExcFromWindowsErr()
, с дополнительным поведением: если filename не являетсяNULL
, оно передается конструкторуOSError
в качестве третьего параметра, который будет использоваться для определения атрибутаfilename
экземпляра исключения.Availability: Windows.
-
PyObject *PyErr_SetExcFromWindowsErrWithFilenameObjects(PyObject *type, int ierr, PyObject *filename, PyObject *filename2)¶
- Возвращаемое значение: Всегда NULL. Часть Стабильный ABI on Windows с версии 3.7.
Аналогично
PyErr_SetExcFromWindowsErrWithFilenameObject()
, но принимает второй объект имени файла.Availability: Windows.
Added in version 3.4.
-
PyObject *PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, const char *filename)¶
- Возвращаемое значение: Всегда NULL. Часть Стабильный ABI on Windows с версии 3.7.
Аналогично
PyErr_SetFromWindowsErrWithFilename()
, с дополнительным параметром, указывающим тип исключения, которое должно быть поднято.Availability: Windows.
-
PyObject *PyErr_SetImportError(PyObject *msg, PyObject *name, PyObject *path)¶
- Возвращаемое значение: Всегда NULL. Часть Стабильный 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. Часть Стабильный 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_SyntaxLocationEx(const char *filename, int lineno, int col_offset)¶
- Часть Стабильный ABI с версии 3.7.
Аналогично
PyErr_SyntaxLocationObject()
, но filename - это байтовая строка, декодированная из filesystem encoding and error handler.Added in version 3.2.
-
void PyErr_SyntaxLocation(const char *filename, int lineno)¶
- Часть Стабильный ABI.
Аналогично
PyErr_SyntaxLocationEx()
, но параметр col_offset опущен.
-
void PyErr_BadInternalCall()¶
- Часть Стабильный ABI.
Это сокращение для
PyErr_SetString(PyExc_SystemError, message)
, где сообщение указывает на то, что внутренняя операция (например, функция API Python/C) была вызвана с недопустимым аргументом. В основном используется для внутреннего использования.
Вынесение предупреждений¶
Используйте эти функции для выдачи предупреждений из кода на Си. Они повторяют аналогичные функции, экспортируемые модулем Python warnings
. Обычно они печатают предупреждение в sys.stderr; однако возможно, что пользователь указал, что предупреждения должны быть превращены в ошибки, и в этом случае они будут вызывать исключение. Также возможно, что функции вызывают исключение из-за проблем с механизмом предупреждений. Возвращаемое значение - 0
, если исключение не возникло, или -1
, если возникло. (Невозможно определить, было ли на самом деле выведено предупреждение или причина исключения; это сделано намеренно). Если исключение возникло, вызывающая сторона должна выполнить свою обычную обработку исключений (например, Py_DECREF()
принадлежит ссылкам и возвращает значение ошибки).
-
int PyErr_WarnEx(PyObject *category, const char *message, Py_ssize_t stack_level)¶
- Часть Стабильный ABI.
Выдать предупреждающее сообщение. Аргумент category - категория предупреждения (см. ниже) или
NULL
; аргумент message - строка в кодировке UTF-8. stack_level - положительное число, указывающее количество фреймов стека; предупреждение будет выдано с текущей выполняющейся строки кода в этом фрейме стека. При stack_level, равном 1, вызывается функцияPyErr_WarnEx()
, 2 - функция, расположенная выше, и так далее.Категории предупреждений должны быть подклассами
PyExc_Warning
;PyExc_Warning
является подклассомPyExc_Exception
; категория предупреждений по умолчанию -PyExc_RuntimeWarning
. Стандартные категории предупреждений Python доступны в виде глобальных переменных, имена которых перечислены в Стандартные категории предупреждений.Информацию об управлении предупреждениями см. в документации по модулю
warnings
и опции-W
в документации по командной строке. API на языке C для управления предупреждениями не существует.
-
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)¶
- Часть Стабильный ABI.
Аналогично
PyErr_WarnExplicitObject()
, за исключением того, что message и module являются строками в кодировке UTF-8, а filename декодируется из filesystem encoding and error handler.
-
int PyErr_WarnFormat(PyObject *category, Py_ssize_t stack_level, const char *format, ...)¶
- Часть Стабильный ABI.
Функция, аналогичная
PyErr_WarnEx()
, но для форматирования предупреждения используйтеPyUnicode_FromFormat()
. формат - это строка в ASCII-кодировке.Added in version 3.2.
-
int PyErr_ResourceWarning(PyObject *source, Py_ssize_t stack_level, const char *format, ...)¶
- Часть Стабильный ABI с версии 3.6.
Функция, аналогичная
PyErr_WarnFormat()
, но категория - этоResourceWarning
, и она передает источник вwarnings.WarningMessage
.Added in version 3.6.
Запрос индикатора ошибок¶
-
PyObject *PyErr_Occurred()¶
- Возвращаемое значение: Заимствованная ссылка. Часть Стабильный ABI.
Проверьте, установлен ли индикатор ошибки. Если установлен, возвращает тип исключения * (первый аргумент последнего вызова одной из функций
PyErr_Set*
илиPyErr_Restore()
). Если не установлен, возвращаетсяNULL
. Вы не владеете ссылкой на возвращаемое значение, поэтому вам не нужноPy_DECREF()
его возвращать.Вызывающий должен удерживать GIL.
Примечание
Не сравнивайте возвращаемое значение с конкретным исключением; вместо этого используйте
PyErr_ExceptionMatches()
, как показано ниже. (Сравнение легко может оказаться неудачным, поскольку в случае исключения класса исключение может быть экземпляром, а не классом, или подклассом ожидаемого исключения).
-
int PyErr_ExceptionMatches(PyObject *exc)¶
- Часть Стабильный ABI.
Эквивалентно
PyErr_GivenExceptionMatches(PyErr_Occurred(), exc)
. Эта функция должна вызываться только тогда, когда исключение действительно установлено; если исключение не было вызвано, произойдет нарушение доступа к памяти.
-
int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)¶
- Часть Стабильный ABI.
Возвращает true, если исключение given соответствует типу исключения в exc. Если exc - объект класса, то возвращается true, если given - экземпляр подкласса. Если exc - кортеж, то поиск совпадения ведется по всем типам исключений в кортеже (и рекурсивно в подкортежах).
-
PyObject *PyErr_GetRaisedException(void)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI с версии 3.12.
Возвращает текущее исключение, очищая при этом индикатор ошибки. Верните
NULL
, если индикатор ошибки не установлен.Эта функция используется кодом, который должен перехватывать исключения, или кодом, который должен временно сохранять и восстанавливать индикатор ошибки.
Например:
{ PyObject *exc = PyErr_GetRaisedException(); /* ... code that might produce other errors ... */ PyErr_SetRaisedException(exc); }
См.также
PyErr_GetHandledException()
, чтобы сохранить обрабатываемое в данный момент исключение.Added in version 3.12.
-
void PyErr_SetRaisedException(PyObject *exc)¶
- Часть Стабильный ABI с версии 3.12.
Устанавливает exc в качестве текущего вызываемого исключения, очищая существующее исключение, если оно было установлено.
Предупреждение
Этот вызов похищает ссылку на exc, которая должна быть корректным исключением.
Added in version 3.12.
-
void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)¶
- Часть Стабильный ABI.
Не рекомендуется, начиная с версии 3.12: Вместо этого используйте
PyErr_GetRaisedException()
.Извлеките индикатор ошибки в три переменные, адреса которых переданы. Если индикатор ошибки не установлен, установите все три переменные в
NULL
. Если он установлен, он будет очищен, и вы станете владельцем ссылки на каждый полученный объект. Объект value и traceback могут бытьNULL
, даже если объект type не установлен.Примечание
Эта функция обычно используется только в унаследованном коде, который должен перехватывать исключения или временно сохранять и восстанавливать индикатор ошибки.
Например:
{ 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)¶
- Часть Стабильный ABI.
Не рекомендуется, начиная с версии 3.12: Вместо этого используйте
PyErr_SetRaisedException()
.Устанавливает индикатор ошибки из трех объектов, type, value и traceback, очищая существующее исключение, если оно было установлено. Если объекты имеют значение
NULL
, индикатор ошибки очищается. Не передавайте типNULL
и не``NULL`` значение или traceback. Тип исключения должен быть классом. Не передавайте недопустимый тип исключения или значение. (Нарушение этих правил приведет к серьезным проблемам в дальнейшем.) Этот вызов забирает ссылку на каждый объект: до вызова вы должны владеть ссылкой на каждый объект, а после вызова вы больше не владеете этими ссылками. (Если вы этого не понимаете, не используйте эту функцию. Я вас предупредил).Примечание
Эта функция обычно используется только в устаревшем коде, которому необходимо временно сохранять и восстанавливать индикатор ошибки. Используйте
PyErr_Fetch()
, чтобы сохранить текущий индикатор ошибки.
-
void PyErr_NormalizeException(PyObject **exc, PyObject **val, PyObject **tb)¶
- Часть Стабильный ABI.
Не рекомендуется, начиная с версии 3.12: Вместо этого используйте
PyErr_GetRaisedException()
, чтобы избежать возможной де-нормализации.При определенных обстоятельствах значения, возвращаемые функцией
PyErr_Fetch()
, могут быть «ненормированными», то есть*exc
является объектом класса, но*val
не является экземпляром того же класса. В этом случае данная функция может быть использована для инстанцирования класса. Если значения уже нормализованы, ничего не произойдет. Отложенная нормализация реализована для повышения производительности.Примечание
Эта функция не неявно устанавливает атрибут
__traceback__
для значения исключения. Если требуется соответствующая установка traceback, то необходимо использовать следующий дополнительный фрагмент:if (tb != NULL) { PyException_SetTraceback(val, tb); }
-
PyObject *PyErr_GetHandledException(void)¶
- Часть Стабильный ABI с версии 3.11.
Получает активный экземпляр исключения, как это было бы возвращено командой
sys.exception()
. Это относится к исключению, которое было уже поймано, а не к только что вызванному исключению. Возвращает новую ссылку на исключение илиNULL
. Не изменяет состояние исключения в интерпретаторе.Примечание
Эта функция обычно не используется кодом, который хочет обрабатывать исключения. Скорее, она может быть использована, когда коду нужно временно сохранить и восстановить состояние исключения. Используйте
PyErr_SetHandledException()
, чтобы восстановить или очистить состояние исключения.Added in version 3.11.
-
void PyErr_SetHandledException(PyObject *exc)¶
- Часть Стабильный ABI с версии 3.11.
Устанавливает активное исключение, известное из
sys.exception()
. Это относится к исключению, которое было уже поймано, а не к только что поднятому исключению. Чтобы очистить состояние исключения, передайтеNULL
.Примечание
Эта функция обычно не используется кодом, который хочет обрабатывать исключения. Скорее, она может быть использована, когда коду нужно временно сохранить и восстановить состояние исключения. Используйте
PyErr_GetHandledException()
, чтобы получить состояние исключения.Added in version 3.11.
-
void PyErr_GetExcInfo(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)¶
- Часть Стабильный ABI с версии 3.7.
Получите представление информации об исключении в старом стиле, как известно из
sys.exc_info()
. Это относится к исключению, которое было уже поймано, а не к только что возникшему исключению. Возвращает новые ссылки на три объекта, любой из которых может бытьNULL
. Не изменяет состояние информации об исключении. Эта функция оставлена для обратной совместимости. Предпочтительнее использоватьPyErr_GetHandledException()
.Примечание
Эта функция обычно не используется кодом, который хочет обрабатывать исключения. Скорее, она может быть использована, когда коду нужно временно сохранить и восстановить состояние исключения. Используйте
PyErr_SetExcInfo()
, чтобы восстановить или очистить состояние исключения.Added in version 3.3.
-
void PyErr_SetExcInfo(PyObject *type, PyObject *value, PyObject *traceback)¶
- Часть Стабильный ABI с версии 3.7.
Устанавливает информацию об исключении, известную из
sys.exc_info()
. Это относится к исключению, которое было уже поймано, а не к только что поднятому исключению. Эта функция крадет ссылки на аргументы. Чтобы очистить состояние исключения, передайтеNULL
для всех трех аргументов. Эта функция оставлена для обратной совместимости. Предпочтительнее использоватьPyErr_SetHandledException()
.Примечание
Эта функция обычно не используется кодом, который хочет обрабатывать исключения. Скорее, она может быть использована, когда коду нужно временно сохранить и восстановить состояние исключения. Используйте
PyErr_GetExcInfo()
, чтобы прочитать состояние исключения.Added in version 3.3.
Изменено в версии 3.11: Аргументы
type
иtraceback
больше не используются и могут быть NULL. Теперь интерпретатор получает их от экземпляра исключения (аргументvalue
). Функция по-прежнему похищает ссылки на все три аргумента.
Обработка сигналов¶
-
int PyErr_CheckSignals()¶
- Часть Стабильный ABI.
Эта функция взаимодействует с обработкой сигналов в Python.
Если функция вызывается из главного потока и под основным интерпретатором Python, она проверяет, был ли отправлен сигнал процессам, и если да, вызывает соответствующий обработчик сигнала. Если поддерживается модуль
signal
, она может вызвать обработчик сигнала, написанный на Python.Функция пытается обработать все ожидающие сигналы, а затем возвращает
0
. Однако если обработчик сигналов Python вызывает исключение, устанавливается индикатор ошибки и функция немедленно возвращает-1
(при этом другие ожидающие сигналы могут быть еще не обработаны: они будут обработаны при следующем вызовеPyErr_CheckSignals()
).Если функция вызывается из неосновного потока или из неосновного интерпретатора Python, она ничего не делает и возвращает
0
.Эта функция может быть вызвана долго выполняющимся кодом на языке C, который хочет быть прерван запросами пользователя (например, нажатием Ctrl-C).
Примечание
Обработчик сигналов Python по умолчанию для
SIGINT
вызывает исключениеKeyboardInterrupt
.
-
void PyErr_SetInterrupt()¶
- Часть Стабильный ABI.
Имитируйте эффект прихода сигнала
SIGINT
. Это эквивалентноPyErr_SetInterruptEx(SIGINT)
.Примечание
Эта функция является async-сигналобезопасной. Ее можно вызывать без GIL и из обработчика сигналов на языке C.
-
int PyErr_SetInterruptEx(int signum)¶
- Часть Стабильный ABI с версии 3.10.
Имитируйте эффект прихода сигнала. При следующем вызове
PyErr_CheckSignals()
будет вызван обработчик сигнала Python для заданного номера сигнала.Эта функция может быть вызвана кодом на языке C, который устанавливает собственную обработку сигналов и хочет, чтобы обработчики сигналов Python вызывались, как ожидалось, при запросе прерывания (например, когда пользователь нажимает Ctrl-C, чтобы прервать операцию).
Если данный сигнал не обрабатывается Python (он был установлен в
signal.SIG_DFL
илиsignal.SIG_IGN
), он будет проигнорирован.Если signum находится вне допустимого диапазона номеров сигналов, возвращается
-1
. В противном случае возвращается0
. Индикатор ошибки никогда не изменяется этой функцией.Примечание
Эта функция является async-сигналобезопасной. Ее можно вызывать без GIL и из обработчика сигналов на языке C.
Added in version 3.10.
-
int PySignal_SetWakeupFd(int fd)¶
Эта служебная функция задает дескриптор файла, в который записывается номер сигнала в виде одного байта при каждом получении сигнала. fd должен быть неблокирующим. Возвращает предыдущий такой дескриптор файла.
Значение
-1
отключает функцию; это начальное состояние. Это эквивалентноsignal.set_wakeup_fd()
в Python, но без проверки ошибок. fd должен быть корректным дескриптором файла. Функция должна вызываться только из главного потока.Изменено в версии 3.5: В Windows эта функция теперь также поддерживает дескрипторы сокетов.
Классы исключений¶
-
PyObject *PyErr_NewException(const char *name, PyObject *base, PyObject *dict)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Эта служебная функция создает и возвращает новый класс исключений. Аргумент name должен быть именем нового исключения, строкой C вида
module.classname
. Аргументы base и dict обычно имеют значениеNULL
. Создается объект класса, производный отException
(доступный в Си какPyExc_Exception
).Атрибут
__module__
нового класса устанавливается в первую часть (до последней точки) аргумента name, а имя класса - в последнюю часть (после последней точки). Аргумент base может использоваться для указания альтернативных базовых классов; это может быть как один класс, так и несколько классов. Аргумент dict может использоваться для указания словаря переменных и методов класса.
-
PyObject *PyErr_NewExceptionWithDoc(const char *name, const char *doc, PyObject *base, PyObject *dict)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
То же самое, что и
PyErr_NewException()
, за исключением того, что новому классу исключений можно легко задать строку документации: Если doc не``NULL``, то он будет использоваться в качестве docstring для класса исключений.Added in version 3.2.
Объекты исключений¶
-
PyObject *PyException_GetTraceback(PyObject *ex)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Возвращает отслеживание, связанное с исключением, в виде новой ссылки, доступной из Python через атрибут
__traceback__
. Если трассировка не связана, возвращаетсяNULL
.
-
int PyException_SetTraceback(PyObject *ex, PyObject *tb)¶
- Часть Стабильный ABI.
Установите отслеживание, связанное с исключением, в tb. Используйте
Py_None
, чтобы очистить его.
-
PyObject *PyException_GetContext(PyObject *ex)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Возвращает контекст (другой экземпляр исключения, во время обработки которого было поднято ex), связанный с исключением, в виде новой ссылки, доступной из Python через атрибут
__context__
. Если контекст не связан, возвращаетсяNULL
.
-
void PyException_SetContext(PyObject *ex, PyObject *ctx)¶
- Часть Стабильный ABI.
Установите контекст, связанный с исключением, на ctx. Используйте
NULL
, чтобы очистить его. Нет проверки типа, чтобы убедиться, что ctx является экземпляром исключения. Это крадет ссылку на ctx.
-
PyObject *PyException_GetCause(PyObject *ex)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Возвращает причину (либо экземпляр исключения, либо
None
, заданныйraise ... from ...
), связанную с исключением, в виде новой ссылки, доступной из Python через атрибут__cause__
.
-
void PyException_SetCause(PyObject *ex, PyObject *cause)¶
- Часть Стабильный ABI.
Установите для причины, связанной с исключением, значение cause. Чтобы очистить ее, используйте
NULL
. Нет проверки типа, чтобы убедиться, что cause является либо экземпляром исключения, либоNone
. Это крадет ссылку на cause.Атрибут
__suppress_context__
неявно устанавливается вTrue
этой функцией.
-
PyObject *PyException_GetArgs(PyObject *ex)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI с версии 3.12.
Возвращает
args
исключения ex.
-
void PyException_SetArgs(PyObject *ex, PyObject *args)¶
- Часть Стабильный ABI с версии 3.12.
Установите
args
исключения ex в args.
-
PyObject *PyUnstable_Exc_PrepReraiseStar(PyObject *orig, PyObject *excs)¶
- Это Нестабильный API. Она может меняться без предупреждения в небольших выпусках.
Реализует часть реализации интерпретатора
except*
. orig - это исходное исключение, которое было поймано, а excs - это список исключений, которые должны быть подняты. Этот список содержит необработанную часть orig, если таковая имеется, а также исключения, которые были подняты из клаузулexcept*
(поэтому они имеют отличный от orig traceback) и те, которые были повторно подняты (и имеют тот же traceback, что и orig). ВозвращаетExceptionGroup
, который должен быть поднят в конце, илиNone
, если поднимать нечего.Added in version 3.12.
Объекты исключений Unicode¶
Следующие функции используются для создания и изменения исключений Unicode из языка C.
-
PyObject *PyUnicodeDecodeError_Create(const char *encoding, const char *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Создайте объект
UnicodeDecodeError
с атрибутами encoding, object, length, start, end и reason. encoding и reason - это строки в кодировке UTF-8.
-
PyObject *PyUnicodeDecodeError_GetEncoding(PyObject *exc)¶
-
PyObject *PyUnicodeEncodeError_GetEncoding(PyObject *exc)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Возвращает атрибут encoding данного объекта исключения.
-
PyObject *PyUnicodeDecodeError_GetObject(PyObject *exc)¶
-
PyObject *PyUnicodeEncodeError_GetObject(PyObject *exc)¶
-
PyObject *PyUnicodeTranslateError_GetObject(PyObject *exc)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный 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)¶
- Часть Стабильный 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)¶
- Часть Стабильный ABI.
Устанавливает атрибут 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)¶
- Часть Стабильный 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)¶
- Часть Стабильный ABI.
Устанавливает атрибут end данного объекта исключения в значение end. Возвращает
0
при успехе,-1
при неудаче.
-
PyObject *PyUnicodeDecodeError_GetReason(PyObject *exc)¶
-
PyObject *PyUnicodeEncodeError_GetReason(PyObject *exc)¶
-
PyObject *PyUnicodeTranslateError_GetReason(PyObject *exc)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный 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)¶
- Часть Стабильный ABI.
Устанавливает атрибут reason данного объекта исключения в значение reason. Возвращает
0
при успехе,-1
при неудаче.
Управление рекурсией¶
Эти две функции позволяют выполнять безопасные рекурсивные вызовы на уровне C, как в ядре, так и в модулях расширения. Они нужны, если рекурсивный код не обязательно вызывает код Python (который автоматически отслеживает глубину рекурсии). Они также не нужны для реализаций tp_call, поскольку call protocol берет на себя обработку рекурсии.
-
int Py_EnterRecursiveCall(const char *where)¶
- Часть Стабильный ABI с версии 3.9.
Отмечает точку, в которой должен быть выполнен рекурсивный вызов уровня C.
Если определена
USE_STACKCHECK
, эта функция проверяет, не переполнился ли стек ОС при использованииPyOS_CheckStack()
. Если это так, она устанавливаетMemoryError
и возвращает ненулевое значение.Затем функция проверяет, достигнут ли предел рекурсии. Если это так, то устанавливается
RecursionError
и возвращается ненулевое значение. В противном случае возвращается ноль.where должно быть строкой в кодировке UTF-8, например
" in instance check"
, которая будет конкатенирована к сообщениюRecursionError
, вызванному ограничением глубины рекурсии.Изменено в версии 3.9: Теперь эта функция доступна и в limited API.
-
void Py_LeaveRecursiveCall(void)¶
- Часть Стабильный ABI с версии 3.9.
Завершает выполнение
Py_EnterRecursiveCall()
. Должен вызываться один раз для каждого успешного вызоваPy_EnterRecursiveCall()
.Изменено в версии 3.9: Теперь эта функция доступна и в limited API.
Правильная реализация tp_repr
для контейнерных типов требует специальной обработки рекурсии. Помимо защиты стека, tp_repr
также должна отслеживать объекты для предотвращения циклов. Следующие две функции облегчают эту работу. По сути, они являются эквивалентом reprlib.recursive_repr()
на языке Си.
-
int Py_ReprEnter(PyObject *object)¶
- Часть Стабильный ABI.
Вызывается в начале реализации
tp_repr
для обнаружения циклов.Если объект уже был обработан, функция возвращает целое положительное число. В этом случае реализация
tp_repr
должна вернуть строковый объект, указывающий на цикл. В качестве примера можно привести объектыdict
, возвращающие{...}
, иlist
, возвращающие[...]
.Функция вернет отрицательное целое число, если достигнут предел рекурсии. В этом случае реализация
tp_repr
обычно должна возвращатьNULL
.В противном случае функция возвращает ноль, и реализация
tp_repr
может продолжать работу в обычном режиме.
-
void Py_ReprLeave(PyObject *object)¶
- Часть Стабильный ABI.
Завершает
Py_ReprEnter()
. Должен вызываться один раз для каждого вызоваPy_ReprEnter()
, возвращающего ноль.
Стандартные исключения¶
Все стандартные исключения Python доступны в виде глобальных переменных, чьи имена имеют вид PyExc_
, за которым следует имя исключения Python. Они имеют тип PyObject*; все они являются объектами класса. Для полноты картины здесь перечислены все переменные:
C Name |
Имя питона |
Примечания |
---|---|---|
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
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
.
Это псевдонимы совместимости с PyExc_OSError
:
C Name |
Примечания |
---|---|
|
|
|
|
|
Изменено в версии 3.3: Раньше эти псевдонимы были отдельными типами исключений.
Примечания:
Стандартные категории предупреждений¶
Все стандартные категории предупреждений Python доступны в виде глобальных переменных, чьи имена имеют вид PyExc_
, за которым следует имя исключения Python. Они имеют тип PyObject*; все они являются объектами класса. Для полноты картины здесь перечислены все переменные:
C Name |
Имя питона |
Примечания |
---|---|---|
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
Added in version 3.2: PyExc_ResourceWarning
.
Примечания:
Это базовый класс для других стандартных категорий предупреждений.