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

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

void PyErr_Clear()

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

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

void PyErr_PrintEx(int set_sys_last_vars)

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

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

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

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

void PyErr_Print()

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

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

void PyErr_WriteUnraisable(PyObject *obj)

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

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

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

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

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

Выбрасывание исключений

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

Это вспомогательная функция для повышения исключения 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. Часть Стабильной ABI в Windows начиная с версии 3.7.

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

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

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

Значение возврата: всегда NULL. Часть Стабильной ABI в Windows начиная с версии 3.7.

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

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

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

Значение возврата: всегда NULL. Часть Стабильной ABI в Windows начиная с версии 3.7.

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

Доступность: 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 является кортежем, все типы исключений в кортеже (и рекурсивно в подкортежах) проверяются на соответствие.

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

Часть Стабильной 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)

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

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

Примечание

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

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

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

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

Примечание

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

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

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

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

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

Примечание

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

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

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

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

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

Примечание

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

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

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

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)

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

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

int PyException_SetTraceback(PyObject *ex, PyObject *tb)

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

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

PyObject *PyException_GetContext(PyObject *ex)

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

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

void PyException_SetContext(PyObject *ex, PyObject *ctx)

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

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

PyObject *PyException_GetCause(PyObject *ex)

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

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

void PyException_SetCause(PyObject *ex, PyObject *cause)

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

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

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

Объекты исключений 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 *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)

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

Примечания:

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

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

2

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

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

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

Примечания:

3

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