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

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

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

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

Примечание

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

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

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, ...)

Return value: Always NULL.

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

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

Return value: Always 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()

Return value: Always NULL.

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

PyObject* PyErr_SetFromErrno(PyObject *type)

Return value: Always NULL.

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

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

Return value: Always NULL.

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

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

Return value: Always NULL.

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

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

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

Return value: Always NULL.

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

PyObject* PyErr_SetFromWindowsErr(int ierr)

Return value: Always NULL.

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

Availability: Windows.

PyObject* PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)

Return value: Always NULL.

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

Availability: Windows.

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

Return value: Always NULL.

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

Availability: Windows.

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

Return value: Always NULL.

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

Availability: Windows.

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

Return value: Always NULL.

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

Availability: Windows.

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

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

Return value: Always NULL.

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

Availability: Windows.

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

Return value: Always NULL.

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

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

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 в документации к командной строке. Отсутствует C API для управления предупреждениями.

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

Return value: Always NULL.

Очень походит на PyErr_SetImportError(), но функция позволяет задать подкласс ImportError для поднятия.

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

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

Return value: Borrowed reference.

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

Примечание

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

int PyErr_ExceptionMatches(PyObject *exc)

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

int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)

Возвращает true, если given исключение соответствует типу исключения в 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);

   /* ... код, который может вызывать другие ошибки ... */

   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)

Return value: New reference.

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

Return value: New reference.

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

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

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

PyObject* PyException_GetTraceback(PyObject *ex)

Return value: New reference.

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

int PyException_SetTraceback(PyObject *ex, PyObject *tb)

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

PyObject* PyException_GetContext(PyObject *ex)

Return value: New reference.

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

void PyException_SetContext(PyObject *ex, PyObject *ctx)

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

PyObject* PyException_GetCause(PyObject *ex)

Return value: New reference.

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

void PyException_SetCause(PyObject *ex, PyObject *cause)

Установить причину, связанную с исключением, в значение cause. Используйте NULL, чтобы очистить его. Нет проверки типа, чтобы убедиться, что cause является сущностью исключения или None. Крадёт ссылку на cause.

Функция неявно устанавливает для __suppress_context__ значение True.

Объекты исключения Юникода

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

Return value: New reference.

Создать объект 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)

Return value: New reference.

Создать объект 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)

Return value: New reference.

Создать объект 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)

Return value: New reference.

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

PyObject* PyUnicodeDecodeError_GetObject(PyObject *exc)

PyObject* PyUnicodeEncodeError_GetObject(PyObject *exc) PyObject* PyUnicodeTranslateError_GetObject(PyObject *exc)

Return value: New reference.

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

Return value: New reference.

Возвращает 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 код (который отслеживает его глубину рекурсии автоматически).

int Py_EnterRecursiveCall(const char *where)

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

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

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

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

void Py_LeaveRecursiveCall()

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

Для правильной реализации 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*; все они являются объектами класса. Для полноты, далее приведены все переменные:

C имя	Python имя	Прим.
PyExc_BaseException	BaseException	(1)
PyExc_Exception	Exception	(1)
PyExc_ArithmeticError	ArithmeticError	(1)
PyExc_AssertionError	AssertionError
PyExc_AttributeError	AttributeError
PyExc_BlockingIOError	BlockingIOError
PyExc_BrokenPipeError	BrokenPipeError
PyExc_BufferError	BufferError
PyExc_ChildProcessError	ChildProcessError
PyExc_ConnectionAbortedError	ConnectionAbortedError
PyExc_ConnectionError	ConnectionError
PyExc_ConnectionRefusedError	ConnectionRefusedError
PyExc_ConnectionResetError	ConnectionResetError
PyExc_EOFError	EOFError
PyExc_FileExistsError	FileExistsError
PyExc_FileNotFoundError	FileNotFoundError
PyExc_FloatingPointError	FloatingPointError
PyExc_GeneratorExit	GeneratorExit
PyExc_ImportError	ImportError
PyExc_IndentationError	IndentationError
PyExc_IndexError	IndexError
PyExc_InterruptedError	InterruptedError
PyExc_IsADirectoryError	IsADirectoryError
PyExc_KeyError	KeyError
PyExc_KeyboardInterrupt	KeyboardInterrupt
PyExc_LookupError	LookupError	(1)
PyExc_MemoryError	MemoryError
PyExc_ModuleNotFoundError	ModuleNotFoundError
PyExc_NameError	NameError
PyExc_NotADirectoryError	NotADirectoryError
PyExc_NotImplementedError	NotImplementedError
PyExc_OSError	OSError	(1)
PyExc_OverflowError	OverflowError
PyExc_PermissionError	PermissionError
PyExc_ProcessLookupError	ProcessLookupError
PyExc_RecursionError	RecursionError
PyExc_ReferenceError	ReferenceError	(2)
PyExc_RuntimeError	RuntimeError
PyExc_StopAsyncIteration	StopAsyncIteration
PyExc_StopIteration	StopIteration
PyExc_SyntaxError	SyntaxError
PyExc_SystemError	SystemError
PyExc_SystemExit	SystemExit
PyExc_TabError	TabError
PyExc_TimeoutError	TimeoutError
PyExc_TypeError	TypeError
PyExc_UnboundLocalError	UnboundLocalError
PyExc_UnicodeDecodeError	UnicodeDecodeError
PyExc_UnicodeEncodeError	UnicodeEncodeError
PyExc_UnicodeError	UnicodeError
PyExc_UnicodeTranslateError	UnicodeTranslateError
PyExc_ValueError	ValueError
PyExc_ZeroDivisionError	ZeroDivisionError

Добавлено в версии 3.3: PyExc_BlockingIOError, PyExc_BrokenPipeError, PyExc_ChildProcessError, PyExc_ConnectionError, PyExc_ConnectionAbortedError, PyExc_ConnectionRefusedError, PyExc_ConnectionResetError, PyExc_FileExistsError, PyExc_FileNotFoundError, PyExc_InterruptedError, PyExc_IsADirectoryError, PyExc_NotADirectoryError, PyExc_PermissionError, PyExc_ProcessLookupError and PyExc_TimeoutError were introduced following PEP 3151.

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

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

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

C имя	Прим.
PyExc_EnvironmentError
PyExc_IOError
PyExc_WindowsError	(3)

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

Примечания:

1. Это базовый класс для других стандартных исключений.
2. Определяется только в Windows; защитите код, использующий эту функцию, проверив, что определен MS_WINDOWS макрос препроцессора.

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

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

C имя	Python имя	Прим.
PyExc_Warning	Warning	(1)
PyExc_BytesWarning	BytesWarning
PyExc_DeprecationWarning	DeprecationWarning
PyExc_FutureWarning	FutureWarning
PyExc_ImportWarning	ImportWarning
PyExc_PendingDeprecationWarning	PendingDeprecationWarning
PyExc_ResourceWarning	ResourceWarning
PyExc_RuntimeWarning	RuntimeWarning
PyExc_SyntaxWarning	SyntaxWarning
PyExc_UnicodeWarning	UnicodeWarning
PyExc_UserWarning	UserWarning

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

Примечания:

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