`exceptions.md`

881 строк · 81.2 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.12/c-api/exceptions.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Обработка исключений89Функции, описанные в этой главе, позволяют обрабатывать и возбуждать исключения Python. Важно понимать некоторые основы обработки исключений Python. Она работает примерно как переменная `errno` в POSIX: существует глобальный индикатор (на поток) последней произошедшей ошибки. Большинство функций C API не очищают его при успехе, но устанавливают его, чтобы указать причину ошибки при неудаче. Большинство функций C API также возвращают индикатор ошибки, обычно `NULL`, если они должны вернуть указатель, или `-1`, если они возвращают целое число (исключение: функции `PyArg_*` возвращают `1` при успехе и `0` при неудаче).1011Конкретно, индикатор ошибки состоит из трех указателей на объекты: тип исключения, значение исключения и объект трассировки. Любой из этих указателей может быть `NULL`, если не установлен (хотя некоторые комбинации запрещены, например, нельзя иметь не-`NULL` трассировку, если тип исключения `NULL`).1213Когда функция должна завершиться ошибкой, потому что вызванная ей функция завершилась ошибкой, она обычно не устанавливает индикатор ошибки; его уже установила вызванная функция. Она отвечает либо за обработку ошибки и очистку исключения, либо за возврат после освобождения всех удерживаемых ресурсов (таких как ссылки на объекты или выделенная память); она *не* должна продолжать нормальное выполнение, если не готова обработать ошибку. При возврате из-за ошибки важно указать вызывающему коду, что ошибка была установлена. Если ошибка не обрабатывается или не аккуратно распространяется, последующие вызовы Python/C API могут вести себя не так, как задумано, и могут отказать загадочным образом.1415> **Примечание**16>17> Индикатор ошибки **не** является результатом [`sys.exc_info()`](https://python-all.ru/3.12/library/sys.html#sys.exc_info). Первый соответствует исключению, которое еще не перехвачено (и поэтому все еще распространяется), тогда как второй возвращает исключение после его перехвата (и поэтому прекратило распространение).1819## Печать и очистка2021#### `void PyErr_Clear()`2223*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*2425Очищает индикатор ошибки. Если индикатор ошибки не установлен, эффекта нет.2627#### `void PyErr_PrintEx(int set_sys_last_vars)`2829*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*3031Печатает стандартную трассировку в `sys.stderr` и очищает индикатор ошибки. **За исключением** случая, когда ошибка является `SystemExit`, в этом случае трассировка не печатается, и процесс Python завершится с кодом ошибки, указанным экземпляром `SystemExit`.3233Вызывайте эту функцию **только**, когда установлен индикатор ошибки. В противном случае это вызовет фатальную ошибку!3435Если *set\_sys\_last\_vars* не равно нулю, переменная [`sys.last_exc`](https://python-all.ru/3.12/library/sys.html#sys.last_exc) устанавливается в напечатанное исключение. Для обратной совместимости устаревшие переменные [`sys.last_type`](https://python-all.ru/3.12/library/sys.html#sys.last_type), [`sys.last_value`](https://python-all.ru/3.12/library/sys.html#sys.last_value) и [`sys.last_traceback`](https://python-all.ru/3.12/library/sys.html#sys.last_traceback) также устанавливаются в тип, значение и трассировку этого исключения соответственно.3637Изменено в версии 3.12: Добавлена установка [`sys.last_exc`](https://python-all.ru/3.12/library/sys.html#sys.last_exc).3839#### `void PyErr_Print()`4041*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*4243Псевдоним для `PyErr_PrintEx(1)`.4445#### `void PyErr_WriteUnraisable(PyObject *obj)`4647*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*4849Вызывает [`sys.unraisablehook()`](https://python-all.ru/3.12/library/sys.html#sys.unraisablehook) с использованием текущего исключения и аргумента *obj*.5051Эта вспомогательная функция выводит предупреждающее сообщение в `sys.stderr`, когда исключение было установлено, но интерпретатор не может его фактически возбудить. Она используется, например, когда исключение возникает в методе [`__del__()`](https://python-all.ru/3.12/reference/datamodel.html#object.__del__).5253Функция вызывается с единственным аргументом *obj*, который идентифицирует контекст, в котором возникло невыбрасываемое исключение. Если возможно, repr *obj* будет напечатан в предупреждающем сообщении. Если *obj* равен `NULL`, печатается только трассировка.5455При вызове этой функции должно быть установлено исключение.5657Изменено в версии 3.4: Печатает трассировку. Печатает только трассировку, если *obj* равен `NULL`.5859Изменено в версии 3.8: Используйте [`sys.unraisablehook()`](https://python-all.ru/3.12/library/sys.html#sys.unraisablehook).6061#### `void PyErr_DisplayException(PyObject *exc)`6263*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.12.*6465Печатает стандартное отображение трассировки `exc` в `sys.stderr`, включая цепочки исключений и примечания.6667Добавлено в версии 3.12.6869## Возбуждение исключений7071Эти функции помогают установить индикатор ошибки текущего потока. Для удобства некоторые из этих функций всегда возвращают указатель `NULL` для использования в операторе `return`.7273#### `void PyErr_SetString(PyObject *type, const char *message)`7475*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*7677Это наиболее распространенный способ установки индикатора ошибки. Первый аргумент указывает тип исключения; обычно это одно из стандартных исключений, например `PyExc_RuntimeError`. Не нужно создавать новую [сильную ссылку](https://python-all.ru/3.12/glossary.html#term-strong-reference) на него (например, с помощью [`Py_INCREF()`](https://python-all.ru/3.12/c-api/refcounting.html#c.Py_INCREF)). Второй аргумент – сообщение об ошибке; оно декодируется из `'utf-8'`.7879#### `void PyErr_SetObject(PyObject *type, PyObject *value)`8081*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*8283Эта функция аналогична [`PyErr_SetString()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_SetString), но позволяет указать произвольный объект Python для «значения» исключения.8485#### `PyObject *PyErr_Format(PyObject *exception, const char *format, ...)`8687*Возвращаемое значение: всегда NULL.*8889*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*9091Эта функция устанавливает индикатор ошибки и возвращает `NULL`. *исключение* должен быть классом исключения Python. Параметры *format* и последующие помогают форматировать сообщение об ошибке; они имеют тот же смысл и значения, что и в [`PyUnicode_FromFormat()`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_FromFormat). *format* – это строка в кодировке ASCII.9293#### `PyObject *PyErr_FormatV(PyObject *exception, const char *format, va_list vargs)`9495*Возвращаемое значение: Всегда NULL.*9697*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.5.*9899То же, что и [`PyErr_Format()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_Format), но принимает аргумент `va_list` вместо переменного числа аргументов.100101Добавлено в версии 3.5.102103#### `void PyErr_SetNone(PyObject *type)`104105*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*106107Это сокращение для `PyErr_SetObject(type, Py_None)`.108109#### `int PyErr_BadArgument()`110111*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*112113Это сокращение для `PyErr_SetString(PyExc_TypeError, message)`, где *message* указывает, что встроенная операция была вызвана с недопустимым аргументом. В основном предназначено для внутреннего использования.114115#### `PyObject *PyErr_NoMemory()`116117*Возвращаемое значение: всегда NULL.*118119*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*120121Это сокращение для `PyErr_SetNone(PyExc_MemoryError)`; оно возвращает `NULL`, чтобы функция выделения объекта могла написать `return PyErr_NoMemory();`, когда заканчивается память.122123#### `PyObject *PyErr_SetFromErrno(PyObject *type)`124125*Возвращаемое значение: всегда NULL.*126127*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*128129Это удобная функция для возбуждения исключения, когда функция библиотеки C вернула ошибку и установила переменную C `errno`. Она создает объект кортежа, первый элемент которого – целочисленное значение `errno`, а второй – соответствующее сообщение об ошибке (полученное из `strerror()`), а затем вызывает `PyErr_SetObject(type, object)`. В Unix, когда значение `errno` равно `EINTR`, что указывает на прерванный системный вызов, эта функция вызывает [`PyErr_CheckSignals()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_CheckSignals), и если та устанавливает индикатор ошибки, оставляет его установленным на это. Функция всегда возвращает `NULL`, так что функция-обертка вокруг системного вызова может написать `return PyErr_SetFromErrno(type);`, когда системный вызов возвращает ошибку.130131#### `PyObject *PyErr_SetFromErrnoWithFilenameObject(PyObject *type, PyObject *filenameObject)`132133*Возвращаемое значение: всегда NULL.*134135*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*136137Аналогично [`PyErr_SetFromErrno()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_SetFromErrno), с тем дополнением, что если *filenameObject* не равно `NULL`, он передаётся конструктору *type* в качестве третьего параметра. В случае исключения [`OSError`](https://python-all.ru/3.12/library/exceptions.html#OSError) это используется для задания атрибута `filename` экземпляра исключения.138139#### `PyObject *PyErr_SetFromErrnoWithFilenameObjects(PyObject *type, PyObject *filenameObject, PyObject *filenameObject2)`140141*Возвращаемое значение: всегда NULL.*142143*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.7.*144145Аналогично [`PyErr_SetFromErrnoWithFilenameObject()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_SetFromErrnoWithFilenameObject), но принимает второй объект имени файла; используется для возбуждения ошибок, когда функция, принимающая два имени файла, завершается неудачей.146147Добавлено в версии 3.4.148149#### `PyObject *PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename)`150151*Возвращаемое значение: всегда NULL.*152153*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*154155Аналогично [`PyErr_SetFromErrnoWithFilenameObject()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_SetFromErrnoWithFilenameObject), но имя файла задаётся как C-строка. *filename* декодируется с использованием [кодировки файловой системы и обработчика ошибок](https://python-all.ru/3.12/glossary.html#term-filesystem-encoding-and-error-handler).156157#### `PyObject *PyErr_SetFromWindowsErr(int ierr)`158159*Возвращаемое значение: всегда NULL.*160161*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) на Windows начиная с версии 3.7.*162163Это удобная функция для возбуждения [`OSError`](https://python-all.ru/3.12/library/exceptions.html#OSError). Если она вызвана с *ierr* равным `0`, то вместо него используется код ошибки, возвращённый вызовом `GetLastError()`. Она вызывает функцию Win32 `FormatMessage()` для получения описания Windows для кода ошибки, заданного *ierr* или `GetLastError()`, затем создаёт объект [`OSError`](https://python-all.ru/3.12/library/exceptions.html#OSError), устанавливая атрибут [`winerror`](https://python-all.ru/3.12/library/exceptions.html#OSError.winerror) в код ошибки, атрибут [`strerror`](https://python-all.ru/3.12/library/exceptions.html#OSError.strerror) – в соответствующее сообщение об ошибке (полученное из `FormatMessage()`), после чего вызывает `PyErr_SetObject(PyExc_OSError, object)`. Эта функция всегда возвращает `NULL`.164165[Доступность](https://python-all.ru/3.12/library/intro.html#availability): Windows.166167#### `PyObject *PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)`168169*Возвращаемое значение: всегда NULL.*170171*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) на Windows начиная с версии 3.7.*172173Аналогично [`PyErr_SetFromWindowsErr()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_SetFromWindowsErr), с дополнительным параметром, указывающим тип возбуждаемого исключения.174175[Доступность](https://python-all.ru/3.12/library/intro.html#availability): Windows.176177#### `PyObject *PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)`178179*Возвращаемое значение: всегда NULL.*180181*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) на Windows начиная с версии 3.7.*182183Аналогично [`PyErr_SetFromWindowsErr()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_SetFromWindowsErr), с тем дополнением, что если *filename* не равно `NULL`, он декодируется из кодировки файловой системы ([`os.fsdecode()`](https://python-all.ru/3.12/library/os.html#os.fsdecode)) и передаётся конструктору [`OSError`](https://python-all.ru/3.12/library/exceptions.html#OSError) в качестве третьего параметра для задания атрибута `filename` экземпляра исключения.184185[Доступность](https://python-all.ru/3.12/library/intro.html#availability): Windows.186187#### `PyObject *PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject *type, int ierr, PyObject *filename)`188189*Возвращаемое значение: всегда NULL.*190191*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) на Windows начиная с версии 3.7.*192193Аналогично [`PyErr_SetExcFromWindowsErr()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_SetExcFromWindowsErr), с тем дополнением, что если *filename* не равно `NULL`, он передаётся конструктору [`OSError`](https://python-all.ru/3.12/library/exceptions.html#OSError) в качестве третьего параметра для задания атрибута `filename` экземпляра исключения.194195[Доступность](https://python-all.ru/3.12/library/intro.html#availability): Windows.196197#### `PyObject *PyErr_SetExcFromWindowsErrWithFilenameObjects(PyObject *type, int ierr, PyObject *filename, PyObject *filename2)`198199*Возвращаемое значение: всегда NULL.*200201*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) на Windows начиная с версии 3.7.*202203Аналогично [`PyErr_SetExcFromWindowsErrWithFilenameObject()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_SetExcFromWindowsErrWithFilenameObject), но принимает второй объект имени файла.204205[Доступность](https://python-all.ru/3.12/library/intro.html#availability): Windows.206207Добавлено в версии 3.4.208209#### `PyObject *PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, const char *filename)`210211*Возвращаемое значение: всегда NULL.*212213*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) на Windows начиная с версии 3.7.*214215Аналогично [`PyErr_SetFromWindowsErrWithFilename()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_SetFromWindowsErrWithFilename), с дополнительным параметром, указывающим тип возбуждаемого исключения.216217[Доступность](https://python-all.ru/3.12/library/intro.html#availability): Windows.218219#### `PyObject *PyErr_SetImportError(PyObject *msg, PyObject *name, PyObject *path)`220221*Возвращаемое значение: всегда NULL.*222223*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.7.*224225Это удобная функция для возбуждения [`ImportError`](https://python-all.ru/3.12/library/exceptions.html#ImportError). *msg* будет установлен как строка сообщения исключения. *name* и *path*, оба могут быть `NULL`, будут установлены как соответствующие атрибуты [`ImportError`](https://python-all.ru/3.12/library/exceptions.html#ImportError): `name` и `path`.226227Добавлено в версии 3.3.228229#### `PyObject *PyErr_SetImportErrorSubclass(PyObject *exception, PyObject *msg, PyObject *name, PyObject *path)`230231*Возвращаемое значение: всегда NULL.*232233*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.6.*234235Очень похожа на [`PyErr_SetImportError()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_SetImportError), но эта функция позволяет указать подкласс [`ImportError`](https://python-all.ru/3.12/library/exceptions.html#ImportError) для возбуждения.236237Добавлено в версии 3.6.238239#### `void PyErr_SyntaxLocationObject(PyObject *filename, int lineno, int col_offset)`240241Устанавливает информацию о файле, строке и смещении для текущего исключения. Если текущее исключение не является [`SyntaxError`](https://python-all.ru/3.12/library/exceptions.html#SyntaxError), то устанавливаются дополнительные атрибуты, из-за которых подсистема печати исключений считает исключение [`SyntaxError`](https://python-all.ru/3.12/library/exceptions.html#SyntaxError).242243Добавлено в версии 3.4.244245#### `void PyErr_SyntaxLocationEx(const char *filename, int lineno, int col_offset)`246247*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.7.*248249Как [`PyErr_SyntaxLocationObject()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_SyntaxLocationObject), но *filename* – это байтовая строка, декодированная из [кодировки файловой системы и обработчика ошибок](https://python-all.ru/3.12/glossary.html#term-filesystem-encoding-and-error-handler).250251Добавлено в версии 3.2.252253#### `void PyErr_SyntaxLocation(const char *filename, int lineno)`254255*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*256257Как [`PyErr_SyntaxLocationEx()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_SyntaxLocationEx), но параметр *col\_offset* опущен.258259#### `void PyErr_BadInternalCall()`260261*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*262263Это сокращение для `PyErr_SetString(PyExc_SystemError, message)`, где *message* указывает, что внутренняя операция (например, функция Python/C API) была вызвана с недопустимым аргументом. Предназначено в основном для внутреннего использования.264265## Выдача предупреждений266267Используйте эти функции для выдачи предупреждений из кода на C. Они аналогичны соответствующим функциям, экспортируемым модулем Python [`warnings`](https://python-all.ru/3.12/library/warnings.html#module-warnings). Обычно они выводят предупреждающее сообщение в *sys.stderr*; однако возможно, что пользователь указал превращать предупреждения в ошибки, и в этом случае они возбудят исключение. Также возможно, что функции возбуждают исключение из-за проблемы с механизмом предупреждений. Возвращаемое значение – `0`, если исключение не возбуждено, или `-1`, если исключение возбуждено. (Невозможно определить, было ли предупреждение фактически напечатано или какова причина исключения; это сделано намеренно.) Если исключение возбуждено, вызывающий код должен выполнить обычную обработку исключений (например, [`Py_DECREF()`](https://python-all.ru/3.12/c-api/refcounting.html#c.Py_DECREF) принадлежащие ссылки и вернуть значение ошибки).268269#### `int PyErr_WarnEx(PyObject *category, const char *message, Py_ssize_t stack_level)`270271*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*272273Выдает предупреждающее сообщение. Аргумент *category* – это категория предупреждения (см. ниже) или `NULL`; аргумент *message* – это строка в кодировке UTF-8. *stack\_level* – положительное число, задающее количество фреймов стека; предупреждение будет выдано от текущей выполняемой строки кода в этом фрейме стека. *stack\_level*, равный 1, – это функция, вызывающая [`PyErr_WarnEx()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_WarnEx), 2 – функция над ней, и так далее.274275Категории предупреждений должны быть подклассами `PyExc_Warning`; `PyExc_Warning` является подклассом `PyExc_Exception`; категория предупреждений по умолчанию – `PyExc_RuntimeWarning`. Стандартные категории предупреждений Python доступны в виде глобальных переменных, имена которых перечислены в разделе [Стандартные категории предупреждений](https://python-all.ru/3.12/c-api/exceptions.html#standardwarningcategories).276277Информацию об управлении предупреждениями см. в документации модуля [`warnings`](https://python-all.ru/3.12/library/warnings.html#module-warnings) и опции [`-W`](https://python-all.ru/3.12/using/cmdline.html#cmdoption-W) в документации командной строки. API для управления предупреждениями на C не существует.278279#### `int PyErr_WarnExplicitObject(PyObject *category, PyObject *message, PyObject *filename, int lineno, PyObject *module, PyObject *registry)`280281Выдаёт предупреждение с явным контролем всех его атрибутов. Это простая обёртка вокруг функции Python [`warnings.warn_explicit()`](https://python-all.ru/3.12/library/warnings.html#warnings.warn_explicit); за подробностями обращайтесь к её документации. Аргументы *module* и *registry* могут быть установлены в `NULL`, чтобы получить описанный там эффект по умолчанию.282283Добавлено в версии 3.4.284285#### `int PyErr_WarnExplicit(PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry)`286287*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*288289Аналогично [`PyErr_WarnExplicitObject()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_WarnExplicitObject), за исключением того, что *message* и *module* являются строками в кодировке UTF-8, а *filename* декодируется из [кодировки файловой системы и обработчика ошибок](https://python-all.ru/3.12/glossary.html#term-filesystem-encoding-and-error-handler).290291#### `int PyErr_WarnFormat(PyObject *category, Py_ssize_t stack_level, const char *format, ...)`292293*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*294295Функция, аналогичная [`PyErr_WarnEx()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_WarnEx), но использующая [`PyUnicode_FromFormat()`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_FromFormat) для форматирования предупреждающего сообщения. *format* – это строка в ASCII-кодировке.296297Добавлено в версии 3.2.298299#### `int PyErr_ResourceWarning(PyObject *source, Py_ssize_t stack_level, const char *format, ...)`300301*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.6.*302303Функция аналогична [`PyErr_WarnFormat()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_WarnFormat), но *category* равен [`ResourceWarning`](https://python-all.ru/3.12/library/exceptions.html#ResourceWarning), и она передаёт *source* в `warnings.WarningMessage`.304305Добавлено в версии 3.6.306307## Опрос индикатора ошибки308309#### `PyObject *PyErr_Occurred()`310311*Возвращаемое значение: заимствованная ссылка.*312313*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*314315Проверяет, установлен ли индикатор ошибки. Если установлен, возвращает *тип* исключения (первый аргумент последнего вызова одной из функций `PyErr_Set*` или [`PyErr_Restore()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_Restore)). Если не установлен, возвращает `NULL`. Вы не владеете ссылкой на возвращаемое значение, поэтому вам не нужно [`Py_DECREF()`](https://python-all.ru/3.12/c-api/refcounting.html#c.Py_DECREF) его.316317Вызывающий должен удерживать GIL.318319> **Примечание**320>321> Не сравнивайте возвращаемое значение с конкретным исключением; используйте вместо этого [`PyErr_ExceptionMatches()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_ExceptionMatches), как показано ниже. (Сравнение может легко не сработать, так как исключение может быть экземпляром, а не классом (в случае классового исключения) или подклассом ожидаемого исключения.)322323#### `int PyErr_ExceptionMatches(PyObject *exc)`324325*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*326327Эквивалентно `PyErr_GivenExceptionMatches(PyErr_Occurred(), exc)`. Эту функцию следует вызывать только тогда, когда исключение действительно установлено; при отсутствии возбуждённого исключения произойдёт нарушение доступа к памяти.328329#### `int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)`330331*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*332333Возвращает истину, если *заданное* исключение соответствует типу исключения в *exc*. Если *exc* – объект класса, также возвращает истину, когда *given* является экземпляром подкласса. Если *exc* – кортеж, производится поиск соответствия среди всех типов исключений в кортеже (и рекурсивно во вложенных кортежах).334335#### `PyObject *PyErr_GetRaisedException(void)`336337*Возвращаемое значение: новая ссылка.*338339*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) с версии 3.12.*340341Возвращает исключение, которое в данный момент возбуждается, одновременно очищая индикатор ошибки. Возвращает `NULL`, если индикатор ошибки не установлен.342343Эта функция используется кодом, которому необходимо перехватывать исключения, или кодом, которому нужно временно сохранять и восстанавливать индикатор ошибки.344345Например:346347```c348{349   PyObject *exc = PyErr_GetRaisedException();350351   /* ... код, который может вызвать другие ошибки ... */352353   PyErr_SetRaisedException(exc);354}355```356357> **См. также**358>359> [`PyErr_GetHandledException()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_GetHandledException), чтобы сохранить исключение, которое в данный момент обрабатывается.360361Добавлено в версии 3.12.362363#### `void PyErr_SetRaisedException(PyObject *exc)`364365*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.12.*366367Устанавливает *exc* в качестве текущего возбуждаемого исключения, очищая существующее исключение, если оно было установлено.368369> **Предупреждение**370>371> Этот вызов похищает ссылку на *exc*, который должен быть допустимым исключением.372373Добавлено в версии 3.12.374375#### `void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)`376377*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*378379Устарело с версии 3.12: Используйте [`PyErr_GetRaisedException()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_GetRaisedException).380381Извлекает индикатор ошибки в три переменные, чьи адреса передаются. Если индикатор ошибки не установлен, устанавливает все три переменные в `NULL`. Если он установлен, он будет очищен, и вы получаете владение ссылкой на каждый извлеченный объект. Объекты value и traceback могут иметь значение `NULL`, даже если объект type – нет.382383> **Примечание**384>385> Эта функция обычно используется только устаревшим кодом, которому нужно перехватывать исключения или временно сохранять и восстанавливать индикатор ошибки.386>387> Например:388>389> ```c390> {391>    PyObject *type, *value, *traceback;392>    PyErr_Fetch(&type, &value, &traceback);393>394>    /* ... код, который может вызвать другие ошибки ... */395>396>    PyErr_Restore(type, value, traceback);397> }398> ```399400#### `void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback)`401402*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*403404Устарело с версии 3.12: Используйте [`PyErr_SetRaisedException()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_SetRaisedException).405406Устанавливает индикатор ошибки из трех объектов: *type*, *value* и *traceback*, очищая существующее исключение, если оно установлено. Если объекты равны `NULL`, индикатор ошибки очищается. Не передавайте `NULL` тип и не-`NULL` значение или traceback. Тип исключения должен быть классом. Не передавайте недопустимый тип или значение исключения. (Нарушение этих правил приведет к скрытым проблемам в дальнейшем.) Этот вызов забирает ссылку на каждый объект: вы должны владеть ссылкой на каждый объект до вызова, а после вызова вы больше не владеете этими ссылками. (Если вы этого не понимаете, не используйте эту функцию. Я вас предупредил.)407408> **Примечание**409>410> Эта функция обычно используется только устаревшим кодом, которому нужно временно сохранять и восстанавливать индикатор ошибки. Используйте [`PyErr_Fetch()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_Fetch), чтобы сохранить текущий индикатор ошибки.411412#### `void PyErr_NormalizeException(PyObject **exc, PyObject **val, PyObject **tb)`413414*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*415416Устарело с версии 3.12: Используйте [`PyErr_GetRaisedException()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_GetRaisedException) вместо этого, чтобы избежать возможной денормализации.417418При определенных обстоятельствах значения, возвращаемые [`PyErr_Fetch()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_Fetch) ниже, могут быть «ненормализованными», то есть `*exc` является объектом класса, но `*val` не является экземпляром того же класса. В этом случае данная функция может использоваться для создания экземпляра класса. Если значения уже нормализованы, ничего не происходит. Отложенная нормализация реализована для повышения производительности.419420> **Примечание**421>422> Эта функция *не* неявно устанавливает атрибут [`__traceback__`](https://python-all.ru/3.12/library/exceptions.html#BaseException.__traceback__) у значения исключения. Если требуется правильно установить traceback, необходим следующий дополнительный фрагмент:423>424> ```c425> if (tb != NULL) {426>   PyException_SetTraceback(val, tb);427> }428> ```429430#### `PyObject *PyErr_GetHandledException(void)`431432*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.11.*433434Извлекает активный экземпляр исключения, как возвращаемый [`sys.exception()`](https://python-all.ru/3.12/library/sys.html#sys.exception). Это относится к исключению, которое *уже было перехвачено*, а не к только что возбужденному. Возвращает новую ссылку на исключение или `NULL`. Не изменяет состояние исключения интерпретатора.435436> **Примечание**437>438> Эта функция обычно не используется кодом, который хочет обрабатывать исключения. Скорее, она может использоваться, когда коду нужно временно сохранить и восстановить состояние исключения. Используйте [`PyErr_SetHandledException()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_SetHandledException), чтобы восстановить или очистить состояние исключения.439440Добавлено в версии 3.12.441442#### `void PyErr_SetHandledException(PyObject *exc)`443444*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.11.*445446Устанавливает активное исключение, как известно из `sys.exception()`. Это относится к исключению, которое *уже было перехвачено*, а не к только что возбужденному. Чтобы очистить состояние исключения, передайте `NULL`.447448> **Примечание**449>450> Эта функция обычно не используется кодом, который хочет обрабатывать исключения. Скорее, она может использоваться, когда коду нужно временно сохранить и восстановить состояние исключения. Используйте [`PyErr_GetHandledException()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_GetHandledException), чтобы получить состояние исключения.451452Добавлено в версии 3.12.453454#### `void PyErr_GetExcInfo(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)`455456*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.7.*457458Извлекает представление информации об исключении в старом стиле, как известно из [`sys.exc_info()`](https://python-all.ru/3.12/library/sys.html#sys.exc_info). Это относится к исключению, которое *уже было перехвачено*, а не к только что возбужденному. Возвращает новые ссылки на три объекта, каждый из которых может быть `NULL`. Не изменяет состояние информации об исключении. Эта функция сохраняется для обратной совместимости. Предпочтительнее использовать [`PyErr_GetHandledException()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_GetHandledException).459460> **Примечание**461>462> Эта функция обычно не используется кодом, который хочет обрабатывать исключения. Скорее, она может использоваться, когда коду нужно временно сохранить и восстановить состояние исключения. Используйте [`PyErr_SetExcInfo()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_SetExcInfo), чтобы восстановить или очистить состояние исключения.463464Добавлено в версии 3.3.465466#### `void PyErr_SetExcInfo(PyObject *type, PyObject *value, PyObject *traceback)`467468*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.7.*469470Устанавливает информацию об исключении, как известно из `sys.exc_info()`. Это относится к исключению, которое было *уже перехвачено*, а не к исключению, которое было только что возбуждено. Эта функция похищает ссылки на аргументы. Чтобы очистить состояние исключения, передайте `NULL` для всех трёх аргументов. Эта функция сохранена для обратной совместимости. Предпочтительнее использовать [`PyErr_SetHandledException()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_SetHandledException).471472> **Примечание**473>474> Эта функция обычно не используется кодом, который хочет обрабатывать исключения. Скорее, она может использоваться, когда коду нужно временно сохранить и восстановить состояние исключения. Используйте [`PyErr_GetExcInfo()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_GetExcInfo), чтобы прочитать состояние исключения.475476Добавлено в версии 3.3.477478Изменено в версии 3.11: Аргументы `type` и `traceback` больше не используются и могут быть NULL. Интерпретатор теперь извлекает их из экземпляра исключения (аргумент `value`). Функция по-прежнему похищает ссылки на все три аргумента.479480## Обработка сигналов481482#### `int PyErr_CheckSignals()`483484*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*485486Эта функция взаимодействует с обработкой сигналов Python.487488Если функция вызывается из главного потока и в главном интерпретаторе Python, она проверяет, был ли отправлен сигнал процессам, и если да, вызывает соответствующий обработчик сигнала. Если модуль [`signal`](https://python-all.ru/3.12/library/signal.html#module-signal) поддерживается, это может вызвать обработчик сигнала, написанный на Python.489490Функция пытается обработать все ожидающие сигналы, а затем возвращает `0`. Однако, если обработчик сигнала Python возбуждает исключение, устанавливается индикатор ошибки, и функция немедленно возвращает `-1` (таким образом, другие ожидающие сигналы могут быть еще не обработаны: они будут обработаны при следующем вызове [`PyErr_CheckSignals()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_CheckSignals)).491492Если функция вызывается из не-главного потока или в не-главном интерпретаторе Python, она ничего не делает и возвращает `0`.493494Эта функция может вызываться длительно работающим кодом на C, который должен быть прерываемым по запросу пользователя (например, по нажатию Ctrl-C).495496> **Примечание**497>498> Обработчик сигнала Python по умолчанию для `SIGINT` возбуждает исключение [`KeyboardInterrupt`](https://python-all.ru/3.12/library/exceptions.html#KeyboardInterrupt).499500#### `void PyErr_SetInterrupt()`501502*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*503504Имитирует эффект прибытия сигнала `SIGINT`. Это эквивалентно `PyErr_SetInterruptEx(SIGINT)`.505506> **Примечание**507>508> Эта функция безопасна для асинхронных сигналов. Её можно вызывать без [GIL](https://python-all.ru/3.12/glossary.html#term-GIL) и из обработчика сигналов C.509510#### `int PyErr_SetInterruptEx(int signum)`511512*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.10.*513514Имитирует эффект прибытия сигнала. При следующем вызове [`PyErr_CheckSignals()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_CheckSignals) будет вызван обработчик сигнала Python для заданного номера сигнала.515516Эта функция может вызываться кодом на C, который устанавливает собственную обработку сигналов и хочет, чтобы обработчики сигналов Python вызывались должным образом при запросе прерывания (например, когда пользователь нажимает Ctrl-C для прерывания операции).517518Если заданный сигнал не обрабатывается Python (он был установлен в [`signal.SIG_DFL`](https://python-all.ru/3.12/library/signal.html#signal.SIG_DFL) или [`signal.SIG_IGN`](https://python-all.ru/3.12/library/signal.html#signal.SIG_IGN)), он будет проигнорирован.519520Если *signum* выходит за допустимый диапазон номеров сигналов, возвращается `-1`. В противном случае возвращается `0`. Эта функция никогда не изменяет индикатор ошибки.521522> **Примечание**523>524> Эта функция безопасна для асинхронных сигналов. Её можно вызывать без [GIL](https://python-all.ru/3.12/glossary.html#term-GIL) и из обработчика сигналов C.525526Добавлено в версии 3.10.527528#### `int PySignal_SetWakeupFd(int fd)`529530Эта вспомогательная функция задаёт файловый дескриптор, в который при получении сигнала записывается номер сигнала в виде одного байта. *fd* должен быть неблокирующим. Функция возвращает предыдущий такой файловый дескриптор.531532Значение `-1` отключает эту возможность; это начальное состояние. Это эквивалентно [`signal.set_wakeup_fd()`](https://python-all.ru/3.12/library/signal.html#signal.set_wakeup_fd) в Python, но без проверки ошибок. *fd* должен быть корректным файловым дескриптором. Функцию следует вызывать только из главного потока.533534Изменено в версии 3.5: В Windows функция теперь также поддерживает дескрипторы сокетов.535536## Классы исключений537538#### `PyObject *PyErr_NewException(const char *name, PyObject *base, PyObject *dict)`539540*Возвращаемое значение: новая ссылка.*541542*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*543544Эта вспомогательная функция создаёт и возвращает новый класс исключения. Аргумент *name* должен быть именем нового исключения – строкой C вида `module.classname`. Аргументы *base* и *dict* обычно равны `NULL`. При этом создаётся класс, производный от [`Exception`](https://python-all.ru/3.12/library/exceptions.html#Exception) (доступен в C как `PyExc_Exception`).545546Атрибут [`__module__`](https://python-all.ru/3.12/reference/datamodel.html#type.__module__) нового класса устанавливается в первую часть (до последней точки) аргумента *name*, а имя класса – в последнюю часть (после последней точки). Аргумент *base* можно использовать для указания альтернативных базовых классов; это может быть как один класс, так и кортеж классов. Аргумент *dict* можно использовать для указания словаря переменных и методов класса.547548#### `PyObject *PyErr_NewExceptionWithDoc(const char *name, const char *doc, PyObject *base, PyObject *dict)`549550*Возвращаемое значение: новая ссылка.*551552*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*553554То же, что и [`PyErr_NewException()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_NewException), за исключением того, что новому классу исключения можно легко задать докстринг: если *doc* не `NULL`, он будет использоваться в качестве докстринга класса исключения.555556Добавлено в версии 3.2.557558## Объекты исключений559560#### `PyObject *PyException_GetTraceback(PyObject *ex)`561562*Возвращаемое значение: новая ссылка.*563564*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*565566Возвращает traceback, связанный с исключением, в виде новой ссылки, доступной из Python через атрибут [`__traceback__`](https://python-all.ru/3.12/library/exceptions.html#BaseException.__traceback__). Если traceback не связан, возвращает `NULL`.567568#### `int PyException_SetTraceback(PyObject *ex, PyObject *tb)`569570*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*571572Устанавливает traceback, связанный с исключением, в значение *tb*. Используйте `Py_None`, чтобы очистить его.573574#### `PyObject *PyException_GetContext(PyObject *ex)`575576*Возвращаемое значение: новая ссылка.*577578*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*579580Возвращает контекст (другой экземпляр исключения, при обработке которого было возбуждено *ex*), связанный с исключением, в виде новой ссылки, доступной из Python через атрибут [`__context__`](https://python-all.ru/3.12/library/exceptions.html#BaseException.__context__). Если контекст не связан, возвращает `NULL`.581582#### `void PyException_SetContext(PyObject *ex, PyObject *ctx)`583584*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*585586Устанавливает контекст, связанный с исключением, в *ctx*. Для очистки используйте `NULL`. Проверка типа, что *ctx* является экземпляром исключения, не выполняется. Эта функция перехватывает ссылку на *ctx*.587588#### `PyObject *PyException_GetCause(PyObject *ex)`589590*Возвращаемое значение: новая ссылка.*591592*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*593594Возвращает причину (экземпляр исключения или `None`, установленную с помощью `raise ... from ...`), связанную с исключением, в виде новой ссылки, доступной из Python через атрибут [`__cause__`](https://python-all.ru/3.12/library/exceptions.html#BaseException.__cause__).595596#### `void PyException_SetCause(PyObject *ex, PyObject *cause)`597598*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*599600Устанавливает причину, связанную с исключением, в *cause*. Для очистки используйте `NULL`. Проверка типа, что *cause* является экземпляром исключения или `None`, не выполняется. Эта функция перехватывает ссылку на *cause*.601602Атрибут [`__suppress_context__`](https://python-all.ru/3.12/library/exceptions.html#BaseException.__suppress_context__) неявно устанавливается в значение `True` этой функцией.603604#### `PyObject *PyException_GetArgs(PyObject *ex)`605606*Возвращаемое значение: новая ссылка.*607608*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) с версии 3.12.*609610Возвращает [`args`](https://python-all.ru/3.12/library/exceptions.html#BaseException.args) исключения *ex*.611612#### `void PyException_SetArgs(PyObject *ex, PyObject *args)`613614*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.12.*615616Устанавливает [`args`](https://python-all.ru/3.12/library/exceptions.html#BaseException.args) исключения *ex* в значение *args*.617618#### `PyObject *PyUnstable_Exc_PrepReraiseStar(PyObject *orig, PyObject *excs)`619620> *Это [нестабильное API](https://python-all.ru/3.12/c-api/stable.html#unstable-c-api). Оно может меняться без предупреждения в минорных версиях.*621622Реализует часть реализации интерпретатором конструкции `except*`. *orig* – это исходное исключение, которое было перехвачено, а *excs* – это список исключений, которые необходимо возбудить. Этот список содержит необработанную часть *orig* (если есть), а также исключения, возбуждённые из предложений `except*` (поэтому их traceback отличается от traceback *orig*), и те, которые были повторно возбуждены (и имеют тот же traceback, что и *orig*). Возвращает [`ExceptionGroup`](https://python-all.ru/3.12/library/exceptions.html#ExceptionGroup), который нужно повторно возбудить в конце, или `None`, если ничего повторно возбуждать не нужно.623624Добавлено в версии 3.12.625626## Объекты исключений Unicode627628Следующие функции используются для создания и изменения исключений Unicode из C.629630#### `PyObject *PyUnicodeDecodeError_Create(const char *encoding, const char *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)`631632*Возвращаемое значение: новая ссылка.*633634*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*635636Создаёт объект [`UnicodeDecodeError`](https://python-all.ru/3.12/library/exceptions.html#UnicodeDecodeError) с атрибутами *encoding*, *object*, *length*, *start*, *end* и *reason*. *encoding* и *reason* – это строки в кодировке UTF-8.637638#### `PyObject *PyUnicodeDecodeError_GetEncoding(PyObject *exc)`639640#### `PyObject *PyUnicodeEncodeError_GetEncoding(PyObject *exc)`641642*Возвращаемое значение: новая ссылка.*643644*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*645646Возвращает атрибут *encoding* указанного объекта исключения.647648#### `PyObject *PyUnicodeDecodeError_GetObject(PyObject *exc)`649650#### `PyObject *PyUnicodeEncodeError_GetObject(PyObject *exc)`651652#### `PyObject *PyUnicodeTranslateError_GetObject(PyObject *exc)`653654*Возвращаемое значение: новая ссылка.*655656*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*657658Возвращает атрибут *object* указанного объекта исключения.659660#### `int PyUnicodeDecodeError_GetStart(PyObject *exc, Py_ssize_t *start)`661662#### `int PyUnicodeEncodeError_GetStart(PyObject *exc, Py_ssize_t *start)`663664#### `int PyUnicodeTranslateError_GetStart(PyObject *exc, Py_ssize_t *start)`665666*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*667668Получает атрибут *start* указанного объекта исключения и помещает его в *\*start*. *start* не должен быть равен `NULL`. Возвращает `0` в случае успеха, `-1` при ошибке.669670#### `int PyUnicodeDecodeError_SetStart(PyObject *exc, Py_ssize_t start)`671672#### `int PyUnicodeEncodeError_SetStart(PyObject *exc, Py_ssize_t start)`673674#### `int PyUnicodeTranslateError_SetStart(PyObject *exc, Py_ssize_t start)`675676*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*677678Устанавливает атрибут *start* указанного объекта исключения в значение *start*. Возвращает `0` при успехе, `-1` при ошибке.679680#### `int PyUnicodeDecodeError_GetEnd(PyObject *exc, Py_ssize_t *end)`681682#### `int PyUnicodeEncodeError_GetEnd(PyObject *exc, Py_ssize_t *end)`683684#### `int PyUnicodeTranslateError_GetEnd(PyObject *exc, Py_ssize_t *end)`685686*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*687688Получает атрибут *end* указанного объекта исключения и помещает его в *\*end*. *end* не должен быть равен `NULL`. Возвращает `0` в случае успеха, `-1` при ошибке.689690#### `int PyUnicodeDecodeError_SetEnd(PyObject *exc, Py_ssize_t end)`691692#### `int PyUnicodeEncodeError_SetEnd(PyObject *exc, Py_ssize_t end)`693694#### `int PyUnicodeTranslateError_SetEnd(PyObject *exc, Py_ssize_t end)`695696*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*697698Устанавливает атрибут *end* указанного объекта исключения в *end*. Возвращает `0` в случае успеха, `-1` при ошибке.699700#### `PyObject *PyUnicodeDecodeError_GetReason(PyObject *exc)`701702#### `PyObject *PyUnicodeEncodeError_GetReason(PyObject *exc)`703704#### `PyObject *PyUnicodeTranslateError_GetReason(PyObject *exc)`705706*Возвращаемое значение: новая ссылка.*707708*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*709710Возвращает атрибут *reason* указанного объекта исключения.711712#### `int PyUnicodeDecodeError_SetReason(PyObject *exc, const char *reason)`713714#### `int PyUnicodeEncodeError_SetReason(PyObject *exc, const char *reason)`715716#### `int PyUnicodeTranslateError_SetReason(PyObject *exc, const char *reason)`717718*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*719720Устанавливает атрибут *reason* указанного объекта исключения в значение *reason*. Возвращает `0` в случае успеха, `-1` в случае ошибки.721722## Управление рекурсией723724Эти две функции предоставляют способ безопасно выполнять рекурсивные вызовы на уровне C как в ядре, так и в модулях расширения. Они необходимы, если рекурсивный код не обязательно вызывает код Python (который автоматически отслеживает свою глубину рекурсии). Они также не нужны для реализаций *tp\_call*, поскольку [протокол вызова](https://python-all.ru/3.12/c-api/call.html#call) берёт на себя обработку рекурсии.725726#### `int Py_EnterRecursiveCall(const char *where)`727728*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.9.*729730Отмечает точку, в которой будет выполнен рекурсивный вызов на уровне C.731732Если `USE_STACKCHECK` определён, эта функция проверяет, не произошло ли переполнения стека ОС с помощью [`PyOS_CheckStack()`](https://python-all.ru/3.12/c-api/sys.html#c.PyOS_CheckStack). Если это так, она устанавливает [`MemoryError`](https://python-all.ru/3.12/library/exceptions.html#MemoryError) и возвращает ненулевое значение.733734Затем функция проверяет, достигнут ли предел рекурсии. Если это так, устанавливается [`RecursionError`](https://python-all.ru/3.12/library/exceptions.html#RecursionError) и возвращается ненулевое значение. В противном случае возвращается ноль.735736*where* должна быть строкой в кодировке UTF-8, например `" in instance check"`, для добавления к сообщению [`RecursionError`](https://python-all.ru/3.12/library/exceptions.html#RecursionError), вызванному пределом глубины рекурсии.737738Изменено в версии 3.9: Эта функция теперь также доступна в [limited API](https://python-all.ru/3.12/c-api/stable.html#limited-c-api).739740#### `void Py_LeaveRecursiveCall(void)`741742*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.9.*743744Завершает [`Py_EnterRecursiveCall()`](https://python-all.ru/3.12/c-api/exceptions.html#c.Py_EnterRecursiveCall). Должна вызываться один раз для каждого *успешного* вызова [`Py_EnterRecursiveCall()`](https://python-all.ru/3.12/c-api/exceptions.html#c.Py_EnterRecursiveCall).745746Изменено в версии 3.9: Эта функция теперь также доступна в [limited API](https://python-all.ru/3.12/c-api/stable.html#limited-c-api).747748Для правильной реализации [`tp_repr`](https://python-all.ru/3.12/c-api/typeobj.html#c.PyTypeObject.tp_repr) для контейнерных типов требуется специальная обработка рекурсии. В дополнение к защите стека, [`tp_repr`](https://python-all.ru/3.12/c-api/typeobj.html#c.PyTypeObject.tp_repr) также необходимо отслеживать объекты для предотвращения циклов. Следующие две функции облегчают эту функциональность. По сути, это эквивалент [`reprlib.recursive_repr()`](https://python-all.ru/3.12/library/reprlib.html#reprlib.recursive_repr) на C.749750#### `int Py_ReprEnter(PyObject *object)`751752*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*753754Вызывается в начале реализации [`tp_repr`](https://python-all.ru/3.12/c-api/typeobj.html#c.PyTypeObject.tp_repr) для обнаружения циклов.755756Если объект уже был обработан, функция возвращает положительное целое число. В этом случае реализация [`tp_repr`](https://python-all.ru/3.12/c-api/typeobj.html#c.PyTypeObject.tp_repr) должна вернуть строковый объект, указывающий на цикл. Например, объекты [`dict`](https://python-all.ru/3.12/library/stdtypes.html#dict) возвращают `{...}`, а объекты [`list`](https://python-all.ru/3.12/library/stdtypes.html#list) возвращают `[...]`.757758Функция возвращает отрицательное целое число, если достигнут предел рекурсии. В этом случае реализация [`tp_repr`](https://python-all.ru/3.12/c-api/typeobj.html#c.PyTypeObject.tp_repr) обычно должна возвращать `NULL`.759760В противном случае функция возвращает ноль, и реализация [`tp_repr`](https://python-all.ru/3.12/c-api/typeobj.html#c.PyTypeObject.tp_repr) может продолжить работу в обычном режиме.761762#### `void Py_ReprLeave(PyObject *object)`763764*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*765766Завершает [`Py_ReprEnter()`](https://python-all.ru/3.12/c-api/exceptions.html#c.Py_ReprEnter). Должна вызываться один раз для каждого вызова [`Py_ReprEnter()`](https://python-all.ru/3.12/c-api/exceptions.html#c.Py_ReprEnter), которая возвращает ноль.767768## Стандартные исключения769770Все стандартные исключения Python доступны в виде глобальных переменных, имена которых образуются добавлением `PyExc_` перед именем исключения Python. Они имеют тип [PyObject](https://python-all.ru/3.12/c-api/structures.html#c.PyObject)\*; все они являются объектами классов. Для полноты, вот все переменные:771772| Имя в C | Имя в Python | Примечания |773| --- | --- | --- |774| `PyExc_BaseException` | [`BaseException`](https://python-all.ru/3.12/library/exceptions.html#BaseException) | [\[1\]](https://python-all.ru/3.12/c-api/exceptions.html#id7) |775| `PyExc_Exception` | [`Exception`](https://python-all.ru/3.12/library/exceptions.html#Exception) | [\[1\]](https://python-all.ru/3.12/c-api/exceptions.html#id7) |776| `PyExc_ArithmeticError` | [`ArithmeticError`](https://python-all.ru/3.12/library/exceptions.html#ArithmeticError) | [\[1\]](https://python-all.ru/3.12/c-api/exceptions.html#id7) |777| `PyExc_AssertionError` | [`AssertionError`](https://python-all.ru/3.12/library/exceptions.html#AssertionError) |  |778| `PyExc_AttributeError` | [`AttributeError`](https://python-all.ru/3.12/library/exceptions.html#AttributeError) |  |779| `PyExc_BlockingIOError` | [`BlockingIOError`](https://python-all.ru/3.12/library/exceptions.html#BlockingIOError) |  |780| `PyExc_BrokenPipeError` | [`BrokenPipeError`](https://python-all.ru/3.12/library/exceptions.html#BrokenPipeError) |  |781| `PyExc_BufferError` | [`BufferError`](https://python-all.ru/3.12/library/exceptions.html#BufferError) |  |782| `PyExc_ChildProcessError` | [`ChildProcessError`](https://python-all.ru/3.12/library/exceptions.html#ChildProcessError) |  |783| `PyExc_ConnectionAbortedError` | [`ConnectionAbortedError`](https://python-all.ru/3.12/library/exceptions.html#ConnectionAbortedError) |  |784| `PyExc_ConnectionError` | [`ConnectionError`](https://python-all.ru/3.12/library/exceptions.html#ConnectionError) |  |785| `PyExc_ConnectionRefusedError` | [`ConnectionRefusedError`](https://python-all.ru/3.12/library/exceptions.html#ConnectionRefusedError) |  |786| `PyExc_ConnectionResetError` | [`ConnectionResetError`](https://python-all.ru/3.12/library/exceptions.html#ConnectionResetError) |  |787| `PyExc_EOFError` | [`EOFError`](https://python-all.ru/3.12/library/exceptions.html#EOFError) |  |788| `PyExc_FileExistsError` | [`FileExistsError`](https://python-all.ru/3.12/library/exceptions.html#FileExistsError) |  |789| `PyExc_FileNotFoundError` | [`FileNotFoundError`](https://python-all.ru/3.12/library/exceptions.html#FileNotFoundError) |  |790| `PyExc_FloatingPointError` | [`FloatingPointError`](https://python-all.ru/3.12/library/exceptions.html#FloatingPointError) |  |791| `PyExc_GeneratorExit` | [`GeneratorExit`](https://python-all.ru/3.12/library/exceptions.html#GeneratorExit) |  |792| `PyExc_ImportError` | [`ImportError`](https://python-all.ru/3.12/library/exceptions.html#ImportError) |  |793| `PyExc_IndentationError` | [`IndentationError`](https://python-all.ru/3.12/library/exceptions.html#IndentationError) |  |794| `PyExc_IndexError` | [`IndexError`](https://python-all.ru/3.12/library/exceptions.html#IndexError) |  |795| `PyExc_InterruptedError` | [`InterruptedError`](https://python-all.ru/3.12/library/exceptions.html#InterruptedError) |  |796| `PyExc_IsADirectoryError` | [`IsADirectoryError`](https://python-all.ru/3.12/library/exceptions.html#IsADirectoryError) |  |797| `PyExc_KeyError` | [`KeyError`](https://python-all.ru/3.12/library/exceptions.html#KeyError) |  |798| `PyExc_KeyboardInterrupt` | [`KeyboardInterrupt`](https://python-all.ru/3.12/library/exceptions.html#KeyboardInterrupt) |  |799| `PyExc_LookupError` | [`LookupError`](https://python-all.ru/3.12/library/exceptions.html#LookupError) | [\[1\]](https://python-all.ru/3.12/c-api/exceptions.html#id7) |800| `PyExc_MemoryError` | [`MemoryError`](https://python-all.ru/3.12/library/exceptions.html#MemoryError) |  |801| `PyExc_ModuleNotFoundError` | [`ModuleNotFoundError`](https://python-all.ru/3.12/library/exceptions.html#ModuleNotFoundError) |  |802| `PyExc_NameError` | [`NameError`](https://python-all.ru/3.12/library/exceptions.html#NameError) |  |803| `PyExc_NotADirectoryError` | [`NotADirectoryError`](https://python-all.ru/3.12/library/exceptions.html#NotADirectoryError) |  |804| `PyExc_NotImplementedError` | [`NotImplementedError`](https://python-all.ru/3.12/library/exceptions.html#NotImplementedError) |  |805| `PyExc_OSError` | [`OSError`](https://python-all.ru/3.12/library/exceptions.html#OSError) | [\[1\]](https://python-all.ru/3.12/c-api/exceptions.html#id7) |806| `PyExc_OverflowError` | [`OverflowError`](https://python-all.ru/3.12/library/exceptions.html#OverflowError) |  |807| `PyExc_PermissionError` | [`PermissionError`](https://python-all.ru/3.12/library/exceptions.html#PermissionError) |  |808| `PyExc_ProcessLookupError` | [`ProcessLookupError`](https://python-all.ru/3.12/library/exceptions.html#ProcessLookupError) |  |809| `PyExc_RecursionError` | [`RecursionError`](https://python-all.ru/3.12/library/exceptions.html#RecursionError) |  |810| `PyExc_ReferenceError` | [`ReferenceError`](https://python-all.ru/3.12/library/exceptions.html#ReferenceError) |  |811| `PyExc_RuntimeError` | [`RuntimeError`](https://python-all.ru/3.12/library/exceptions.html#RuntimeError) |  |812| `PyExc_StopAsyncIteration` | [`StopAsyncIteration`](https://python-all.ru/3.12/library/exceptions.html#StopAsyncIteration) |  |813| `PyExc_StopIteration` | [`StopIteration`](https://python-all.ru/3.12/library/exceptions.html#StopIteration) |  |814| `PyExc_SyntaxError` | [`SyntaxError`](https://python-all.ru/3.12/library/exceptions.html#SyntaxError) |  |815| `PyExc_SystemError` | [`SystemError`](https://python-all.ru/3.12/library/exceptions.html#SystemError) |  |816| `PyExc_SystemExit` | [`SystemExit`](https://python-all.ru/3.12/library/exceptions.html#SystemExit) |  |817| `PyExc_TabError` | [`TabError`](https://python-all.ru/3.12/library/exceptions.html#TabError) |  |818| `PyExc_TimeoutError` | [`TimeoutError`](https://python-all.ru/3.12/library/exceptions.html#TimeoutError) |  |819| `PyExc_TypeError` | [`TypeError`](https://python-all.ru/3.12/library/exceptions.html#TypeError) |  |820| `PyExc_UnboundLocalError` | [`UnboundLocalError`](https://python-all.ru/3.12/library/exceptions.html#UnboundLocalError) |  |821| `PyExc_UnicodeDecodeError` | [`UnicodeDecodeError`](https://python-all.ru/3.12/library/exceptions.html#UnicodeDecodeError) |  |822| `PyExc_UnicodeEncodeError` | [`UnicodeEncodeError`](https://python-all.ru/3.12/library/exceptions.html#UnicodeEncodeError) |  |823| `PyExc_UnicodeError` | [`UnicodeError`](https://python-all.ru/3.12/library/exceptions.html#UnicodeError) |  |824| `PyExc_UnicodeTranslateError` | [`UnicodeTranslateError`](https://python-all.ru/3.12/library/exceptions.html#UnicodeTranslateError) |  |825| `PyExc_ValueError` | [`ValueError`](https://python-all.ru/3.12/library/exceptions.html#ValueError) |  |826| `PyExc_ZeroDivisionError` | [`ZeroDivisionError`](https://python-all.ru/3.12/library/exceptions.html#ZeroDivisionError) |  |827828Добавлено в версии 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` и `PyExc_TimeoutError` были введены в соответствии с [**PEP 3151**](https://python-all.ru/3.12/c-api/exceptions.html).829830Добавлено в версии 3.5: `PyExc_StopAsyncIteration` и `PyExc_RecursionError`.831832Добавлено в версии 3.6: `PyExc_ModuleNotFoundError`.833834Это псевдонимы для совместимости с `PyExc_OSError`:835836| Имя в C | Примечания |837| --- | --- |838| `PyExc_EnvironmentError` |  |839| `PyExc_IOError` |  |840| `PyExc_WindowsError` | [\[2\]](https://python-all.ru/3.12/c-api/exceptions.html#id8) |841842Изменено в версии 3.3: Раньше эти псевдонимы были отдельными типами исключений.843844Примечания:845846\[1\]847848([1](https://python-all.ru/3.12/c-api/exceptions.html#id1),[2](https://python-all.ru/3.12/c-api/exceptions.html#id2),[3](https://python-all.ru/3.12/c-api/exceptions.html#id3),[4](https://python-all.ru/3.12/c-api/exceptions.html#id4),[5](https://python-all.ru/3.12/c-api/exceptions.html#id5))849850Это базовый класс для других стандартных исключений.851852\[[2](https://python-all.ru/3.12/c-api/exceptions.html#id6)\]853854Определено только в Windows; защитите код, использующий это, проверкой, что определён макрос препроцессора `MS_WINDOWS`.855856## Стандартные категории предупреждений857858Все стандартные категории предупреждений Python доступны как глобальные переменные, имена которых образуются добавлением `PyExc_` перед именем исключения Python. Они имеют тип [PyObject](https://python-all.ru/3.12/c-api/structures.html#c.PyObject)\*; все они являются объектами классов. Для полноты, вот все переменные:859860| Имя в C | Имя в Python | Примечания |861| --- | --- | --- |862| `PyExc_Warning` | [`Warning`](https://python-all.ru/3.12/library/exceptions.html#Warning) | [\[3\]](https://python-all.ru/3.12/c-api/exceptions.html#id10) |863| `PyExc_BytesWarning` | [`BytesWarning`](https://python-all.ru/3.12/library/exceptions.html#BytesWarning) |  |864| `PyExc_DeprecationWarning` | [`DeprecationWarning`](https://python-all.ru/3.12/library/exceptions.html#DeprecationWarning) |  |865| `PyExc_FutureWarning` | [`FutureWarning`](https://python-all.ru/3.12/library/exceptions.html#FutureWarning) |  |866| `PyExc_ImportWarning` | [`ImportWarning`](https://python-all.ru/3.12/library/exceptions.html#ImportWarning) |  |867| `PyExc_PendingDeprecationWarning` | [`PendingDeprecationWarning`](https://python-all.ru/3.12/library/exceptions.html#PendingDeprecationWarning) |  |868| `PyExc_ResourceWarning` | [`ResourceWarning`](https://python-all.ru/3.12/library/exceptions.html#ResourceWarning) |  |869| `PyExc_RuntimeWarning` | [`RuntimeWarning`](https://python-all.ru/3.12/library/exceptions.html#RuntimeWarning) |  |870| `PyExc_SyntaxWarning` | [`SyntaxWarning`](https://python-all.ru/3.12/library/exceptions.html#SyntaxWarning) |  |871| `PyExc_UnicodeWarning` | [`UnicodeWarning`](https://python-all.ru/3.12/library/exceptions.html#UnicodeWarning) |  |872| `PyExc_UserWarning` | [`UserWarning`](https://python-all.ru/3.12/library/exceptions.html#UserWarning) |  |873874Добавлено в версии 3.2: `PyExc_ResourceWarning`.875876Примечания:877878\[[3](https://python-all.ru/3.12/c-api/exceptions.html#id9)\]879880Это базовый класс для других стандартных категорий предупреждений.881