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

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

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

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

Примечание

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

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

PyObject* PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)
Return value: Always NULL.

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

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

PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)
Return value: Always NULL.

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

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

PyObject* PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject *type, int ierr, PyObject *filename)
Return value: Always NULL.

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

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

PyObject* PyErr_SetExcFromWindowsErrWithFilenameObjects(PyObject *type, int ierr, PyObject *filename, PyObject *filename2)
Return value: Always NULL.

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

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

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

PyObject* PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, const char *filename)
Return value: Always NULL.

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

Доступность: 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 указывает, что внутренняя операция (например, функция 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)

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

Возвращает истину, если исключение given соответствует типу исключения в exc. Если exc является объектом класса, это также возвращает истину, когда 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 не является экземпляром того же класса. В этом случае эту функцию можно использовать для создания экземпляра класса. Если значения уже нормализованы, ничего не происходит. Отложенная нормализация реализована для повышения производительности.

Примечание

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