/
• Переводы документации
/
• Документация Python 3.8.8 /
• Справочное руководство по Python/C API /
• Обработка исключений

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

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

« предыдущий | следующий »