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

Вывод и очистка

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. Если obj равен NULL, выводится только трассировка стека.

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

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

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

void PyErr_FormatUnraisable(const char *format, ...)

Аналогична PyErr_WriteUnraisable(), но аргумент format и последующие параметры используются для форматирования предупреждения; они имеют то же значение и принимают те же значения, что и в PyUnicode_FromFormat(). PyErr_WriteUnraisable(obj) примерно эквивалентно PyErr_FormatUnraisable("Exception ignored in: %R", obj). Если format равен NULL, выводится только трассировка стека.

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

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

Примечание

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

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

int PyExceptionClass_Check(PyObject *ob)

Возвращает ненулевое значение, если ob является классом исключения, и ноль в противном случае. Эта функция всегда завершается успешно.

const char *PyExceptionClass_Name(PyObject *ob)

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

Возвращает tp_name класса исключения ob.

Объекты исключений

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), и повторно вызванные исключения (с той же трассировкой, что и у 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*; все они являются объектами классов.

Для полноты приведём все переменные: