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

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

void PyErr_Clear()¶

Part of the Стабильный ABI.

Снимите индикатор ошибки. Если индикатор ошибки не установлен, это не повлияет на результат.

void PyErr_PrintEx(int set_sys_last_vars)¶

Part of the Стабильный ABI.

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

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

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

void PyErr_Print()¶

Part of the Стабильный ABI.

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

void PyErr_WriteUnraisable(PyObject *obj)¶

Part of the Стабильный ABI.

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

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

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

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

Создание исключений¶

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

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

Part of the Стабильный ABI.

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

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

Part of the Стабильный ABI.

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

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

Возвращаемое значение: Всегда NULL. Part of the Стабильный ABI.

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

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

Возвращаемое значение: Всегда NULL. Part of the Стабильный ABI since version 3.5.

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

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

void PyErr_SetNone(PyObject *type)¶

Part of the Стабильный ABI.

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

int PyErr_BadArgument()¶

Part of the Стабильный ABI.

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

PyObject *PyErr_NoMemory()¶

Возвращаемое значение: Всегда NULL. Part of the Стабильный ABI.

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

PyObject *PyErr_SetFromErrno(PyObject *type)¶

Возвращаемое значение: Всегда NULL. Part of the Стабильный ABI.

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

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

Возвращаемое значение: Всегда NULL. Part of the Стабильный ABI.

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

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

Возвращаемое значение: Всегда NULL. Part of the Стабильный ABI since version 3.7.

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

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

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

Возвращаемое значение: Всегда NULL. Part of the Стабильный ABI.

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

PyObject *PyErr_SetFromWindowsErr(int ierr)¶

Возвращаемое значение: Всегда NULL. Part of the Стабильный ABI on Windows since version 3.7.

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

Availability: Окна.

PyObject *PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)¶

Возвращаемое значение: Всегда NULL. Part of the Стабильный ABI on Windows since version 3.7.

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

Availability: Окна.

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

Возвращаемое значение: Всегда NULL. Part of the Стабильный ABI on Windows since version 3.7.

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

Availability: Окна.

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

Возвращаемое значение: Всегда NULL. Part of the Стабильный ABI on Windows since version 3.7.

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

Availability: Окна.

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

Возвращаемое значение: Всегда NULL. Part of the Стабильный ABI on Windows since version 3.7.

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

Availability: Окна.

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

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

Возвращаемое значение: Всегда NULL. Part of the Стабильный ABI on Windows since version 3.7.

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

Availability: Окна.

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

Возвращаемое значение: Всегда NULL. Part of the Стабильный ABI since version 3.7.

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

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

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

Возвращаемое значение: Всегда NULL. Part of the Стабильный ABI since version 3.6.

Очень похоже на : c:func: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)¶

Part of the Стабильный ABI since version 3.7.

Например PyErr_SyntaxLocationObject(), но имя файла - это строка байтов, декодированная из filesystem encoding and error handler.

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

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

Part of the Стабильный ABI.

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

void PyErr_BadInternalCall()¶

Part of the Стабильный ABI.

Это сокращение от PyErr_SetString(PyExc_SystemError, 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)¶

Part of the Стабильный ABI.

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

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

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

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

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

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

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

Part of the Стабильный 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, ...)¶

Part of the Стабильный ABI.

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

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

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

Part of the Стабильный ABI since version 3.6.

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

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

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

PyObject *PyErr_Occurred()¶

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

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

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

Примечание

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

int PyErr_ExceptionMatches(PyObject *exc)¶

Part of the Стабильный ABI.

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

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

Part of the Стабильный ABI.

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

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

Part of the Стабильный ABI.

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

Part of the Стабильный ABI.

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

Примечание

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

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

Part of the Стабильный ABI.

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

Примечание

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

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

PyObject *PyErr_GetHandledException(void)¶

Part of the Стабильный ABI since version 3.11.

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

Примечание

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

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

void PyErr_SetHandledException(PyObject *exc)¶

Part of the Стабильный ABI since version 3.11.

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

Примечание

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

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

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

Part of the Стабильный ABI since version 3.7.

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

Примечание

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

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

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

Part of the Стабильный ABI since version 3.7.

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

Примечание

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

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

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

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

int PyErr_CheckSignals()¶

Part of the Стабильный ABI.

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

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

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

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

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

Примечание

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

void PyErr_SetInterrupt()¶

Part of the Стабильный ABI.

Смоделируйте эффект поступления сигнала a SIGINT. Это эквивалентно PyErr_SetInterruptEx(SIGINT).

Примечание

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

int PyErr_SetInterruptEx(int signum)¶

Part of the Стабильный ABI since version 3.10.

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

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

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

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

Примечание

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

Добавлено в версии 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)¶

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

Эта служебная функция создает и возвращает новый класс исключений. Аргумент name должен быть именем нового исключения, строкой на языке Си вида module.classname. Аргументы base и dict обычно имеют значение NULL. При этом создается объект класса, производный от Exception (доступный в C как : c:data:PyExc_Exception).

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

PyObject *PyErr_NewExceptionWithDoc(const char *name, const char *doc, PyObject *base, PyObject *dict)¶

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

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

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

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

PyObject *PyException_GetTraceback(PyObject *ex)¶

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

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

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

Part of the Стабильный ABI.

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

PyObject *PyException_GetContext(PyObject *ex)¶

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

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

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

Part of the Стабильный ABI.

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

PyObject *PyException_GetCause(PyObject *ex)¶

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

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

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

Part of the Стабильный ABI.

Задайте для причины, связанной с исключением, значение cause. Используйте NULL, чтобы удалить его. Нет проверки типа, чтобы убедиться, что cause является либо экземпляром исключения, либо None. Это приводит к краже ссылки на причину.

Эта функция неявно присваивает атрибуту __suppress_context__ значение True.

Объекты исключений в Юникоде¶

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

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

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

PyObject *PyUnicodeDecodeError_GetEncoding(PyObject *exc)¶

PyObject *PyUnicodeEncodeError_GetEncoding(PyObject *exc)¶

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

Возвращает атрибут encoding данного объекта exception.

PyObject *PyUnicodeDecodeError_GetObject(PyObject *exc)¶

PyObject *PyUnicodeEncodeError_GetObject(PyObject *exc)¶

PyObject *PyUnicodeTranslateError_GetObject(PyObject *exc)¶

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

Возвращает атрибут object данного объекта exception.

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)¶

Part of the Стабильный ABI.

Получаем атрибут start данного объекта exception и помещаем его в *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)¶

Part of the Стабильный 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)¶

Part of the Стабильный ABI.

Получаем атрибут end данного объекта exception и помещаем его в *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)¶

Part of the Стабильный ABI.

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

PyObject *PyUnicodeDecodeError_GetReason(PyObject *exc)¶

PyObject *PyUnicodeEncodeError_GetReason(PyObject *exc)¶

PyObject *PyUnicodeTranslateError_GetReason(PyObject *exc)¶

Возвращаемое значение: Новая ссылка. Part of the Стабильный 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)¶

Part of the Стабильный ABI.

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

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

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

int Py_EnterRecursiveCall(const char *where)¶

Part of the Стабильный ABI since version 3.9.

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

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

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

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

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

void Py_LeaveRecursiveCall(void)¶

Part of the Стабильный ABI since version 3.9.

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

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

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

int Py_ReprEnter(PyObject *object)¶

Part of the Стабильный ABI.

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

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

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

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

void Py_ReprLeave(PyObject *object)¶

Part of the Стабильный ABI.

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

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

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

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

Записи:

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

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

Записи: