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

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

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_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(), но принимает второй объект файла.

Доступность: 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 указывает, что внутренняя операция (например, функция API Python/C) была вызвана с незаконным аргументом. В основном предназначено для внутреннего использования.

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

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

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

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

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

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

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

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

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

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

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

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

Функция, похожая на PyErr_WarnFormat(), но category — ResourceWarning, а source передаётся в warnings.WarningMessage.

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

Получение информации об ошибке

PyObject *PyErr_Occurred()

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

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

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

Примечание

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

int PyErr_ExceptionMatches(PyObject *exc)

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

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

int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)

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

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

PyObject *PyErr_GetRaisedException(void)

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

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

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

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

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

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

Примечание

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

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

PyObject *PyErr_GetHandledException(void)

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

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

Примечание

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

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

void PyErr_SetHandledException(PyObject *exc)

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

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

Примечание

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

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

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

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

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

Примечание

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

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

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

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

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

Примечание

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

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

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

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

int PyErr_CheckSignals()

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

Эта функция взаимодействует с обработкой сигналов Python.

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

Функция пытается обработать все ожидающие сигналы, а затем возвращает 0. Однако, если обработчик сигнала Python вызывает исключение, индикатор ошибки устанавливается, и функция возвращает -1 немедленно (таким образом, другие ожидающие сигналы могут быть не обработаны: они будут на следующем вызове PyErr_CheckSignals()).

Если функция вызывается из неглавного потока или под неглавным интерпретатором Python, она ничего не делает и возвращает 0.

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

Примечание

По умолчанию обработчик сигнала Python для SIGINT вызывает исключение KeyboardInterrupt.

void PyErr_SetInterrupt()

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

Имитировать эффект прихода сигнала SIGINT. Это эквивалентно PyErr_SetInterruptEx(SIGINT).

Примечание

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

int PyErr_SetInterruptEx(int signum)

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

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

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

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

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

Примечание

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

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

int PySignal_SetWakeupFd(int fd)

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

Значение -1 отключает эту функцию; это начальное состояние. Это эквивалентно 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*; все они являются объектами классов. Для полноты, вот все переменные:

Примечания: