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

Вывод и сброс

void PyErr_Clear()

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

Сбрасывает индикатор ошибки. Если индикатор ошибки не установлен, ничего не происходит.

void PyErr_PrintEx(int set_sys_last_vars)

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

Выводит стандартную трассировку стека в sys.stderr и сбрасывает индикатор ошибки. Однако, если ошибка является SystemExit, трассировка стека не выводится, а процесс Python завершается с кодом ошибки, указанным в экземпляре SystemExit.

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

Если set_sys_last_vars не равен нулю, переменным sys.last_type, sys.last_value и sys.last_traceback будут присвоены соответственно тип, значение и трассировка стека выведенного исключения.

void PyErr_Print()

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

Псевдоним для PyErr_PrintEx(1).

void PyErr_WriteUnraisable(PyObject *obj)

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

Вызывает sys.unraisablehook() с текущим исключением и аргументом obj.

Эта вспомогательная функция выводит предупреждение в sys.stderr, когда исключение установлено, но интерпретатор не может фактически вызвать его. Например, она используется, когда исключение возникает в методе __del__().

Функция вызывается с единственным аргументом obj, указывающим контекст, в котором возникло невызванное исключение. Если возможно, представление obj будет выведено в сообщении предупреждения.

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

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

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

Это вспомогательная функция для вызова WindowsError. Если значение ierr равно 0, вместо него используется код ошибки, возвращённый вызовом GetLastError(). Функция вызывает функцию Win32 FormatMessage(), чтобы получить описание Windows для кода ошибки, заданного ierr или GetLastError(), затем создаёт объект-кортеж, первый элемент которого — значение ierr, а второй — соответствующее сообщение об ошибке (полученное из FormatMessage()), и вызывает PyErr_SetObject(PyExc_WindowsError, 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 в документации по командной строке. C API для управления предупреждениями отсутствует.

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, если переданное исключение соответствует типу исключения в exc. Если exc — объект-класс, функция также возвращает true, когда given является экземпляром подкласса. Если exc — кортеж, выполняется поиск совпадения среди всех типов исключений в кортеже (и рекурсивно во вложенных кортежах).

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

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

Получает индикатор ошибки в три переменные, адреса которых передаются функции. Если индикатор ошибки не установлен, все три переменные устанавливаются в 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.

Устанавливает индикатор ошибки на основе трёх объектов. Если индикатор ошибки уже установлен, сначала он очищается. Если объекты равны NULL, индикатор ошибки очищается. Не передавайте тип NULL и значение или объект трассировки, отличные от NULL. Тип исключения должен быть классом. Не передавайте недопустимый тип или значение исключения. (Нарушение этих правил позднее приведёт к трудноуловимым проблемам.) Этот вызов забирает ссылку на каждый объект: до вызова у вас должна быть ссылка на каждый объект, а после вызова эти ссылки вам больше не принадлежат. (Если вы не понимаете, что это значит, не используйте эту функцию. Я вас предупредил.)

Примечание

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

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

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

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

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

Стандартные исключения

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

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

Примечания:

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

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

Примечания: