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

Печать и очистка¶Printing and clearing

void PyErr_Clear()¶

Часть Stable ABI.

Очищает индикатор ошибки. Если индикатор ошибки не установлен, эффекта нет.

void PyErr_PrintEx(int set_sys_last_vars)¶

Часть Stable 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()¶

Часть Stable ABI.

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

void PyErr_WriteUnraisable(PyObject *obj)¶

Часть Stable 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(), но format и последующие параметры помогают форматировать предупреждающее сообщение; они имеют тот же смысл и те же значения, что и в PyUnicode_FromFormat(). PyErr_WriteUnraisable(obj) примерно эквивалентна PyErr_FormatUnraisable("Exception ignored in: %R", obj). Если format равен NULL, печатается только трассировка.

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

void PyErr_DisplayException(PyObject *exc)¶

Часть Stable ABI начиная с версии 3.12.

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

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

Возбуждение исключений¶Raising exceptions

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

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

Часть Stable ABI.

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

void PyErr_SetObject(PyObject *type, PyObject *value)¶

Часть Stable ABI.

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

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

Возвращаемое значение: всегда NULL. Часть Stable ABI.

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

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

Возвращаемое значение: Всегда NULL. Часть Stable ABI начиная с версии 3.5.

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

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

void PyErr_SetNone(PyObject *type)¶

Часть Stable ABI.

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

int PyErr_BadArgument()¶

Часть Stable ABI.

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

PyObject *PyErr_NoMemory()¶

Возвращаемое значение: всегда NULL. Часть Stable ABI.

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

PyObject *PyErr_SetFromErrno(PyObject *type)¶

Возвращаемое значение: всегда NULL. Часть Stable 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. Часть Stable ABI.

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

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

Возвращаемое значение: всегда NULL. Часть Stable ABI начиная с версии 3.7.

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

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

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

Возвращаемое значение: всегда NULL. Часть Stable ABI.

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

PyObject *PyErr_SetFromWindowsErr(int ierr)¶

Возвращаемое значение: всегда NULL. Часть Stable 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. Часть Stable ABI на Windows начиная с версии 3.7.

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

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

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

Возвращаемое значение: всегда NULL. Часть Stable ABI на Windows начиная с версии 3.7.

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

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

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

Возвращаемое значение: всегда NULL. Часть Stable ABI на Windows начиная с версии 3.7.

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

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

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

Возвращаемое значение: всегда NULL. Часть Stable ABI на Windows начиная с версии 3.7.

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

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

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

PyObject *PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, const char *filename)¶

Возвращаемое значение: всегда NULL. Часть Stable ABI на Windows начиная с версии 3.7.

Аналогично PyErr_SetFromWindowsErrWithFilename(), с дополнительным параметром, указывающим тип возбуждаемого исключения.

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

PyObject *PyErr_SetImportError(PyObject *msg, PyObject *name, PyObject *path)¶

Возвращаемое значение: всегда NULL. Часть Stable 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. Часть Stable ABI начиная с версии 3.6.

Очень похожа на PyErr_SetImportError(), но эта функция позволяет указать подкласс ImportError для возбуждения.

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

void PyErr_SyntaxLocationObject(PyObject *filename, int lineno, int col_offset)¶

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

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

void PyErr_RangedSyntaxLocationObject(PyObject *filename, int lineno, int col_offset, int end_lineno, int end_col_offset)¶

Аналогично PyErr_SyntaxLocationObject(), но также устанавливает информацию end_lineno и end_col_offset для текущего исключения.

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

void PyErr_SyntaxLocationEx(const char *filename, int lineno, int col_offset)¶

Часть Stable ABI начиная с версии 3.7.

Как PyErr_SyntaxLocationObject(), но filename – это байтовая строка, декодированная из кодировки файловой системы и обработчика ошибок.

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

void PyErr_SyntaxLocation(const char *filename, int lineno)¶

Часть Stable ABI.

Как PyErr_SyntaxLocationEx(), но параметр col_offset опущен.

void PyErr_BadInternalCall()¶

Часть Stable ABI.

Это сокращение для PyErr_SetString(PyExc_SystemError, message), где message указывает, что внутренняя операция (например, функция Python/C API) была вызвана с недопустимым аргументом. Предназначено в основном для внутреннего использования.

PyObject *PyErr_ProgramTextObject(PyObject *filename, int lineno)¶

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

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

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

Часть Stable ABI.

Аналогично PyErr_ProgramTextObject(), но filename – это const char*, который декодируется с помощью кодировки файловой системы и обработчика ошибок, вместо ссылки на объект Python.

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

Используйте эти функции для выдачи предупреждений из кода на C. Они аналогичны соответствующим функциям, экспортируемым модулем Python warnings. Обычно они выводят предупреждающее сообщение в sys.stderr; однако возможно, что пользователь указал превращать предупреждения в ошибки, и в этом случае они возбудят исключение. Также возможно, что функции возбуждают исключение из-за проблемы с механизмом предупреждений. Возвращаемое значение – 0, если исключение не возбуждено, или -1, если исключение возбуждено. (Невозможно определить, было ли предупреждение фактически напечатано или какова причина исключения; это сделано намеренно.) Если исключение возбуждено, вызывающий код должен выполнить обычную обработку исключений (например, Py_DECREF() принадлежащие ссылки и вернуть значение ошибки).

int PyErr_WarnEx(PyObject *category, const char *message, Py_ssize_t stack_level)¶

Часть Stable ABI.

Выдает предупреждающее сообщение. Аргумент category – это категория предупреждения (см. ниже) или NULL; аргумент message – это строка в кодировке UTF-8. stack_level – положительное число, задающее количество фреймов стека; предупреждение будет выдано от текущей выполняемой строки кода в этом фрейме стека. stack_level, равный 1, – это функция, вызывающая PyErr_WarnEx(), 2 – функция над ней, и так далее.

Категории предупреждений должны быть подклассами PyExc_Warning; PyExc_Warning является подклассом PyExc_Exception; категория предупреждения по умолчанию – PyExc_RuntimeWarning. Стандартные категории предупреждений Python доступны как глобальные переменные, названия которых перечислены в Типы предупреждений.

Информацию об управлении предупреждениями см. в документации модуля warnings и опции -W в документации командной строки. API для управления предупреждениями на C не существует.

int PyErr_WarnExplicitObject(PyObject *category, PyObject *message, PyObject *filename, int lineno, PyObject *module, PyObject *registry)¶

Выдаёт предупреждение с явным контролем всех его атрибутов. Это простая обёртка вокруг функции Python warnings.warn_explicit(); за подробностями обращайтесь к её документации. Аргументы module и registry могут быть установлены в NULL, чтобы получить описанный там эффект по умолчанию.

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

int PyErr_WarnExplicit(PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry)¶

Часть Stable ABI.

Аналогично PyErr_WarnExplicitObject(), за исключением того, что message и module являются строками в кодировке UTF-8, а filename декодируется из кодировки файловой системы и обработчика ошибок.

int PyErr_WarnFormat(PyObject *category, Py_ssize_t stack_level, const char *format, ...)¶

Часть Stable ABI.

Функция аналогична PyErr_WarnEx(), но использует PyUnicode_FromFormat() для форматирования предупреждающего сообщения. format – это строка в кодировке ASCII.

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

int PyErr_WarnExplicitFormat(PyObject *category, const char *filename, int lineno, const char *module, PyObject *registry, const char *format, ...)¶

Аналогично PyErr_WarnExplicit(), но использует PyUnicode_FromFormat() для форматирования предупреждающего сообщения. format – это строка в кодировке ASCII.

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

int PyErr_ResourceWarning(PyObject *source, Py_ssize_t stack_level, const char *format, ...)¶

Часть Stable ABI начиная с версии 3.6.

Функция аналогична PyErr_WarnFormat(), но category равен ResourceWarning, и она передаёт source в warnings.WarningMessage.

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

Опрос индикатора ошибки¶Querying the error indicator

PyObject *PyErr_Occurred()¶

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

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

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

Примечание

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

int PyErr_ExceptionMatches(PyObject *exc)¶

Часть Stable ABI.

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

int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)¶

Часть Stable ABI.

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

PyObject *PyErr_GetRaisedException(void)¶

Возвращаемое значение: новая ссылка. Часть Stable ABI с версии 3.12.

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

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

Например:

{
   PyObject *exc = PyErr_GetRaisedException();

   /* ... код, который может вызвать другие ошибки ... */

   PyErr_SetRaisedException(exc);
}

См. также

PyErr_GetHandledException(), чтобы сохранить исключение, которое в данный момент обрабатывается.

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

void PyErr_SetRaisedException(PyObject *exc)¶

Часть Stable ABI начиная с версии 3.12.

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

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

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

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

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

Часть Stable ABI.

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

Извлекает индикатор ошибки в три переменные, чьи адреса передаются. Если индикатор ошибки не установлен, устанавливает все три переменные в NULL. Если он установлен, он будет очищен, и вы получаете владение ссылкой на каждый извлеченный объект. Объекты value и traceback могут иметь значение NULL, даже если объект type – нет.

Примечание

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

Например:

{
   PyObject *type, *value, *traceback;
   PyErr_Fetch(&type, &value, &traceback);

   /* ... код, который может вызвать другие ошибки ... */

   PyErr_Restore(type, value, traceback);
}

void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback)¶

Часть Stable ABI.

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

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

Примечание

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

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

Часть Stable ABI.

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

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

Примечание

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

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

PyObject *PyErr_GetHandledException(void)¶

Часть Stable ABI начиная с версии 3.11.

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

Примечание

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

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

void PyErr_SetHandledException(PyObject *exc)¶

Часть Stable ABI начиная с версии 3.11.

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

Примечание

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

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

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

Часть Stable ABI начиная с версии 3.7.

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

Примечание

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

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

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

Часть Stable ABI начиная с версии 3.7.

Устанавливает информацию об исключении, как известно из sys.exc_info(). Это относится к исключению, которое уже было перехвачено, а не к только что возбужденному. Эта функция «похищает» ссылки на аргументы. Чтобы очистить состояние исключения, передайте NULL для всех трех аргументов. Эта функция сохраняется для обратной совместимости. Предпочтительнее использовать PyErr_SetHandledException().

Примечание

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

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

Изменено в версии 3.11: Аргументы type и traceback больше не используются и могут быть NULL. Интерпретатор теперь извлекает их из экземпляра исключения (аргумент value). Функция по-прежнему «похищает» ссылки всех трех аргументов.

Обработка сигналов¶Signal Handling

int PyErr_CheckSignals()¶

Часть Stable ABI.

Обрабатывает внешние прерывания, такие как сигналы или активация отладчика, обработка которых была отложена до момента, когда безопасно выполнять код Python и/или возбуждать исключения.

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

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

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

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

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

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

• Запуск сборщика мусора, если необходимо.

• Выполнение ожидающего скрипта удалённого отладчика.

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

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

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

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

void PyErr_SetInterrupt()¶

Часть Stable ABI.

Имитирует эффект прибытия сигнала SIGINT. Это эквивалентно PyErr_SetInterruptEx(SIGINT).

Примечание

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

int PyErr_SetInterruptEx(int signum)¶

Часть Stable ABI начиная с версии 3.10.

Имитирует эффект прибытия сигнала. При следующем вызове PyErr_CheckSignals() будет вызван обработчик сигнала Python для заданного номера сигнала.

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

Если заданный сигнал не обрабатывается Python (он был установлен в signal.SIG_DFL или signal.SIG_IGN), он будет проигнорирован.

Если signum выходит за допустимый диапазон номеров сигналов, возвращается -1. В противном случае возвращается 0. Эта функция никогда не изменяет индикатор ошибки.

Примечание

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

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

int PySignal_SetWakeupFd(int fd)¶

Эта вспомогательная функция задаёт файловый дескриптор, в который при получении сигнала записывается номер сигнала в виде одного байта. fd должен быть неблокирующим. Функция возвращает предыдущий такой файловый дескриптор.

Значение -1 отключает эту возможность; это начальное состояние. Это эквивалентно signal.set_wakeup_fd() в Python, но без проверки ошибок. fd должен быть корректным файловым дескриптором. Функцию следует вызывать только из главного потока.

Изменено в версии 3.5: В Windows функция теперь также поддерживает дескрипторы сокетов.

Классы исключений¶Exception Classes

PyObject *PyErr_NewException(const char *name, PyObject *base, PyObject *dict)¶

Возвращаемое значение: новая ссылка. Часть Stable 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)¶

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

То же, что и PyErr_NewException(), за исключением того, что новому классу исключения можно легко задать докстринг: если doc не NULL, он будет использоваться в качестве докстринга класса исключения.

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

int PyExceptionClass_Check(PyObject *ob)¶

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

const char *PyExceptionClass_Name(PyObject *ob)¶

Часть Stable ABI с версии 3.8.

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

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

int PyExceptionInstance_Check(PyObject *op)¶

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

PyExceptionInstance_Class(op)¶

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

PyObject *PyException_GetTraceback(PyObject *ex)¶

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

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

int PyException_SetTraceback(PyObject *ex, PyObject *tb)¶

Часть Stable ABI.

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

PyObject *PyException_GetContext(PyObject *ex)¶

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

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

void PyException_SetContext(PyObject *ex, PyObject *ctx)¶

Часть Stable ABI.

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

PyObject *PyException_GetCause(PyObject *ex)¶

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

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

void PyException_SetCause(PyObject *ex, PyObject *cause)¶

Часть Stable ABI.

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

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

PyObject *PyException_GetArgs(PyObject *ex)¶

Возвращаемое значение: новая ссылка. Часть Stable ABI с версии 3.12.

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

void PyException_SetArgs(PyObject *ex, PyObject *args)¶

Часть Stable ABI начиная с версии 3.12.

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

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

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

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

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

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

Следующие функции используются для создания и изменения исключений 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)¶

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

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

PyObject *PyUnicodeDecodeError_GetEncoding(PyObject *exc)¶

PyObject *PyUnicodeEncodeError_GetEncoding(PyObject *exc)¶

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

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

PyObject *PyUnicodeDecodeError_GetObject(PyObject *exc)¶

PyObject *PyUnicodeEncodeError_GetObject(PyObject *exc)¶

PyObject *PyUnicodeTranslateError_GetObject(PyObject *exc)¶

Возвращаемое значение: новая ссылка. Часть Stable 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)¶

Часть Stable ABI.

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

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

См. также

UnicodeError.start

int PyUnicodeDecodeError_SetStart(PyObject *exc, Py_ssize_t start)¶

int PyUnicodeEncodeError_SetStart(PyObject *exc, Py_ssize_t start)¶

int PyUnicodeTranslateError_SetStart(PyObject *exc, Py_ssize_t start)¶

Часть Stable ABI.

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

Примечание

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

int PyUnicodeDecodeError_GetEnd(PyObject *exc, Py_ssize_t *end)¶

int PyUnicodeEncodeError_GetEnd(PyObject *exc, Py_ssize_t *end)¶

int PyUnicodeTranslateError_GetEnd(PyObject *exc, Py_ssize_t *end)¶

Часть Stable ABI.

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

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

int PyUnicodeDecodeError_SetEnd(PyObject *exc, Py_ssize_t end)¶

int PyUnicodeEncodeError_SetEnd(PyObject *exc, Py_ssize_t end)¶

int PyUnicodeTranslateError_SetEnd(PyObject *exc, Py_ssize_t end)¶

Часть Stable ABI.

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

См. также

UnicodeError.end

PyObject *PyUnicodeDecodeError_GetReason(PyObject *exc)¶

PyObject *PyUnicodeEncodeError_GetReason(PyObject *exc)¶

PyObject *PyUnicodeTranslateError_GetReason(PyObject *exc)¶

Возвращаемое значение: новая ссылка. Часть Stable 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)¶

Часть Stable ABI.

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

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

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

int Py_EnterRecursiveCall(const char *where)¶

Часть Stable ABI начиная с версии 3.9.

Отмечает точку, в которой будет выполнен рекурсивный вызов на уровне C.

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

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

См. также

Функция PyUnstable_ThreadState_SetStackProtection().

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

void Py_LeaveRecursiveCall(void)¶

Часть Stable ABI начиная с версии 3.9.

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

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

Для правильной реализации tp_repr для контейнерных типов требуется специальная обработка рекурсии. В дополнение к защите стека, tp_repr также необходимо отслеживать объекты для предотвращения циклов. Следующие две функции облегчают эту функциональность. По сути, это эквивалент reprlib.recursive_repr() на C.

int Py_ReprEnter(PyObject *object)¶

Часть Stable ABI.

Вызывается в начале реализации tp_repr для обнаружения циклов.

Если объект уже был обработан, функция возвращает положительное целое число. В этом случае реализация tp_repr должна вернуть строковый объект, указывающий на цикл. Например, объекты dict возвращают {...}, а объекты list возвращают [...].

Функция возвращает отрицательное целое число, если достигнут предел рекурсии. В этом случае реализация tp_repr обычно должна возвращать NULL.

В противном случае функция возвращает ноль, и реализация tp_repr может продолжить работу в обычном режиме.

void Py_ReprLeave(PyObject *object)¶

Часть Stable ABI.

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

int Py_GetRecursionLimit(void)¶

Часть Stable ABI.

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

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

См. также

sys.getrecursionlimit()

void Py_SetRecursionLimit(int new_limit)¶

Часть Stable ABI.

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

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

См. также

sys.setrecursionlimit()

Типы исключений и предупреждений¶Exception and warning types

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

Для полноты картины – вот все переменные:

Трассировки¶Tracebacks

PyTypeObject PyTraceBack_Type¶

Часть Stable ABI.

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

int PyTraceBack_Check(PyObject *op)¶

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

int PyTraceBack_Here(PyFrameObject *f)¶

Часть Stable ABI.

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

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

Эта функция возвращает 0 в случае успеха и -1 с установленным исключением в случае неудачи.

int PyTraceBack_Print(PyObject *tb, PyObject *f)¶

Часть Stable ABI.

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

Эта функция возвращает 0 в случае успеха и -1 с установленным исключением в случае неудачи.