Обработка исключений

Вывод и сброс

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 также присваиваются соответственно тип, значение и трассировка стека этого исключения.

Изменено в версии 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, полученное вызовом repr, будет выведено в сообщении предупреждения. Если obj равен NULL, выводится только трассировка стека.

При вызове этой функции должно быть установлено исключение.

Изменено в версии 3.4: Выводится трассировка стека. Если obj равен NULL, выводится только трассировка стека.

Изменено в версии 3.8: Используется sys.unraisablehook().

void PyErr_DisplayException(PyObject *exc)

Входит в состав стабильного ABI с версии 3.12.

Вывести стандартное представление трассировки стека для exc в sys.stderr, включая связанные исключения и примечания.

Добавлено в версии 3.12.

Вызов исключений

Эти функции помогают установить индикатор ошибки текущего потока. Для удобства некоторые из этих функций всегда возвращают указатель NULL для использования в операторе return.

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

Входит в состав стабильного ABI.

Это самый распространённый способ установить индикатор ошибки. Первый аргумент задаёт тип исключения; обычно это одно из стандартных исключений, например PyExc_RuntimeError. Создавать на него новую сильную ссылку (например, с помощью 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 вместо переменного числа аргументов.

Добавлено в версии 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(), но принимает второй объект имени файла для вызова исключений, когда завершается с ошибкой функция, работающая с двумя именами файлов.

Добавлено в версии 3.4.

PyObject *PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename)

Возвращаемое значение: всегда NULL.Входит в состав стабильного ABI.

Похожа на PyErr_SetFromErrnoWithFilenameObject(), но имя файла задаётся в виде строки C. filename декодируется с использованием кодировки файловой системы и обработчика ошибок.

PyObject *PyErr_SetFromWindowsErr(int ierr)

Возвращаемое значение: всегда NULL.Входит в состав стабильного ABI в Windows с версии 3.7.

Это вспомогательная функция для вызова исключения OSError. Если ierr равен 0, вместо него используется код ошибки, возвращённый вызовом GetLastError(). Функция вызывает функцию Win32 FormatMessage(), чтобы получить описание Windows для кода ошибки, заданного ierr или GetLastError(), затем создаёт объект OSError, устанавливая атрибут winerror в код ошибки, а атрибут strerror — в соответствующее сообщение об ошибке (полученное из FormatMessage()), после чего вызывает PyErr_SetObject(PyExc_OSError, object). Эта функция всегда возвращает NULL.

Доступность: Windows.

PyObject *PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)

Возвращаемое значение: всегда NULL.Входит в состав стабильного ABI в Windows с версии 3.7.

Похожа на PyErr_SetFromWindowsErr(), но принимает дополнительный параметр, задающий тип вызываемого исключения.

Доступность: Windows.

PyObject *PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)

Возвращаемое значение: всегда NULL.Входит в состав стабильного ABI в Windows с версии 3.7.

Похожа на PyErr_SetFromWindowsErr(), но дополнительно, если filename не равен NULL, декодирует его с использованием кодировки файловой системы (os.fsdecode()) и передаёт конструктору OSError в качестве третьего параметра, чтобы определить атрибут filename экземпляра исключения.

Доступность: Windows.

PyObject *PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject *type, int ierr, PyObject *filename)

Возвращаемое значение: всегда NULL.Входит в состав стабильного ABI в Windows с версии 3.7.

Похожа на PyErr_SetExcFromWindowsErr(), но дополнительно, если filename не равен NULL, передаёт его конструктору OSError в качестве третьего параметра, чтобы определить атрибут filename экземпляра исключения.

Доступность: Windows.

PyObject *PyErr_SetExcFromWindowsErrWithFilenameObjects(PyObject *type, int ierr, PyObject *filename, PyObject *filename2)

Возвращаемое значение: всегда NULL.Входит в состав стабильного ABI в Windows с версии 3.7.

Похожа на PyErr_SetExcFromWindowsErrWithFilenameObject(), но принимает второй объект имени файла.

Доступность: Windows.

Добавлено в версии 3.4.

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

Возвращаемое значение: всегда NULL.Входит в состав стабильного ABI в Windows с версии 3.7.

Похожа на PyErr_SetFromWindowsErrWithFilename(), но принимает дополнительный параметр, задающий тип вызываемого исключения.

Доступность: Windows.

PyObject *PyErr_SetImportError(PyObject *msg, PyObject *name, PyObject *path)

Возвращаемое значение: всегда NULL.Входит в состав стабильного ABI с версии 3.7.

Это вспомогательная функция для вызова исключения ImportError. msg будет задано как строка сообщения исключения. name и path, оба из которых могут быть равны NULL, будут заданы как соответствующие атрибуты name и path исключения ImportError.

Добавлено в версии 3.3.

PyObject *PyErr_SetImportErrorSubclass(PyObject *exception, PyObject *msg, PyObject *name, PyObject *path)

Возвращаемое значение: всегда NULL.Входит в состав стабильного ABI с версии 3.6.

Похожа на PyErr_SetImportError(), но позволяет указать подкласс ImportError, который нужно вызвать.

Добавлено в версии 3.6.

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)

Входит в состав стабильного ABI с версии 3.7.

Как и PyErr_SyntaxLocationObject(), но filename — это байтовая строка, декодированная с использованием кодировки файловой системы и обработчика ошибок.

Добавлено в версии 3.2.

void PyErr_SyntaxLocation(const char *filename, int lineno)

Входит в состав стабильного ABI.

Как и PyErr_SyntaxLocationEx(), но параметр col_offset опущен.

void PyErr_BadInternalCall()

Входит в состав стабильного ABI.

Это сокращённая форма записи для 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)

Входит в состав стабильного 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.

Добавлено в версии 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 декодируется с использованием кодировки файловой системы и обработчика ошибок.

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

Входит в состав стабильного ABI.

Функция, похожая на PyErr_WarnEx(), но для форматирования предупреждения использует PyUnicode_FromFormat(). format — строка в кодировке ASCII.

Добавлено в версии 3.2.

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

Входит в состав стабильного ABI с версии 3.6.

Функция, похожая на PyErr_WarnFormat(), но category — это ResourceWarning, а source передаётся в warnings.WarningMessage.

Добавлено в версии 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() для сохранения исключения, которое обрабатывается в данный момент.

Добавлено в версии 3.12.

void PyErr_SetRaisedException(PyObject *exc)

Часть стабильного ABI начиная с версии 3.12.

Устанавливает exc как исключение, которое в данный момент возбуждается, и удаляет существующее исключение, если оно установлено.

Предупреждение

Этот вызов забирает ссылку на exc, который должен быть допустимым исключением.

Добавлено в версии 3.12.

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

Часть стабильного ABI.

Устарело с версии 3.12: Вместо этого используйте PyErr_GetRaisedException().

Сохраняет индикатор ошибки в трёх переменных, адреса которых переданы. Если индикатор ошибки не установлен, всем трём переменным присваивается NULL. Если он установлен, он будет сброшен, и вы будете владеть ссылкой на каждый полученный объект. Объект значения и объект трассировки могут быть NULL, даже если объект типа таковым не является.

Примечание

Эта функция обычно используется только устаревшим кодом, которому нужно перехватывать исключения или временно сохранять и восстанавливать индикатор ошибки.

Например:

{
   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. Тип исключения должен быть классом. Не передавайте недопустимый тип или значение исключения. (Нарушение этих правил впоследствии приведёт к трудноуловимым проблемам.) Этот вызов забирает ссылку на каждый объект: до вызова вы должны владеть ссылкой на каждый объект, а после вызова больше не будете владеть этими ссылками. (Если вы этого не понимаете, не используйте эту функцию. Я вас предупредил.)

Примечание

Эта функция обычно используется только устаревшим кодом, которому нужно временно сохранять и восстанавливать индикатор ошибки. Для сохранения текущего индикатора ошибки используйте PyErr_Fetch().

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

Часть стабильного ABI.

Устарело с версии 3.12: Вместо этого используйте PyErr_GetRaisedException(), чтобы избежать возможной денормализации.

При определённых обстоятельствах значения, возвращаемые приведённой ниже функцией PyErr_Fetch(), могут быть «ненормализованными»: это означает, что *exc является объектом-классом, а *val не является экземпляром того же класса. В этом случае эту функцию можно использовать для создания экземпляра класса. Если значения уже нормализованы, ничего не происходит. Отложенная нормализация реализована для повышения производительности.

Примечание

Эта функция не устанавливает неявно атрибут __traceback__ у значения-исключения. Если необходимо правильно установить трассировку, требуется следующий дополнительный фрагмент:

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

PyObject *PyErr_GetHandledException(void)

Часть стабильного ABI начиная с версии 3.11.

Получает активный экземпляр исключения, который возвращала бы функция sys.exception(). Это исключение, которое уже было перехвачено, а не только что возбужденное исключение. Возвращает новую ссылку на исключение или NULL. Не изменяет состояние исключений интерпретатора.

Примечание

Эта функция обычно не используется кодом, которому нужно обрабатывать исключения. Вместо этого её можно применять, когда коду требуется временно сохранять и восстанавливать состояние исключений. Для восстановления или сброса состояния исключений используйте PyErr_SetHandledException().

Добавлено в версии 3.11.

void PyErr_SetHandledException(PyObject *exc)

Часть стабильного ABI начиная с версии 3.11.

Устанавливает активное исключение, известное через sys.exception(). Это исключение, которое уже было перехвачено, а не только что возбужденное исключение. Чтобы сбросить состояние исключений, передайте NULL.

Примечание

Эта функция обычно не используется кодом, которому нужно обрабатывать исключения. Вместо этого её можно применять, когда коду требуется временно сохранять и восстанавливать состояние исключений. Для получения состояния исключений используйте PyErr_GetHandledException().

Добавлено в версии 3.11.

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

Часть стабильного ABI начиная с версии 3.7.

Получает представление информации об исключении в старом формате, известное по sys.exc_info(). Это исключение, которое уже было перехвачено, а не только что возбужденное исключение. Возвращает новые ссылки на три объекта, каждый из которых может быть NULL. Не изменяет состояние информации об исключении. Эта функция сохранена для обратной совместимости. Предпочтительно использовать PyErr_GetHandledException().

Примечание

Эта функция обычно не используется кодом, которому нужно обрабатывать исключения. Вместо этого её можно применять, когда коду требуется временно сохранять и восстанавливать состояние исключений. Для восстановления или сброса состояния исключений используйте PyErr_SetExcInfo().

Добавлено в версии 3.3.

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

Часть стабильного ABI начиная с версии 3.7.

Устанавливает информацию об исключении, известную через sys.exc_info(). Это исключение, которое уже было перехвачено, а не только что возбужденное исключение. Эта функция забирает ссылки на аргументы. Чтобы сбросить состояние исключений, передайте NULL для всех трёх аргументов. Эта функция сохранена для обратной совместимости. Предпочтительно использовать PyErr_SetHandledException().

Примечание

Эта функция обычно не используется кодом, которому нужно обрабатывать исключения. Вместо этого её можно применять, когда коду требуется временно сохранять и восстанавливать состояние исключений. Для чтения состояния исключений используйте PyErr_GetExcInfo().

Добавлено в версии 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).

Примечание

Эта функция безопасна для вызова из асинхронного обработчика сигнала. Её можно вызывать без 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. Эта функция никогда не изменяет индикатор ошибки.

Примечание

Эта функция безопасна для вызова из асинхронного обработчика сигнала. Её можно вызывать без GIL и из обработчика сигнала на C.

Добавлено в версии 3.10.

int PySignal_SetWakeupFd(int fd)

Эта вспомогательная функция задаёт файловый дескриптор, в который при получении сигнала записывается его номер в виде одного байта. fd должен работать в неблокирующем режиме. Функция возвращает предыдущий файловый дескриптор.

Значение -1 отключает эту возможность; это начальное состояние. В Python эта функция эквивалентна signal.set_wakeup_fd(), но не выполняет никаких проверок ошибок. fd должен быть допустимым файловым дескриптором. Функцию следует вызывать только из главного потока.

Изменено в версии 3.5: В Windows функция теперь также поддерживает дескрипторы сокетов.

Классы исключений

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

Возвращаемое значение: новая ссылка. Часть стабильного ABI.

Эта вспомогательная функция создаёт и возвращает новый класс исключения. Аргумент name должен содержать имя нового исключения в виде строки C формата module.classname. Аргументы base и dict обычно равны NULL. В результате создаётся объект-класс, производный от Exception (доступного в C как PyExc_Exception).

Атрибут __module__ нового класса устанавливается в первую часть аргумента name (до последней точки), а имя класса — в последнюю часть (после последней точки). Аргумент base можно использовать для указания альтернативных базовых классов; это может быть один класс или кортеж классов. Аргумент dict можно использовать для указания словаря переменных класса и методов.

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

Возвращаемое значение: новая ссылка. Часть стабильного ABI.

То же, что и PyErr_NewException(), за исключением того, что новому классу исключения можно легко задать строку документации: если doc не равен NULL, он будет использован в качестве строки документации класса исключения.

Добавлено в версии 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.

Устанавливает для исключения ex значение args равным args.

PyObject *PyUnstable_Exc_PrepReraiseStar(PyObject *orig, PyObject *excs)

Это нестабильный API. Он может измениться без предупреждения в минорных выпусках.

Реализует часть реализации интерпретатора для except*. orig — исходное перехваченное исключение, а excs — список исключений, которые нужно возбудить. Этот список содержит необработанную часть orig, если таковая имеется, а также исключения, возбужденные в блоках except* (поэтому их трассировка отличается от трассировки orig), и повторно возбужденные исключения (трассировка которых совпадает с трассировкой orig). Возвращает ExceptionGroup, которое нужно повторно возбудить в конце, или None, если повторно возбуждать нечего.

Добавлено в версии 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, поскольку протокол вызова берет на себя обработку рекурсии.

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: Теперь эта функция также доступна в ограниченном API.

void Py_LeaveRecursiveCall(void)

Часть стабильного ABI начиная с версии 3.9.

Завершает Py_EnterRecursiveCall(). Необходимо вызывать один раз для каждого успешного вызова Py_EnterRecursiveCall().

Изменено в версии 3.9: Теперь эта функция также доступна в ограниченном API.

Для правильной реализации tp_repr для типов-контейнеров требуется специальная обработка рекурсии. Помимо защиты стека, tp_repr также должна отслеживать объекты, чтобы предотвращать циклы. Следующие две функции обеспечивают эту возможность. По сути, они являются эквивалентом reprlib.recursive_repr() на языке C.

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*; все они являются объектами классов. Для полноты приведем список всех переменных:

Это псевдонимы для совместимости с PyExc_OSError:

Примечания:

Стандартные категории предупреждений

Все стандартные категории предупреждений Python доступны как глобальные переменные, имена которых состоят из PyExc_ и имени исключения Python. Их тип — PyObject*; все они являются объектами классов. Для полноты приведем список всех переменных:

Примечания: