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

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

void PyErr_Clear()

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

void PyErr_PrintEx(int set_sys_last_vars)

Вывести стандартную трассировку в sys.stderr и очистить индикатор ошибки. Если ошибка — SystemExit, в этом случае трассировка не выводится, и процесс Python завершится с кодом ошибки, указанным экземпляром SystemExit.

Вызывать эту функцию только при установке индикатора ошибки. В противном случае она вызовет критическую ошибку!

Если set_sys_last_vars ненулевое, переменные sys.last_type, sys.last_value и sys.last_traceback будут установлены соответственно на тип, значение и трассировку выведенного исключения.

void PyErr_Print()

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

void PyErr_WriteUnraisable(PyObject *obj)

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

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

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

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

Вызывающие исключения

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

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

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

void PyErr_SetObject(PyObject *type, PyObject *value)

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

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

Значение возврата: всегда NULL.

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

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

Значение возврата: всегда NULL.

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

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

void PyErr_SetNone(PyObject *type)

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

int PyErr_BadArgument()

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

PyObject* PyErr_NoMemory()

Значение возврата: всегда NULL.

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

PyObject* PyErr_SetFromErrno(PyObject *type)

Значение возврата: всегда NULL.

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

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

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

Значение возврата: всегда NULL.

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

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

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

Значение возврата: всегда NULL.

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

PyObject* PyErr_SetFromWindowsErr(int ierr)

Значение возврата: всегда NULL.

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

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

PyObject* PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)

Значение возврата: всегда NULL.

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

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

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

Значение возврата: всегда NULL.

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

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

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

Значение возврата: всегда NULL.

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

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

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

Значение возврата: всегда NULL.

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

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

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

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

Значение возврата: всегда NULL.

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

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

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

Значение возврата: всегда NULL.

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

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

PyObject* PyErr_SetImportErrorSubclass(PyObject *exception, PyObject *msg, PyObject *name, PyObject *path)

Значение возврата: всегда NULL.

Почти как 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)

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

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

void PyErr_SyntaxLocation(const char *filename, int lineno)

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

void PyErr_BadInternalCall()

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

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

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

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

Выдать сообщение о предупреждении. Аргумент 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)

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

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

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

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

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

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

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

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

PyObject* PyErr_Occurred()

Значение возврата: Заимствованная ссылка.

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

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

Примечание

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

int PyErr_ExceptionMatches(PyObject *exc)

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

int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)

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

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

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

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

Примечание

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

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

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

Примечание

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

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

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

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

Примечание

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

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

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

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

Примечание

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

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

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

int PyErr_CheckSignals()

Эта функция взаимодействует с обработкой сигналов Python. Она проверяет, был ли отправлен сигнал процессам, и, если да, вызывает соответствующий обработчик сигнала. Если модуль signal поддерживается, это может вызвать обработчик сигнала, написанный на Python. Во всех случаях, стандартное действие для SIGINT — возбуждение исключения KeyboardInterrupt. Если исключение возбуждено, индикатор ошибки устанавливается, и функция возвращает -1; в противном случае функция возвращает 0 Индикатор ошибки может быть или не быть очищен, если он был установлен ранее.

void PyErr_SetInterrupt()

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

Если SIGINT не обрабатывается Python (он был установлен в signal.SIG_DFL или signal.SIG_IGN), эта функция ничего не делает.

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)

Значение возврата: Новая ссылка.

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

Значение возврата: Новая ссылка.

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

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

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

PyObject* PyException_GetTraceback(PyObject *ex)

Значение результата: Новая ссылка.

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

int PyException_SetTraceback(PyObject *ex, PyObject *tb)

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

PyObject* PyException_GetContext(PyObject *ex)

Значение результата: Новая ссылка.

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

void PyException_SetContext(PyObject *ex, PyObject *ctx)

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

PyObject* PyException_GetCause(PyObject *ex)

Значение результата: Новая ссылка.

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

void PyException_SetCause(PyObject *ex, PyObject *cause)

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

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

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

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

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

Значение результата: Новая ссылка.

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

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

Значение результата: Новая ссылка.

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

Устаревшая с версии 3.3: 3.11

Py_UNICODE устарела с Python 3.3. Пожалуйста, перейдите к PyObject_CallFunction(PyExc_UnicodeEncodeError, "sOnns", ...).

PyObject* PyUnicodeTranslateError_Create(const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)

Значение результата: Новая ссылка.

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

Устаревшая с версии 3.3: 3.11

Py_UNICODE устарела с Python 3.3. Пожалуйста, перейдите к PyObject_CallFunction(PyExc_UnicodeTranslateError, "Onns", ...).

PyObject* PyUnicodeDecodeError_GetEncoding(PyObject *exc)

PyObject* PyUnicodeEncodeError_GetEncoding(PyObject *exc)

Значение результата: Новая ссылка.

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

PyObject* PyUnicodeDecodeError_GetObject(PyObject *exc)

PyObject* PyUnicodeEncodeError_GetObject(PyObject *exc)

PyObject* PyUnicodeTranslateError_GetObject(PyObject *exc)

Значение результата: Новая ссылка.

Возвращает атрибут 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)

Получает атрибут 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)

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

Получает атрибут 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)

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

PyObject* PyUnicodeDecodeError_GetReason(PyObject *exc)

PyObject* PyUnicodeEncodeError_GetReason(PyObject *exc)

PyObject* PyUnicodeTranslateError_GetReason(PyObject *exc)

Значение результата: Новая ссылка.

Возвращает атрибут 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)

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

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

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

int Py_EnterRecursiveCall(const char *where)

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

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

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

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

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

void Py_LeaveRecursiveCall(void)

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

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

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

int Py_ReprEnter(PyObject *object)

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

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

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

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

void Py_ReprLeave(PyObject *object)

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

Стандартные исключения

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

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

Примечания:

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

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

2

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

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

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

Примечания:

3

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