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

Печать и очистка¶Printing and clearing

void PyErr_Clear()¶

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

void PyErr_PrintEx(int set_sys_last_vars)¶

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

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

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

void PyErr_Print()¶

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

void PyErr_WriteUnraisable(PyObject *obj)¶

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

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

Возбуждение исключений¶Raising exceptions

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

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

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

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

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

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

Возвращаемое значение: всегда NULL.

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

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

Возвращаемое значение: всегда NULL.

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

Новое в версии 3.5.

void PyErr_SetNone(PyObject *type)¶

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

int PyErr_BadArgument()¶

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

PyObject* PyErr_NoMemory()¶

Возвращаемое значение: всегда NULL.

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

PyObject* PyErr_SetFromErrno(PyObject *type)¶

Возвращаемое значение: всегда NULL.

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

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

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

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

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

Новое в версии 3.4.

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

Возвращаемое значение: всегда NULL.

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

PyObject* PyErr_SetFromWindowsErr(int ierr)¶

Возвращаемое значение: всегда NULL.

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

PyObject* PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)¶

Возвращаемое значение: всегда NULL.

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

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

Возвращаемое значение: всегда NULL.

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

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

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

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

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

Новое в версии 3.4.

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

Возвращаемое значение: всегда NULL.

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

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

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

Новое в версии 3.3.

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

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

Новое в версии 3.4.

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

Как и PyErr_SyntaxLocationObject(), но filename – это байтовая строка, декодированная из файловой системной кодировки (os.fsdecode()).

Новое в версии 3.2.

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

Как PyErr_SyntaxLocationEx(), но параметр col_offset опущен.

void PyErr_BadInternalCall()¶

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

Выдача предупреждений¶Issuing warnings

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

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

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

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

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

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

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

Новое в версии 3.6.

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

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

Новое в версии 3.4.

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

Похоже на PyErr_WarnExplicitObject(), за исключением того, что message и module – это строки в кодировке UTF-8, а filename декодируется из файловой системной кодировки (os.fsdecode()).

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

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

Новое в версии 3.2.

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

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

Новое в версии 3.6.

Опрос индикатора ошибки¶Querying the error indicator

PyObject* PyErr_Occurred()¶

Возвращаемое значение: заимствованная ссылка.

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

Примечание

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

int PyErr_ExceptionMatches(PyObject *exc)¶

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

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

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

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

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

Примечание

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

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

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

   PyErr_Restore(type, value, traceback);
}

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

Set the error indicator from the three objects. If the error indicator is already set, it is cleared first. If the objects are NULL, the error indicator is cleared. Do not pass a NULL type and non-NULL value or traceback. The exception type should be a class. Do not pass an invalid exception type or value. (Violating these rules will cause subtle problems later.) This call takes away a reference to each object: you must own a reference to each object before the call and after the call you no longer own these references. (If you don’t understand this, don’t use this function. I warned you.)

Примечание

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

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

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

Примечание

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

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

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

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

Примечание

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

Новое в версии 3.3.

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

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

Примечание

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

Новое в версии 3.3.

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

int PyErr_CheckSignals()¶

Эта функция взаимодействует с обработкой сигналов Python. Она проверяет, был ли отправлен сигнал процессам, и если да, вызывает соответствующий обработчик сигнала. Если модуль signal поддерживается, может быть вызван обработчик сигнала, написанный на Python. Во всех случаях эффект по умолчанию для SIGINT – возбуждение исключения KeyboardInterrupt. Если исключение возбуждено, устанавливается индикатор ошибки, и функция возвращает -1; в противном случае функция возвращает 0. Индикатор ошибки может быть сброшен или не сброшен, если он был установлен ранее.

void PyErr_SetInterrupt()¶

Эта функция имитирует действие сигнала SIGINT – при следующем вызове PyErr_CheckSignals() будет возбуждено KeyboardInterrupt. Её можно вызывать, не удерживая блокировку интерпретатора.

int PySignal_SetWakeupFd(int fd)¶

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

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

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

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

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

Возвращаемое значение: новая ссылка.

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

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

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

Возвращаемое значение: новая ссылка.

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

Новое в версии 3.2.

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

PyObject* PyException_GetTraceback(PyObject *ex)¶

Возвращаемое значение: новая ссылка.

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

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

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

PyObject* PyException_GetContext(PyObject *ex)¶

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

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

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

PyObject* PyException_GetCause(PyObject *ex)¶

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

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

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

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

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

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

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

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

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

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

PyObject* PyUnicodeDecodeError_GetEncoding(PyObject *exc)¶

PyObject* PyUnicodeEncodeError_GetEncoding(PyObject *exc)¶

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

PyObject* PyUnicodeDecodeError_GetObject(PyObject *exc)¶

PyObject* PyUnicodeEncodeError_GetObject(PyObject *exc)¶

PyObject* PyUnicodeTranslateError_GetObject(PyObject *exc)¶

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

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

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

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

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

int PyUnicodeDecodeError_SetStart(PyObject *exc, Py_ssize_t start)¶

int PyUnicodeEncodeError_SetStart(PyObject *exc, Py_ssize_t start)¶

int PyUnicodeTranslateError_SetStart(PyObject *exc, Py_ssize_t start)¶

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

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

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

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

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

int PyUnicodeDecodeError_SetEnd(PyObject *exc, Py_ssize_t end)¶

int PyUnicodeEncodeError_SetEnd(PyObject *exc, Py_ssize_t end)¶

int PyUnicodeTranslateError_SetEnd(PyObject *exc, Py_ssize_t end)¶

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

PyObject* PyUnicodeDecodeError_GetReason(PyObject *exc)¶

PyObject* PyUnicodeEncodeError_GetReason(PyObject *exc)¶

PyObject* PyUnicodeTranslateError_GetReason(PyObject *exc)¶

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

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

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

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

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

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

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

int Py_EnterRecursiveCall(const char *where)¶

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

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

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

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

void Py_LeaveRecursiveCall()¶

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

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

int Py_ReprEnter(PyObject *object)¶

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

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

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

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

void Py_ReprLeave(PyObject *object)¶

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

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

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

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

Примечания:

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

2. То же самое, что и weakref.ReferenceError.

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

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

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

Примечания:

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