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

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

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, который идентифицирует контекст, в котором возникло необрабатываемое исключение. Если возможно, repr объекта 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, будут установлены как атрибуты 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_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()

Значение возврата: Заимствованная ссылка. Часть Стабильного API.

Проверяет, установлено ли индикатор ошибки. Если установлено, возвращает тип исключения (первый аргумент последнего вызова одной из функций PyErr_Set* или функции PyErr_Restore()). Если не установлено, возвращает NULL. Вы не владеете ссылкой на возвращаемое значение, поэтому вам не нужно Py_DECREF() его.

Вызывающая сторона должна удерживать GIL.

Примечание

Не сравнивайте возвращаемое значение со специфичным исключением; используйте PyErr_ExceptionMatches() вместо этого, как показано ниже. (Сравнение может легко завершиться ошибкой, так как исключение может быть экземпляром, а не классом, в случае исключения класса, или это может быть подкласс ожидаемого исключения.)

int PyErr_ExceptionMatches(PyObject *exc)

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

Эквивалентно PyErr_GivenExceptionMatches(PyErr_Occurred(), exc). Этот вызов должен выполняться только в том случае, если исключение фактически установлено; обращение к несуществующему участку памяти произойдёт, если исключение не было поднято.

int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)

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

Возвращает true, если переданное исключение совпадает с типом исключения в exc. Если exc — объект класса, это также возвращает true, когда given — экземпляр подкласса. Если exc — кортеж, ищутся все типы исключений в кортеже (и рекурсивно в подкортежах) в поисках совпадения.

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

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

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

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

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

Примечание

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

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

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

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

Примечание

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

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

PyObject *PyErr_GetHandledException(void)

Часть Стабильного API с версии 3.11.

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

Примечание

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

Введено в версии 3.11.

void PyErr_SetHandledException(PyObject *exc)

Часть Стабильного API с версии 3.11.

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

Примечание

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

Введено в версии 3.11.

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

Часть Стабильного API с версии 3.7.

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

Примечание

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

Введено в версии 3.3.

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

Часть Стабильного API с версии 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 отключает эту функцию; это начальное состояние. Это эквивалентно 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.

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

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:

Примечания:

1(1,2,3,4,5)

Это базовый класс для других стандартных исключений.

2

Определен только в Windows; защитите код, использующий его, проверив, что препроцессорная макрос MS_WINDOWS определен.

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

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

Примечания:

3

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