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

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

void PyErr_Clear()¶

Part of the Stable ABI.

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

void PyErr_PrintEx(int set_sys_last_vars)¶

Part of the Stable ABI.

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

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

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

void PyErr_Print()¶

Part of the Stable ABI.

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

void PyErr_WriteUnraisable(PyObject *obj)¶

Part of the Stable ABI.

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

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

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

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

Воспитание исключений¶

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

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

Part of the Stable ABI.

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

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

Part of the Stable ABI.

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

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

Return value: Always NULL. Part of the Stable ABI.

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

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

Return value: Always NULL. Part of the Stable ABI since version 3.5.

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

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

void PyErr_SetNone(PyObject *type)¶

Part of the Stable ABI.

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

int PyErr_BadArgument()¶

Part of the Stable ABI.

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

PyObject *PyErr_NoMemory()¶

Return value: Always NULL. Part of the Stable ABI.

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

PyObject *PyErr_SetFromErrno(PyObject *type)¶

Return value: Always NULL. Part of the Stable ABI.

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

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

Return value: Always NULL. Part of the Stable ABI.

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

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

Return value: Always NULL. Part of the Stable ABI since version 3.7.

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

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

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

Return value: Always NULL. Part of the Stable ABI.

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

PyObject *PyErr_SetFromWindowsErr(int ierr)¶

Return value: Always NULL. Part of the Stable ABI on Windows since version 3.7.

Это удобная функция для повышения 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. Part of the Stable ABI on Windows since version 3.7.

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

Availability: Windows.

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

Return value: Always NULL. Part of the Stable ABI on Windows since version 3.7.

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

Availability: Windows.

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

Return value: Always NULL. Part of the Stable ABI on Windows since version 3.7.

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

Availability: Windows.

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

Return value: Always NULL. Part of the Stable ABI on Windows since version 3.7.

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

Availability: Windows.

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

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

Return value: Always NULL. Part of the Stable ABI on Windows since version 3.7.

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

Availability: Windows.

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

Return value: Always NULL. Part of the Stable ABI since version 3.7.

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

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

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

Return value: Always NULL. Part of the Stable ABI since version 3.6.

Аналогично PyErr_SetImportError(), но эта функция позволяет указать подкласс ImportError для повышения.

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

void PyErr_SyntaxLocationObject(PyObject *filename, int lineno, int col_offset)¶

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

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

void PyErr_SyntaxLocationEx(const char *filename, int lineno, int col_offset)¶

Part of the Stable ABI since version 3.7.

Подобно PyErr_SyntaxLocationObject(), но filename - это байтовая строка, декодированная из filesystem encoding and error handler.

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

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

Part of the Stable ABI.

Аналогично PyErr_SyntaxLocationEx(), но параметр col_offset опущен.

void PyErr_BadInternalCall()¶

Part of the Stable ABI.

Это сокращение для PyErr_SetString(PyExc_SystemError, message), где сообщение указывает, что внутренняя операция (например, функция API Python/C) была вызвана с недопустимым аргументом. Это в основном для внутреннего использования.

Вынесение предупреждений¶

Используйте эти функции для выдачи предупреждений из кода на языке Си. Они повторяют аналогичные функции, экспортируемые модулем Python warnings. Обычно они выводят предупреждение на sys.stderr; однако возможно, что пользователь указал, что предупреждения должны быть превращены в ошибки, и в этом случае они вызовут исключение. Также возможно, что функции вызывают исключение из-за проблемы с механизмом предупреждений. Возвращаемое значение 0, если исключение не возникло, или -1, если исключение возникло. (Невозможно определить, было ли на самом деле выведено предупреждение или причина исключения; это сделано намеренно). Если возникло исключение, вызывающая программа должна выполнить свою обычную обработку исключений (например, Py_DECREF() принадлежащие ссылки и вернуть значение ошибки).

int PyErr_WarnEx(PyObject *category, const char *message, Py_ssize_t stack_level)¶

Part of the Stable ABI.

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

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

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

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

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

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

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

Part of the Stable ABI.

Аналогично PyErr_WarnExplicitObject() за исключением того, что message и module являются строками в кодировке UTF-8, а filename декодируется из filesystem encoding and error handler.

int PyErr_WarnFormat(PyObject *category, Py_ssize_t stack_level, const char *format, ...)¶

Part of the Stable ABI.

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

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

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

Part of the Stable ABI since version 3.6.

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

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

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

PyObject *PyErr_Occurred()¶

Return value: Borrowed reference. Part of the Stable ABI.

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

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

Примечание

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

int PyErr_ExceptionMatches(PyObject *exc)¶

Part of the Stable ABI.

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

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

Part of the Stable ABI.

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

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

Part of the Stable ABI.

Извлеките индикатор ошибки в три переменные, адреса которых переданы. Если индикатор ошибки не установлен, установите все три переменные в NULL. Если он установлен, он будет очищен, и вы станете владельцем ссылки на каждый извлеченный объект. Объект value и traceback может быть NULL, даже если объект type не является таковым.

Примечание

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

{
   PyObject *type, *value, *traceback;
   PyErr_Fetch(&type, &value, &traceback);

   /* ... code that might produce other errors ... */

   PyErr_Restore(type, value, traceback);
}

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

Part of the Stable ABI.

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

Примечание

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

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

Part of the Stable ABI.

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

Примечание

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

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

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

Part of the Stable ABI since version 3.7.

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

Примечание

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

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

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

Part of the Stable ABI since version 3.7.

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

Примечание

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

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

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

int PyErr_CheckSignals()¶

Part of the Stable ABI.

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

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

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

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

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

Примечание

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

void PyErr_SetInterrupt()¶

Part of the Stable ABI.

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

Примечание

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

int PyErr_SetInterruptEx(int signum)¶

Part of the Stable ABI since version 3.10.

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

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

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

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

Примечание

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

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

int PySignal_SetWakeupFd(int fd)¶

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

Значение -1 отключает функцию; это начальное состояние. Это эквивалентно signal.set_wakeup_fd() в Python, но без какой-либо проверки ошибок. fd должен быть корректным дескриптором файла. Функция должна вызываться только из главного потока.

Изменено в версии 3.5: В Windows эта функция теперь также поддерживает ручки сокетов.

Классы исключений¶

PyObject *PyErr_NewException(const char *name, PyObject *base, PyObject *dict)¶

Return value: New reference. Part of the Stable ABI.

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

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

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

Return value: New reference. Part of the Stable ABI.

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

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

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

PyObject *PyException_GetTraceback(PyObject *ex)¶

Return value: New reference. Part of the Stable ABI.

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

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

Part of the Stable ABI.

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

PyObject *PyException_GetContext(PyObject *ex)¶

Return value: New reference. Part of the Stable ABI.

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

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

Part of the Stable ABI.

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

PyObject *PyException_GetCause(PyObject *ex)¶

Return value: New reference. Part of the Stable ABI.

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

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

Part of the Stable ABI.

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

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

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

Следующие функции используются для создания и изменения исключений Unicode из языка C.

PyObject *PyUnicodeDecodeError_Create(const char *encoding, const char *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)¶

Return value: New reference. Part of the Stable ABI.

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

PyObject *PyUnicodeEncodeError_Create(const char *encoding, const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)¶

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. причина - это строка в кодировке 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. Part of the Stable ABI.

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

PyObject *PyUnicodeDecodeError_GetObject(PyObject *exc)¶

PyObject *PyUnicodeEncodeError_GetObject(PyObject *exc)¶

PyObject *PyUnicodeTranslateError_GetObject(PyObject *exc)¶

Return value: New reference. Part of the Stable ABI.

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

int PyUnicodeDecodeError_GetStart(PyObject *exc, Py_ssize_t *start)¶

int PyUnicodeEncodeError_GetStart(PyObject *exc, Py_ssize_t *start)¶

int PyUnicodeTranslateError_GetStart(PyObject *exc, Py_ssize_t *start)¶

Part of the Stable ABI.

Получить атрибут start данного объекта исключения и поместить его в *start. start не должен быть NULL. Возвращает 0 при успехе, -1 при неудаче.

int PyUnicodeDecodeError_SetStart(PyObject *exc, Py_ssize_t start)¶

int PyUnicodeEncodeError_SetStart(PyObject *exc, Py_ssize_t start)¶

int PyUnicodeTranslateError_SetStart(PyObject *exc, Py_ssize_t start)¶

Part of the Stable ABI.

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

int PyUnicodeDecodeError_GetEnd(PyObject *exc, Py_ssize_t *end)¶

int PyUnicodeEncodeError_GetEnd(PyObject *exc, Py_ssize_t *end)¶

int PyUnicodeTranslateError_GetEnd(PyObject *exc, Py_ssize_t *end)¶

Part of the Stable ABI.

Получить атрибут end данного объекта исключения и поместить его в *end. end не должен быть NULL. Возвращает 0 при успехе, -1 при неудаче.

int PyUnicodeDecodeError_SetEnd(PyObject *exc, Py_ssize_t end)¶

int PyUnicodeEncodeError_SetEnd(PyObject *exc, Py_ssize_t end)¶

int PyUnicodeTranslateError_SetEnd(PyObject *exc, Py_ssize_t end)¶

Part of the Stable ABI.

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

PyObject *PyUnicodeDecodeError_GetReason(PyObject *exc)¶

PyObject *PyUnicodeEncodeError_GetReason(PyObject *exc)¶

PyObject *PyUnicodeTranslateError_GetReason(PyObject *exc)¶

Return value: New reference. Part of the Stable ABI.

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

int PyUnicodeDecodeError_SetReason(PyObject *exc, const char *reason)¶

int PyUnicodeEncodeError_SetReason(PyObject *exc, const char *reason)¶

int PyUnicodeTranslateError_SetReason(PyObject *exc, const char *reason)¶

Part of the Stable ABI.

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

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

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

int Py_EnterRecursiveCall(const char *where)¶

Part of the Stable ABI since version 3.9.

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

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

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

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

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

void Py_LeaveRecursiveCall(void)¶

Part of the Stable ABI since version 3.9.

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

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

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

int Py_ReprEnter(PyObject *object)¶

Part of the Stable ABI.

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

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

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

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

void Py_ReprLeave(PyObject *object)¶

Part of the Stable ABI.

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

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

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

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

Примечания:

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

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

2

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

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

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

Примечания:

3

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