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

Вывод и сброс

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.

void PyErr_Display(PyObject *unused, PyObject *value, PyObject *tb)

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

Устаревший вариант PyErr_DisplayException().

Вывести значение исключения вместе с его трассировкой в sys.stderr. Если для value не задана трассировка, в качестве трассировки используется tb. Первый аргумент игнорируется.

Если sys.stderr равен None, ничего не выводится. Если sys.stderr не установлен, исключение выводится в поток C stderr.

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

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

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

Добавлено в версии 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_RangedSyntaxLocationObject(PyObject *filename, int lineno, int col_offset, int end_lineno, int end_col_offset)

Похожа на PyErr_SyntaxLocationObject(), но также задаёт для текущего исключения сведения end_lineno и end_col_offset.

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

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) была вызвана с недопустимым аргументом. В основном используется внутри системы.

PyObject *PyErr_ProgramTextObject(PyObject *filename, int lineno)

Получить исходную строку из filename с номером lineno. filename должен быть объектом Python типа str.

В случае успеха функция возвращает объект-строку Python с найденной строкой. В случае сбоя функция возвращает NULL, не устанавливая исключение.

PyObject *PyErr_ProgramText(const char *filename, int lineno)

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

Похожа на PyErr_ProgramTextObject(), но filename имеет тип const char* и декодируется с использованием кодировки файловой системы и обработчика ошибок, а не является ссылкой на объект Python.

Выдача предупреждений

Используйте эти функции, чтобы выдавать предупреждения из кода на C. Они аналогичны функциям, экспортируемым модулем warnings языка Python. Обычно они выводят сообщение с предупреждением в 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_WarnExplicitFormat(PyObject *category, const char *filename, int lineno, const char *module, PyObject *registry, const char *format, ...)

Аналогична PyErr_WarnExplicit(), но использует 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() не нужно.

У вызывающей стороны должно быть присоединённое состояние потока.

Примечание

Не сравнивайте возвращаемое значение с конкретным исключением; вместо этого используйте приведённую ниже функцию 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 равен NULL, просто сбросить существующее исключение.

exc должен быть допустимым исключением или NULL.

Этот вызов «забирает» ссылку на 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 и/или возбуждение исключений станет безопасным.

Например, нажатие Ctrl-C приводит к отправке терминалом сигнала signal.SIGINT. Эта функция выполняет соответствующий обработчик сигнала Python, который по умолчанию возбуждает исключение KeyboardInterrupt.

Длительно работающий код на C должен достаточно часто вызывать PyErr_CheckSignals(), чтобы реакция казалась человеку мгновенной.

В настоящее время эта функция вызывает следующие обработчики:

• Обработчики сигналов, в том числе функции Python, зарегистрированные с помощью модуля signal.

  Обработчики сигналов запускаются только в главном потоке главного интерпретатора.

  (Название функции связано с этим: изначально прерывать интерпретатор можно было только сигналами.)

• Запуск сборщика мусора, если это необходимо.
• Выполнение ожидающего сценария удалённого отладчика.

Если какой-либо обработчик возбуждает исключение, немедленно вернуть -1 с установленным исключением. Оставшиеся прерывания будут обработаны при следующем вызове PyErr_CheckSignals(), если это применимо.

Если все обработчики завершаются успешно или обработчиков для запуска нет, вернуть 0.

Изменено в версии 3.12: Теперь эта функция может вызывать сборщик мусора.

Изменено в версии 3.14: Теперь эта функция может выполнять сценарий удалённого отладчика, если включена удалённая отладка.

void PyErr_SetInterrupt()

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

Имитировать получение сигнала SIGINT. Это эквивалентно PyErr_SetInterruptEx(SIGINT).

Примечание

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

Примечание

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

Добавлено в версии 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 (доступного в 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.

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

int PyExceptionInstance_Check(PyObject *op)

Возвращает true, если op является экземпляром BaseException, и false в противном случае. Эта функция всегда завершается успешно.

PyExceptionInstance_Class(op)

Эквивалентно Py_TYPE(op).

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 в случае ошибки.

Если UnicodeError.object — пустая последовательность, результирующее значение start равно 0. В противном случае оно ограничивается значением [0, len(object) - 1].

См. также

UnicodeError.start

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 в случае ошибки.

Примечание

Передача отрицательного значения start не вызывает исключение, однако соответствующие функции получения значения не будут рассматривать его как относительное смещение.

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 в случае ошибки.

Если UnicodeError.object — пустая последовательность, результирующее значение end равно 0. В противном случае оно ограничивается значением [1, len(object)].

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 в случае ошибки.

См. также

UnicodeError.end

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.

Затем функция проверяет, достигнут ли предел стека. Если достигнут, устанавливается RecursionError и возвращается ненулевое значение. В противном случае возвращается ноль.

where должна быть строкой в кодировке UTF-8, например " in instance check", которая добавляется к сообщению RecursionError, вызванному превышением предела глубины рекурсии.

См. также

Функцию PyUnstable_ThreadState_SetStackProtection().

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

void Py_LeaveRecursiveCall(void)

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

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

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

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

int Py_GetRecursionLimit(void)

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

Возвращает предел рекурсии для текущего интерпретатора. Его можно задать с помощью Py_SetRecursionLimit(). Предел рекурсии не позволяет стеку интерпретатора Python расти бесконечно.

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

См. также

sys.getrecursionlimit()

void Py_SetRecursionLimit(int new_limit)

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

Задает предел рекурсии для текущего интерпретатора.

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

См. также

sys.setrecursionlimit()

Типы исключений и предупреждений

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

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

Трассировки стека

PyTypeObject PyTraceBack_Type

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

Объект типа для объектов трассировки стека. В слое Python он доступен как types.TracebackType.

int PyTraceBack_Check(PyObject *op)

Возвращает true, если op является объектом трассировки стека, и false в противном случае. Эта функция не учитывает подклассы.

int PyTraceBack_Here(PyFrameObject *f)

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

Заменяет атрибут __traceback__ текущего исключения новой трассировкой стека, добавляя f в начало существующей цепочки.

Вызов этой функции, когда исключение не установлено, приводит к неопределённому поведению.

В случае успеха функция возвращает 0, а в случае ошибки — -1 с установленным исключением.

int PyTraceBack_Print(PyObject *tb, PyObject *f)

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

Записывает трассировку стека tb в файл f.

В случае успеха функция возвращает 0, а в случае ошибки — -1 с установленным исключением.