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

Функции, описанные в этой главе, позволят вам обрабатывать и вызывать исключения Python. Важно понять некоторые основы обработки исключений в Python. Она работает примерно так же, как переменная POSIX errno: существует глобальный индикатор (для каждого потока) последней произошедшей ошибки. Большинство функций C API не очищают его при успехе, но устанавливают его, чтобы указать причину ошибки при неудаче. Большинство функций C API также возвращают индикатор ошибки, обычно NULL, если они должны возвращать указатель, или -1, если они возвращают целое число (исключение: функции PyArg_* возвращают 1 для успеха и 0 для неудачи).

Конкретно, индикатор ошибки состоит из трех указателей на объекты: тип исключения, значение исключения и объект трассировки. Любой из этих указателей может быть NULL, если он не установлен (хотя некоторые комбинации запрещены, например, вы не можете иметь не``NULL`` traceback, если тип исключения NULL).

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

Примечание

Индикатор ошибки не является результатом sys.exc_info(). Первое соответствует исключению, которое еще не поймано (и поэтому продолжает распространяться), а второе возвращает исключение после того, как оно поймано (и поэтому перестало распространяться).

Печать и очистка

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 также устанавливаются в тип, значение и traceback этого исключения, соответственно.

Изменено в версии 3.12: Была добавлена настройка sys.last_exc.

void PyErr_Print()
Часть Стабильный ABI.

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

void PyErr_WriteUnraisable(PyObject *obj)
Часть Стабильный ABI.

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

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

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

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

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

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

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

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

Added in version 3.13.

void PyErr_DisplayException(PyObject *exc)
Часть Стабильный ABI с версии 3.12.

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

Added in version 3.12.

Воспроизведение исключений

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

void PyErr_SetString(PyObject *type, const char *message)
Часть Стабильный ABI.

Это наиболее распространенный способ установки индикатора ошибки. Первый аргумент задает тип исключения; обычно это одно из стандартных исключений, например PyExc_RuntimeError. Не нужно создавать для него новый strong reference (например, с помощью 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, а не переменное число аргументов.

Added in version 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(), но принимает второй объект имени файла, чтобы выдать ошибку, когда функция, принимающая два имени файла, не работает.

Added in version 3.4.

PyObject *PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename)
Возвращаемое значение: Всегда NULL. Часть Стабильный ABI.

Аналогично PyErr_SetFromErrnoWithFilenameObject(), но имя файла задается в виде строки C. Имя filename декодируется из filesystem encoding and error handler.

PyObject *PyErr_SetFromWindowsErr(int ierr)
Возвращаемое значение: Всегда NULL. Часть Стабильный ABI on Windows с версии 3.7.

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

Availability: Windows.

PyObject *PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)
Возвращаемое значение: Всегда NULL. Часть Стабильный ABI on Windows с версии 3.7.

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

Availability: Windows.

PyObject *PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)
Возвращаемое значение: Всегда NULL. Часть Стабильный ABI on Windows с версии 3.7.

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

Availability: Windows.

PyObject *PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject *type, int ierr, PyObject *filename)
Возвращаемое значение: Всегда NULL. Часть Стабильный ABI on Windows с версии 3.7.

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

Availability: Windows.

PyObject *PyErr_SetExcFromWindowsErrWithFilenameObjects(PyObject *type, int ierr, PyObject *filename, PyObject *filename2)
Возвращаемое значение: Всегда NULL. Часть Стабильный ABI on Windows с версии 3.7.

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

Availability: Windows.

Added in version 3.4.

PyObject *PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, const char *filename)
Возвращаемое значение: Всегда NULL. Часть Стабильный ABI on Windows с версии 3.7.

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

Availability: Windows.

PyObject *PyErr_SetImportError(PyObject *msg, PyObject *name, PyObject *path)
Возвращаемое значение: Всегда NULL. Часть Стабильный ABI с версии 3.7.

Это удобная функция для поднятия ImportError. msg будет установлена как строка сообщения исключения. name и path, которые могут быть NULL, будут установлены как соответствующие ImportError атрибуты name и path.

Added in version 3.3.

PyObject *PyErr_SetImportErrorSubclass(PyObject *exception, PyObject *msg, PyObject *name, PyObject *path)
Возвращаемое значение: Всегда NULL. Часть Стабильный ABI с версии 3.6.

Аналогично PyErr_SetImportError(), но эта функция позволяет указать подкласс ImportError для повышения уровня.

Added in version 3.6.

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

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

Added in version 3.4.

void PyErr_SyntaxLocationEx(const char *filename, int lineno, int col_offset)
Часть Стабильный ABI с версии 3.7.

Аналогично PyErr_SyntaxLocationObject(), но filename - это байтовая строка, декодированная из filesystem encoding and error handler.

Added in version 3.2.

void PyErr_SyntaxLocation(const char *filename, int lineno)
Часть Стабильный ABI.

Аналогично PyErr_SyntaxLocationEx(), но параметр col_offset опущен.

void PyErr_BadInternalCall()
Часть Стабильный ABI.

Это сокращение для PyErr_SetString(PyExc_SystemError, message), где сообщение указывает на то, что внутренняя операция (например, функция API Python/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 на языке C для управления предупреждениями не существует.

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

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

Added in version 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 декодируется из filesystem encoding and error handler.

int PyErr_WarnFormat(PyObject *category, Py_ssize_t stack_level, const char *format, ...)
Часть Стабильный ABI.

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

Added in version 3.2.

int PyErr_ResourceWarning(PyObject *source, Py_ssize_t stack_level, const char *format, ...)
Часть Стабильный ABI с версии 3.6.

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

Added in version 3.6.

Запрос индикатора ошибок

PyObject *PyErr_Occurred()
Возвращаемое значение: Заимствованная ссылка. Часть Стабильный ABI.

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

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

Примечание

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

int PyErr_ExceptionMatches(PyObject *exc)
Часть Стабильный ABI.

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

int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)
Часть Стабильный ABI.

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

PyObject *PyErr_GetRaisedException(void)
Возвращаемое значение: Новая ссылка. Часть Стабильный ABI с версии 3.12.

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

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

Например:

{
   PyObject *exc = PyErr_GetRaisedException();

   /* ... code that might produce other errors ... */

   PyErr_SetRaisedException(exc);
}

См.также

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

Added in version 3.12.

void PyErr_SetRaisedException(PyObject *exc)
Часть Стабильный ABI с версии 3.12.

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

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

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

Added in version 3.12.

void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
Часть Стабильный ABI.

Не рекомендуется, начиная с версии 3.12: Вместо этого используйте PyErr_GetRaisedException().

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

Примечание

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

Например:

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

   /* ... code that might produce other errors ... */

   PyErr_Restore(type, value, traceback);
}
void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback)
Часть Стабильный ABI.

Не рекомендуется, начиная с версии 3.12: Вместо этого используйте PyErr_SetRaisedException().

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

Примечание

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

void PyErr_NormalizeException(PyObject **exc, PyObject **val, PyObject **tb)
Часть Стабильный ABI.

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

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

Примечание

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

if (tb != NULL) {
  PyException_SetTraceback(val, tb);
}
PyObject *PyErr_GetHandledException(void)
Часть Стабильный ABI с версии 3.11.

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

Примечание

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

Added in version 3.11.

void PyErr_SetHandledException(PyObject *exc)
Часть Стабильный ABI с версии 3.11.

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

Примечание

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

Added in version 3.11.

void PyErr_GetExcInfo(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
Часть Стабильный ABI с версии 3.7.

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

Примечание

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

Added in version 3.3.

void PyErr_SetExcInfo(PyObject *type, PyObject *value, PyObject *traceback)
Часть Стабильный ABI с версии 3.7.

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

Примечание

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

Added in version 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).

Примечание

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

Примечание

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

Added in version 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 (доступный в Си как PyExc_Exception).

Атрибут __module__ нового класса устанавливается в первую часть (до последней точки) аргумента name, а имя класса - в последнюю часть (после последней точки). Аргумент base может использоваться для указания альтернативных базовых классов; это может быть как один класс, так и несколько классов. Аргумент dict может использоваться для указания словаря переменных и методов класса.

PyObject *PyErr_NewExceptionWithDoc(const char *name, const char *doc, PyObject *base, PyObject *dict)
Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.

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

Added in version 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 этой функцией.

PyObject *PyException_GetArgs(PyObject *ex)
Возвращаемое значение: Новая ссылка. Часть Стабильный ABI с версии 3.12.

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

void PyException_SetArgs(PyObject *ex, PyObject *args)
Часть Стабильный ABI с версии 3.12.

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

PyObject *PyUnstable_Exc_PrepReraiseStar(PyObject *orig, PyObject *excs)
Это Нестабильный API. Она может меняться без предупреждения в небольших выпусках.

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

Added in version 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, поскольку call protocol берет на себя обработку рекурсии.

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: Теперь эта функция доступна и в limited API.

void Py_LeaveRecursiveCall(void)
Часть Стабильный ABI с версии 3.9.

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

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

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

C Name

Имя питона

Примечания

PyExc_BaseException

BaseException

[1]

PyExc_Exception

Exception

[1]

PyExc_ArithmeticError

ArithmeticError

[1]

PyExc_AssertionError

AssertionError

PyExc_AttributeError

AttributeError

PyExc_BlockingIOError

BlockingIOError

PyExc_BrokenPipeError

BrokenPipeError

PyExc_BufferError

BufferError

PyExc_ChildProcessError

ChildProcessError

PyExc_ConnectionAbortedError

ConnectionAbortedError

PyExc_ConnectionError

ConnectionError

PyExc_ConnectionRefusedError

ConnectionRefusedError

PyExc_ConnectionResetError

ConnectionResetError

PyExc_EOFError

EOFError

PyExc_FileExistsError

FileExistsError

PyExc_FileNotFoundError

FileNotFoundError

PyExc_FloatingPointError

FloatingPointError

PyExc_GeneratorExit

GeneratorExit

PyExc_ImportError

ImportError

PyExc_IndentationError

IndentationError

PyExc_IndexError

IndexError

PyExc_InterruptedError

InterruptedError

PyExc_IsADirectoryError

IsADirectoryError

PyExc_KeyError

KeyError

PyExc_KeyboardInterrupt

KeyboardInterrupt

PyExc_LookupError

LookupError

[1]

PyExc_MemoryError

MemoryError

PyExc_ModuleNotFoundError

ModuleNotFoundError

PyExc_NameError

NameError

PyExc_NotADirectoryError

NotADirectoryError

PyExc_NotImplementedError

NotImplementedError

PyExc_OSError

OSError

[1]

PyExc_OverflowError

OverflowError

PyExc_PermissionError

PermissionError

PyExc_ProcessLookupError

ProcessLookupError

PyExc_RecursionError

RecursionError

PyExc_ReferenceError

ReferenceError

PyExc_RuntimeError

RuntimeError

PyExc_StopAsyncIteration

StopAsyncIteration

PyExc_StopIteration

StopIteration

PyExc_SyntaxError

SyntaxError

PyExc_SystemError

SystemError

PyExc_SystemExit

SystemExit

PyExc_TabError

TabError

PyExc_TimeoutError

TimeoutError

PyExc_TypeError

TypeError

PyExc_UnboundLocalError

UnboundLocalError

PyExc_UnicodeDecodeError

UnicodeDecodeError

PyExc_UnicodeEncodeError

UnicodeEncodeError

PyExc_UnicodeError

UnicodeError

PyExc_UnicodeTranslateError

UnicodeTranslateError

PyExc_ValueError

ValueError

PyExc_ZeroDivisionError

ZeroDivisionError

Added in version 3.3: PyExc_BlockingIOError, PyExc_BrokenPipeError, PyExc_ChildProcessError, PyExc_ConnectionError, PyExc_ConnectionAbortedError, PyExc_ConnectionRefusedError, PyExc_ConnectionResetError, PyExc_FileExistsError, PyExc_FileNotFoundError, PyExc_InterruptedError, PyExc_IsADirectoryError, PyExc_NotADirectoryError, PyExc_PermissionError, PyExc_ProcessLookupError и PyExc_TimeoutError были представлены после PEP 3151.

Added in version 3.5: PyExc_StopAsyncIteration и PyExc_RecursionError.

Added in version 3.6: PyExc_ModuleNotFoundError.

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

C Name

Примечания

PyExc_EnvironmentError

PyExc_IOError

PyExc_WindowsError

[2]

Изменено в версии 3.3: Раньше эти псевдонимы были отдельными типами исключений.

Примечания:

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

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

C Name

Имя питона

Примечания

PyExc_Warning

Warning

[3]

PyExc_BytesWarning

BytesWarning

PyExc_DeprecationWarning

DeprecationWarning

PyExc_FutureWarning

FutureWarning

PyExc_ImportWarning

ImportWarning

PyExc_PendingDeprecationWarning

PendingDeprecationWarning

PyExc_ResourceWarning

ResourceWarning

PyExc_RuntimeWarning

RuntimeWarning

PyExc_SyntaxWarning

SyntaxWarning

PyExc_UnicodeWarning

UnicodeWarning

PyExc_UserWarning

UserWarning

Added in version 3.2: PyExc_ResourceWarning.

Примечания: