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

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

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

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

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

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

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

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

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

void PyErr_DisplayException(PyObject *exc)

Часть Стабильной ABI с версии 3.12.

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

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

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

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

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

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

Это наиболее распространённый способ установки индикатора ошибки. Первый аргумент указывает тип исключения; обычно это одно из стандартных исключений, например PyExc_RuntimeError. Вам не нужно создавать новую сильную ссылку на него (например, с помощью Py_INCREF()). Второй аргумент — сообщение об ошибке; оно декодируется из 'utf-8'.

void PyErr_SetObject(PyObject *type, PyObject *value)

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

Эта функция похожа на PyErr_SetString(), но позволяет указать произвольный объект Python для «значения» исключения.

PyObject *PyErr_Format(PyObject *exception, const char *format, ...)

Значение возврата: всегда NULL. Часть Стабильной ABI.

Эта функция устанавливает индикатор ошибки и возвращает NULL. exception должен быть классом Python исключения. Параметры format и последующие параметры помогают форматировать сообщение об ошибке; они имеют то же значение и значения, что и в PyUnicode_FromFormat(). format — строка в кодировке ASCII.

PyObject *PyErr_FormatV(PyObject *exception, const char *format, va_list vargs)

Значение возврата: всегда NULL. Часть Стабильной ABI с версии 3.5.

То же, что и PyErr_Format(), но использует аргумент va_list вместо переменного числа аргументов.

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

void PyErr_SetNone(PyObject *type)

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

Это сокращение для PyErr_SetObject(type, Py_None).

int PyErr_BadArgument()

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

Это сокращение для PyErr_SetString(PyExc_TypeError, message), где message указывает, что встроенная операция была вызвана с незаконным аргументом. В основном используется для внутренних целей.

PyObject *PyErr_NoMemory()

Значение возврата: всегда NULL. Часть Стабильной ABI.

Это сокращение для PyErr_SetNone(PyExc_MemoryError); оно возвращает NULL, чтобы функция выделения объекта могла записать return PyErr_NoMemory(); при недостатке памяти.

PyObject *PyErr_SetFromErrno(PyObject *type)

Значение возврата: всегда NULL. Часть Стабильной ABI.

Это вспомогательная функция для вызова исключения, когда функция C-библиотеки возвратила ошибку и установила переменную C errno. Она создаёт объект кортежа, первым элементом которого является целое значение errno, а вторым — соответствующее сообщение об ошибке (полученное из strerror()), и затем вызывает PyErr_SetObject(type, object). В Unix, когда значение errno равно EINTR, что указывает на прерванный системный вызов, она вызывает PyErr_CheckSignals(), и если это установило индикатор ошибки, оставляет его установленным на эту ошибку. Функция всегда возвращает NULL, чтобы функция-обёртка вокруг системного вызова могла записать return PyErr_SetFromErrno(type); при ошибке системного вызова.

PyObject *PyErr_SetFromErrnoWithFilenameObject(PyObject *type, PyObject *filenameObject)

Значение возврата: всегда NULL. Часть Стабильной ABI.

Аналогично PyErr_SetFromErrno(), с дополнительным поведением, что если filenameObject не NULL, оно передаётся в конструктор type в качестве третьего параметра. В случае исключения OSError это используется для определения атрибута filename экземпляра исключения.

PyObject *PyErr_SetFromErrnoWithFilenameObjects(PyObject *type, PyObject *filenameObject, PyObject *filenameObject2)

Значение возврата: всегда NULL. Часть Стабильной ABI с версии 3.7.

Аналогично PyErr_SetFromErrnoWithFilenameObject(), но принимает второй объект файла для повышения ошибок, когда функция, принимающая два имени файлов, терпит неудачу.

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

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

Значение возврата: всегда NULL. Часть Стабильной ABI.

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

PyObject *PyErr_SetFromWindowsErr(int ierr)

Значение возврата: всегда NULL. Часть Стабильной ABI в Windows с версии 3.7.

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

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

PyObject *PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)

Значение возврата: всегда NULL. Часть Стабильной ABI в Windows с версии 3.7.

Аналогично PyErr_SetFromWindowsErr() с дополнительным параметром, определяющим тип исключения для повышения.

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

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

Значение возврата: всегда NULL. Часть Стабильной ABI в Windows с версии 3.7.

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

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

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

Значение возврата: всегда NULL. Часть Стабильной ABI на Windows начиная с версии 3.7.

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

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

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

Значение возврата: всегда NULL. Часть Стабильной ABI на Windows начиная с версии 3.7.

Аналогично PyErr_SetExcFromWindowsErrWithFilenameObject(), но принимает второй объект filename.

Доступность: 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 в документации командной строки. 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 – это кортеж, ищутся все типы исключений в кортеже (и рекурсивно в подкортежах) для соответствия.

PyObject *PyErr_GetRaisedException(void)

Значение возврата: Новая ссылка. Часть стабильного API с версии 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)

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

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

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

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

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

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

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

Устарело с версии 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)

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

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

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

Примечание

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

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

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

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

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

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

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

Возвращает стек вызовов, связанный с исключением, как новую ссылку, доступную в Python через атрибут __traceback__. Если стек вызовов не связан, возвращает NULL.

int PyException_SetTraceback(PyObject *ex, PyObject *tb)

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

Устанавливает стек вызовов, связанный с исключением, в tb. Используйте Py_None для его очистки.

PyObject *PyException_GetContext(PyObject *ex)

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

Возвращает контекст (другой экземпляр исключения, при обработке которого было поднято ex) связанный с исключением как новую ссылку, доступную в Python через атрибут __context__. Если контекст не связан, возвращает NULL.

void PyException_SetContext(PyObject *ex, PyObject *ctx)

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

Устанавливает контекст, связанный с исключением, в ctx. Используйте NULL для его очистки. Проверки типов для ctx, гарантирующих, что это экземпляр исключения, нет. Эта функция заимствует ссылку на ctx.

PyObject *PyException_GetCause(PyObject *ex)

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

Возвращает причину (либо экземпляр исключения, либо None, установленную функцией raise ... from ... ), связанную с исключением, как новую ссылку, доступную в Python через атрибут __cause__.

void PyException_SetCause(PyObject *ex, PyObject *cause)

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

Устанавливает причину, связанную с исключением, в cause. Используйте NULL для её очистки. Проверки типов для cause, гарантирующих, что это либо экземпляр исключения, либо None, нет. Эта функция заимствует ссылку на cause.

Атрибут __suppress_context__ неявно устанавливается в True этой функцией.

PyObject *PyException_GetArgs(PyObject *ex)

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

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

void PyException_SetArgs(PyObject *ex, PyObject *args)

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

Устанавливает args исключения ex в args.

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

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

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

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

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

Следующие функции используются для создания и изменения исключений Unicode из C.

PyObject *PyUnicodeDecodeError_Create(const char *encoding, const char *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)

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

Создаёт объект UnicodeDecodeError с атрибутами encoding, object, length, start, end и reason. encoding и reason — строки, закодированные в UTF-8.

PyObject *PyUnicodeDecodeError_GetEncoding(PyObject *exc)

PyObject *PyUnicodeEncodeError_GetEncoding(PyObject *exc)

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

Возвращает атрибут encoding данного объекта исключения.

PyObject *PyUnicodeDecodeError_GetObject(PyObject *exc)

PyObject *PyUnicodeEncodeError_GetObject(PyObject *exc)

PyObject *PyUnicodeTranslateError_GetObject(PyObject *exc)

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

Возвращает атрибут object данного объекта исключения.

int PyUnicodeDecodeError_GetStart(PyObject *exc, Py_ssize_t *start)

int PyUnicodeEncodeError_GetStart(PyObject *exc, Py_ssize_t *start)

int PyUnicodeTranslateError_GetStart(PyObject *exc, Py_ssize_t *start)

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

Получает атрибут start данного объекта исключения и помещает его в *start. start не должен быть NULL. Возвращает 0 при успехе, -1 при ошибке.

int PyUnicodeDecodeError_SetStart(PyObject *exc, Py_ssize_t start)

int PyUnicodeEncodeError_SetStart(PyObject *exc, Py_ssize_t start)

int PyUnicodeTranslateError_SetStart(PyObject *exc, Py_ssize_t start)

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

Устанавливает атрибут start данного объекта исключения в start. Возвращает 0 при успехе, -1 при ошибке.

int PyUnicodeDecodeError_GetEnd(PyObject *exc, Py_ssize_t *end)

int PyUnicodeEncodeError_GetEnd(PyObject *exc, Py_ssize_t *end)

int PyUnicodeTranslateError_GetEnd(PyObject *exc, Py_ssize_t *end)

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

Получает атрибут end данного объекта исключения и помещает его в *end. end не должен быть NULL. Возвращает 0 при успехе, -1 при ошибке.

int PyUnicodeDecodeError_SetEnd(PyObject *exc, Py_ssize_t end)

int PyUnicodeEncodeError_SetEnd(PyObject *exc, Py_ssize_t end)

int PyUnicodeTranslateError_SetEnd(PyObject *exc, Py_ssize_t end)

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

Устанавливает атрибут end данного объекта исключения в end. Возвращает 0 при успехе, -1 при ошибке.

PyObject *PyUnicodeDecodeError_GetReason(PyObject *exc)

PyObject *PyUnicodeEncodeError_GetReason(PyObject *exc)

PyObject *PyUnicodeTranslateError_GetReason(PyObject *exc)

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

Возвращает атрибут reason данного объекта исключения.

int PyUnicodeDecodeError_SetReason(PyObject *exc, const char *reason)

int PyUnicodeEncodeError_SetReason(PyObject *exc, const char *reason)

int PyUnicodeTranslateError_SetReason(PyObject *exc, const char *reason)

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

Устанавливает атрибут reason данного объекта исключения в reason. Возвращает 0 при успехе, -1 при ошибке.

Управление рекурсией

Эти две функции обеспечивают способ безопасного выполнения рекурсивных вызовов на уровне C, как в ядре, так и в модулях расширения. Они необходимы, если рекурсивный код не обязательно вызывает Python-код (который автоматически отслеживает глубину рекурсии). Они также не нужны для реализаций tp_call, потому что протокол вызова вызова обрабатывает управление рекурсией.

int Py_EnterRecursiveCall(const char *where)

Часть Стабильной ABI с версии 3.9.

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

Если USE_STACKCHECK определено, эта функция проверяет, переполнен ли стек ОС с помощью PyOS_CheckStack(). Если это так, то устанавливает исключение MemoryError и возвращает ненулевое значение.

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

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

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

void Py_LeaveRecursiveCall(void)

Часть Стабильной ABI с версии 3.9.

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

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

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

Примечания: