Встроенные исключения

В Python все исключения должны быть экземплярами класса, производного от BaseException. В операторе try с предложением Exception, в котором упоминается конкретный класс, это предложение также обрабатывает любые классы исключений, производные от этого класса (но не классы исключений, из которых он является производным). Два класса исключений, не связанные созданием подклассов, никогда не являются эквивалентными, даже если они имеют одно и то же имя.

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

Пользовательский код может вызывать встроенные исключения. Это можно использовать для проверки обработчика исключений или для сообщения об ошибке, «точно так же, как» ситуация, в которой интерпретатор вызывает то же исключение; но помните, что нет ничего, что могло бы помешать пользовательскому коду вызвать недопустимую ошибку.

Встроенные классы исключений могут быть разделены на подклассы для определения новых исключений; программистам рекомендуется создавать новые исключения из класса Exception или одного из его подклассов, а не из BaseException. Дополнительную информацию об определении исключений можно найти в руководстве по Python в разделе Пользовательские исключения.

Контекст исключения

Три атрибута объектов исключений предоставляют информацию о контексте, в котором возникло исключение:

BaseException.__context__

BaseException.__cause__

BaseException.__suppress_context__

При возникновении нового исключения, когда другое исключение уже обрабатывается, атрибуту __context__ нового исключения автоматически присваивается значение обработанного исключения. Исключение может быть обработано при использовании предложения Exception или finally, или оператора with.

Этот контекст неявного исключения можно дополнить явной причиной, используя from с raise:

поднять new_exc из original_exc

Выражение, следующее за from, должно быть исключением или Нет. В возникшем исключении он будет установлен как __cause__. Установка __cause__ также неявно устанавливает для атрибута __suppress_context__ значение True, так что использование raise new_exc from None эффективно заменяет старое исключение новым для целей отображения. (например, преобразование KeyError в AttributeError), оставляя старое исключение доступным в __context__ для самоанализа при отладке.

Код отображения обратной трассировки по умолчанию отображает эти цепочки исключений в дополнение к обратной трассировке самого исключения. Явно связанное исключение в __cause__ всегда отображается, если оно присутствует. Неявно связанное исключение в __context__ отображается только в том случае, если __cause__ имеет значение None и __suppress_context__ имеет значение false.

В любом случае само исключение всегда отображается после любых связанных исключений, поэтому последняя строка обратной трассировки всегда показывает последнее возникшее исключение.

Наследование от встроенных исключений

Пользовательский код может создавать подклассы, наследуемые от типа исключения. Рекомендуется одновременно создавать подкласс только одного типа исключения, чтобы избежать любых возможных конфликтов между тем, как базы обрабатывают атрибут args, а также из-за возможной несовместимости структуры памяти.

Большинство встроенных исключений для повышения эффективности реализованы на языке C, см.: Objects/Exceptions.c. Некоторые из них имеют собственную структуру памяти, что делает невозможным создание подкласса, наследуемого от нескольких типов исключений. Расположение памяти типа является деталью реализации и может меняться в разных версиях Python, что приведет к новым конфликтам в будущем. Поэтому рекомендуется вообще избегать создания подклассов нескольких типов исключений.

Базовые классы

Следующие исключения используются в основном как базовые классы для других исключений.

exception BaseException

Базовый класс для всех встроенных исключений. Он не предназначен для прямого наследования определяемыми пользователем классами (для этого используйте Exception). Если str() вызывается для экземпляра этого класса, возвращается представление аргумента(ов) экземпляра или пустая строка, если аргументов нет.

args

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

with_traceback(tb)

Этот метод устанавливает tb в качестве новой трассировки исключения и возвращает объект исключения. Он чаще использовался до того, как стали доступны функции цепочки исключений PEP 3134. В следующем примере показано, как мы можем преобразовать экземпляр SomeException в экземпляр OtherException, сохраняя при этом обратную трассировку. После возникновения текущий кадр помещается в обратную трассировку OtherException, как это произошло бы с обратной трассировкой исходного SomeException, если бы мы позволили ему распространиться на вызывающую сторону.

try:
    ...
except SomeException:
    tb = sys.exception().__traceback__
    raise OtherException(...).with_traceback(tb)

__traceback__

Доступное для записи поле, содержащее объект трассировки, связанный с этим исключением. См. также: Инструкция raise.

add_note(note)

Добавьте строку note к примечаниям об исключении, которые появляются в стандартной обратной трассировке после строки исключения. Ошибка TypeError возникает, если note не является строкой.

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

__notes__

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

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

exception Exception

Все встроенные исключения, не выходящие из системы, являются производными от этого класса. Все определяемые пользователем исключения также должны быть производными от этого класса.

exception ArithmeticError

Базовый класс для встроенных исключений, возникающих при различных арифметических ошибках: OverflowError, ZeroDivisionError, FloatingPointError.

exception BufferError

Возникает, когда операция, связанная с buffer, не может быть выполнена.

exception LookupError

Базовый класс для исключений, которые возникают, когда ключ или индекс, используемые в сопоставлении или последовательности, недействительны: IndexError, KeyError. Его можно вызвать непосредственно с помощью codecs.lookup().

Конкретные исключения

Следующие исключения представляют собой исключения, которые обычно возникают.

exception AssertionError

Возникает, когда оператор assert не работает.

exception AttributeError

Возникает, когда ссылка на атрибут (см. Attribute references) или присвоение завершаются неудачно. (Когда объект вообще не поддерживает ссылки на атрибуты или назначения атрибутов, возникает TypeError.)

The name and obj attributes can be set using keyword-only arguments to the constructor. When set they represent the name of the attribute that was attempted to be accessed and the object that was accessed for said attribute, respectively.

Изменено в версии 3.10: Добавлены атрибуты name и obj.

exception EOFError

Raised when the input() function hits an end-of-file condition (EOF) without reading any data. (N.B.: the io.IOBase.read() and io.IOBase.readline() methods return an empty string when they hit EOF.)

exception FloatingPointError

В настоящее время не используется.

exception GeneratorExit

Возникает, когда закрывается generator или coroutine; см. generator.close() и coroutine.close(). Он напрямую наследуется от BaseException вместо Exception, поскольку технически это не ошибка.

exception ImportError

Возникает, когда у оператора import возникают проблемы при загрузке модуля. Также возникает, когда имя «from list» в from ... import не может быть найдено.

Необязательные аргументы name и path, содержащие только ключевые слова, устанавливают соответствующие атрибуты:

name

Имя модуля, который была предпринята попытка импортировать.

path

Путь к любому файлу, вызвавшему исключение.

Изменено в версии 3.3: Добавлены атрибуты name и path.

exception ModuleNotFoundError

Подкласс ImportError, который вызывается import, когда модуль не может быть найден. Он также возникает, когда в sys.modules обнаружено None.

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

exception IndexError

Возникает, когда индекс последовательности выходит за пределы допустимого диапазона. (Индексы срезов автоматически усекаются, чтобы попасть в разрешенный диапазон; если индекс не является целым числом, возникает TypeError.)

exception KeyError

Возникает, когда ключ сопоставления (словаря) не найден в наборе существующих ключей.

exception KeyboardInterrupt

Вызывается, когда пользователь нажимает клавишу прерывания (обычно Control-C или Delete). Во время выполнения регулярно производится проверка на прерывания. Исключение наследуется от BaseException, чтобы случайно не быть перехваченным кодом, который перехватывает Exception и тем самым предотвратить выход интерпретатора.

Примечание

Перехват KeyboardInterrupt требует особого внимания. Поскольку его можно вызвать в непредсказуемые моменты, в некоторых случаях он может привести работающую программу в несогласованное состояние. Обычно лучше разрешить KeyboardInterrupt завершать программу как можно быстрее или вообще избегать ее запуска. (См. обработчики-и-исключения.)

exception MemoryError

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

exception NameError

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

The name attribute can be set using a keyword-only argument to the constructor. When set it represent the name of the variable that was attempted to be accessed.

Изменено в версии 3.10: Добавлен атрибут name.

exception NotImplementedError

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

Примечание

Его не следует использовать для указания того, что оператор или метод вообще не должен поддерживаться — в этом случае либо оставьте оператор/метод неопределенным, либо, если это подкласс, установите для него значение None.

Осторожно

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

exception OSError([arg])

exception OSError(errno, strerror[, filename[, winerror[, filename2]]])

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

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

Конструктор часто фактически возвращает подкласс OSError, как описано ниже в разделе Исключения ОС. Конкретный подкласс зависит от конечного значения errno. Такое поведение возникает только при создании OSError напрямую или через псевдоним и не наследуется при создании подклассов.

errno

Числовой код ошибки из переменной C errno.

winerror

В Windows это дает вам собственный код ошибки Windows. Атрибут errno представляет собой приблизительный перевод в терминах POSIX этого собственного кода ошибки.

В Windows, если аргумент конструктора winerror является целым числом, атрибут errno определяется по коду ошибки Windows, а аргумент errno игнорируется. На других платформах аргумент winerror игнорируется, а атрибут winerror не существует.

strerror

The corresponding error message, as provided by the operating system. It is formatted by the C functions perror() under POSIX, and FormatMessage() under Windows.

filename

filename2

Для исключений, связанных с путем к файловой системе (например, open() или os.unlink()), filename — это имя файла, передаваемое функции. Для функций, которые используют два пути файловой системы (например, os.rename()), filename2 соответствует второму имени файла, переданному функции.

Изменено в версии 3.3: EnvironmentError, IOError, WindowsError, socket.error, select.error and mmap.error have been merged into OSError, and the constructor may return a subclass.

Изменено в версии 3.4: Атрибут filename теперь является исходным именем файла, передаваемым в функцию, а не именем, закодированным или декодированным из кодирования файловой системы и обработчика ошибок. Кроме того, были добавлены аргумент и атрибут конструктора filename2.

exception OverflowError

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

exception RecursionError

Это исключение является производным от RuntimeError. Он возникает, когда интерпретатор обнаруживает, что максимальная глубина рекурсии (см. sys.getrecursionlimit()) превышена.

Добавлено в версии 3.5: Ранее возникало простое сообщение RuntimeError.

exception ReferenceError

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

exception RuntimeError

Возникает при обнаружении ошибки, не подпадающей ни под одну из других категорий. Соответствующее значение представляет собой строку, указывающую, что именно пошло не так.

exception StopIteration

Вызывается встроенной функцией next() и методом iterator__next__(), чтобы сигнализировать о том, что итератор больше не создает элементов.

value

Объект исключения имеет единственный атрибут value, который передается в качестве аргумента при создании исключения и по умолчанию имеет значение None.

Когда функция generator или coroutine возвращает значение, создается новый экземпляр StopIteration, и значение, возвращаемое функцией, используется в качестве параметра value для конструктор исключения.

Если код генератора прямо или косвенно вызывает StopIteration, он преобразуется в RuntimeError (сохраняя StopIteration как причину нового исключения).

Изменено в версии 3.3: Добавлен атрибут value и возможность функций-генераторов использовать его для возврата значения.

Изменено в версии 3.5: Введено преобразование RuntimeError через from __future__ importgenerator_stop, см. PEP 479.

Изменено в версии 3.7: Включите PEP 479 для всего кода по умолчанию: ошибка StopIteration, возникающая в генераторе, преобразуется в RuntimeError.

exception StopAsyncIteration

Должен быть вызван методом __anext__() объекта асинхронного итератора, чтобы остановить итерацию.

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

exception SyntaxError(message, details)

Возникает, когда синтаксический анализатор обнаруживает синтаксическую ошибку. Это может произойти в операторе import, при вызове встроенных функций compile(), exec() или eval() или при чтении исходного скрипта. или стандартный ввод (также в интерактивном режиме).

str() экземпляра исключения возвращает только сообщение об ошибке. Details — это кортеж, члены которого также доступны как отдельные атрибуты.

filename

Имя файла, в котором произошла синтаксическая ошибка.

lineno

В каком номере строки в файле произошла ошибка. Индексируется 1: первая строка в файле имеет lineno, равный 1.

offset

Столбец в строке, в которой произошла ошибка. Это индекс 1: первый символ в строке имеет смещение, равное 1.

text

Текст исходного кода, связанный с ошибкой.

end_lineno

На каком номере строки в файле заканчивается ошибка. Это индекс 1: первая строка в файле имеет lineno, равный 1.

end_offset

Столбец в конечной строке, в котором произошла ошибка, заканчивается. Это индекс 1: первый символ в строке имеет смещение, равное 1.

В случае ошибок в полях f-строки сообщение начинается с префикса «f-строка:», а смещения представляют собой смещения в тексте, созданном на основе выражения замены. Например, компиляция поля f’Bad {ab}“ приводит к следующему атрибуту args: („f-string: …“, („“, 1, 2, „(ab)n“, 1, 5)) .

Изменено в версии 3.10: Добавлены атрибуты end_lineno и end_offset.

exception IndentationError

Базовый класс для синтаксических ошибок, связанных с неправильным отступом. Это подкласс SyntaxError.

exception TabError

Возникает, когда отступ содержит непоследовательное использование табуляции и пробелов. Это подкласс IndentationError.

exception SystemError

Поднимается, когда интерпретатор находит внутреннюю ошибку, но ситуация не выглядит настолько серьезно, чтобы заставить ее отказаться от всей надежды. Связанное значение-это строка, указывающая, что пошло не так (в условиях низкого уровня). В: Термин: cpython, это может быть поднято неправильно, используя API Python C, такой как возврат значения` null` без набора исключений.

Если вы уверены, что это исключение не ваша вина или вина в пакете, которую вы используете, вы должны сообщить об этом автору или сопровождающему вашего интерпретатора Python. Обязательно сообщите о версии интерпретатора Python (`` sys.version``; она также напечатана в начале интерактивного сеанса Python), точное сообщение об ошибке (связанное значение исключения) и, если возможно, источник Программа, которая вызвала ошибку.

exception SystemExit

This exception is raised by the sys.exit() function. It inherits from BaseException instead of Exception so that it is not accidentally caught by code that catches Exception. This allows the exception to properly propagate up and cause the interpreter to exit. When it is not handled, the Python interpreter exits; no stack traceback is printed. The constructor accepts the same optional argument passed to sys.exit(). If the value is an integer, it specifies the system exit status (passed to C’s exit() function); if it is None, the exit status is zero; if it has another type (such as a string), the object’s value is printed and the exit status is one.

Вызов sys.exit() преобразуется в исключение, чтобы можно было выполнить обработчики очистки (предложения finally операторов try) и чтобы отладчик мог выполнить сценарий без риска потери контроля. Функцию os._exit() можно использовать, если абсолютно необходимо немедленно завершить работу (например, в дочернем процессе после вызова os.fork()).

code

Статус завершения или сообщение об ошибке, передаваемое конструктору. (По умолчанию «Нет».)

exception TypeError

Возникает, когда операция или функция применяется к объекту неподходящего типа. Связанное значение представляет собой строку, предоставляющую подробную информацию о несоответствии типов.

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

Передача аргументов неправильного типа (например, передача list, когда ожидается int) должна привести к TypeError, но передача аргументов с неправильным значением (например, числом вне ожидаемые границы) должно привести к ошибке ValueError.

exception UnboundLocalError

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

exception UnicodeError

Возникает при возникновении ошибки кодирования или декодирования, связанной с Unicode. Это подкласс ValueError.

UnicodeError имеет атрибуты, описывающие ошибку кодирования или декодирования. Например, err.object[err.start:err.end] дает конкретный недопустимый входной сигнал, с которым произошел сбой кодека.

encoding

Название кодировки, из-за которой возникла ошибка.

reason

Строка, описывающая конкретную ошибку кодека.

object

Объект, который кодек пытался закодировать или декодировать.

start

Первый индекс недопустимых данных в object.

end

Индекс после последних недопустимых данных в object.

exception UnicodeEncodeError

Возникает, когда во время кодирования возникает ошибка, связанная с Unicode. Это подкласс UnicodeError.

exception UnicodeDecodeError

Возникает, когда во время декодирования возникает ошибка, связанная с Unicode. Это подкласс UnicodeError.

exception UnicodeTranslateError

Возникает, когда во время перевода возникает ошибка, связанная с Unicode. Это подкласс UnicodeError.

exception ValueError

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

exception ZeroDivisionError

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

Следующие исключения сохранены для совместимости с предыдущими версиями; начиная с Python 3.3, они являются псевдонимами OSError.

exception EnvironmentError

exception IOError

exception WindowsError

Доступно только в Windows.

Исключения операционной системы

Следующие исключения являются подклассами OSError, они возникают в зависимости от кода системной ошибки.

exception BlockingIOError

Возникает, когда операция блокируется на объекте (например, сокете), установленном для неблокирующей операции. Соответствует errno EAGAIN, EALREADY, EWOULDBLOCK и :py:const :~errno.EINPROGRESS.

В дополнение к атрибутам OSError, BlockingIOError может иметь еще один атрибут:

characters_written

An integer containing the number of characters written to the stream before it blocked. This attribute is available when using the buffered I/O classes from the io module.

exception ChildProcessError

Возникает, когда операция над дочерним процессом завершилась неудачно. Соответствует errno ECHILD.

exception ConnectionError

Базовый класс для проблем, связанных с подключением.

Подклассами являются BrokenPipeError, ConnectionAbortedError, ConnectionRefusedError и ConnectionResetError.

exception BrokenPipeError

Подкласс ConnectionError, возникающий при попытке записи в канал, когда другой конец закрыт, или при попытке записи в сокет, который был отключен для записи. Соответствует errno EPIPE и ESHUTDOWN.

exception ConnectionAbortedError

Подкласс ConnectionError, вызываемый, когда попытка соединения прерывается узлом. Соответствует errno ECONNABORTED.

exception ConnectionRefusedError

Подкласс ConnectionError, вызываемый, когда попытка соединения отклонена узлом. Соответствует errno ECONNREFUSED.

exception ConnectionResetError

Подкласс ConnectionError, вызываемый при сбросе соединения партнером. Соответствует errno ECONNRESET.

exception FileExistsError

Возникает при попытке создать файл или каталог, который уже существует. Соответствует errno EEXIST.

exception FileNotFoundError

Возникает, когда файл или каталог запрошен, но не существует. Соответствует errno ENOENT.

exception InterruptedError

Возникает, когда системный вызов прерывается входящим сигналом. Соответствует errno EINTR.

Изменено в версии 3.5: Python теперь повторяет системные вызовы, когда системный вызов прерывается сигналом, за исключением случаев, когда обработчик сигнала вызывает исключение (обоснование см. в PEP 475), вместо вызова InterruptedError.

exception IsADirectoryError

Возникает, когда в каталоге запрашивается файловая операция (например, os.remove()). Соответствует errno EISDIR.

exception NotADirectoryError

Возникает, когда операция с каталогом (например, os.listdir()) запрашивается для чего-то, что не является каталогом. На большинстве платформ POSIX он также может возникнуть, если операция пытается открыть или просмотреть файл, не являющийся каталогом, как если бы это был каталог. Соответствует errno ENOTDIR.

exception PermissionError

Возникает при попытке запустить операцию без соответствующих прав доступа, например разрешений файловой системы. Соответствует errno EACCES, EPERM и ENOTCAPABLE.

Изменено в версии 3.11.1: ENOTCAPABLE WASI теперь сопоставлен с PermissionError.

exception ProcessLookupError

Возникает, когда данный процесс не существует. Соответствует errno ESRCH.

exception TimeoutError

Возникает, когда на системном уровне истекло время ожидания системной функции. Соответствует errno ETIMEDOUT.

Добавлено в версии 3.3: Были добавлены все вышеперечисленные подклассы OSError.

См. также

PEP 3151 - Переработка иерархии исключений ОС и ввода-вывода.

Предупреждения

Следующие исключения используются в качестве категорий предупреждений; дополнительную информацию см. в документации Warning Categories.

exception Warning

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

exception UserWarning

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

exception DeprecationWarning

Базовый класс для предупреждений об устаревших функциях, если эти предупреждения предназначены для других разработчиков Python.

Игнорируется фильтрами предупреждений по умолчанию, за исключением модуля __main__ (PEP 565). Включение Режима разработки Python отображает это предупреждение.

Политика прекращения поддержки описана в PEP 387.

exception PendingDeprecationWarning

Базовый класс для предупреждений об устаревших функциях, которые, как ожидается, станут устаревшими в будущем, но не устарели в данный момент.

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

Игнорируется фильтрами предупреждений по умолчанию. Включение Режима разработки Python отображает это предупреждение.

Политика прекращения поддержки описана в PEP 387.

exception SyntaxWarning

Базовый класс для предупреждений о сомнительном синтаксисе.

exception RuntimeWarning

Базовый класс для предупреждений о сомнительном поведении во время выполнения.

exception FutureWarning

Базовый класс для предупреждений об устаревших функциях, если эти предупреждения предназначены для конечных пользователей приложений, написанных на Python.

exception ImportWarning

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

Игнорируется фильтрами предупреждений по умолчанию. Включение Режима разработки Python отображает это предупреждение.

exception UnicodeWarning

Базовый класс для предупреждений, связанных с Unicode.

exception EncodingWarning

Базовый класс для предупреждений, связанных с кодировками.

Подробности см. в Opt-in EncodingWarning.

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

exception BytesWarning

Базовый класс для предупреждений, связанных с bytes и bytearray.

exception ResourceWarning

Базовый класс для предупреждений, связанных с использованием ресурсов.

Игнорируется фильтрами предупреждений по умолчанию. Включение Режима разработки Python отображает это предупреждение.

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

Группы исключений

Следующие действия используются, когда необходимо вызвать несколько несвязанных исключений. Они являются частью иерархии исключений, поэтому их можно обрабатывать с помощью Exception, как и все другие исключения. Кроме того, они распознаются по Exception*, который соответствует их подгруппам на основе типов содержащихся исключений.

exception ExceptionGroup(msg, excs)

exception BaseExceptionGroup(msg, excs)

Оба этих типа исключений заключают исключения в последовательность excs. Параметр msg должен быть строкой. Разница между этими двумя классами заключается в том, что BaseExceptionGroup расширяет BaseException и может обертывать любое исключение, тогда как ExceptionGroup расширяет Exception и может обертывать только подклассы : exc:Исключение. Эта конструкция устроена так, что кроме Exception перехватывается ExceptionGroup, но не BaseExceptionGroup.

Конструктор BaseExceptionGroup возвращает ExceptionGroup вместо BaseExceptionGroup, если все содержащиеся исключения являются экземплярами Exception, поэтому его можно использовать для автоматического выбора. С другой стороны, конструктор ExceptionGroup вызывает TypeError, если какое-либо содержащееся исключение не является подклассом Exception.

message

Аргумент конструктора msg. Это атрибут, доступный только для чтения.

exceptions

Кортеж исключений в последовательности excs, переданный конструктору. Это атрибут, доступный только для чтения.

subgroup(condition)

Возвращает группу исключений, содержащую только те исключения из текущей группы, которые соответствуют условию, или «Нет», если результат пуст.

The condition can be either a function that accepts an exception and returns true for those that should be in the subgroup, or it can be an exception type or a tuple of exception types, which is used to check for a match using the same check that is used in an except clause.

В результате сохраняется структура вложения текущего исключения, а также значения его message, __traceback__, __cause__, :attr:` Поля ~BaseException.__context__` и __notes__. Пустые вложенные группы исключаются из результата.

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

split(condition)

Аналогично subgroup(), но возвращает пару (match, rest), где match — это subgroup(condition), а rest — оставшаяся несовпадающая часть.

derive(excs)

Возвращает группу исключений с тем же message, но которая оборачивает исключения в excs.

Этот метод используется subgroup() и split(), которые используются в различных контекстах для разделения группы исключений. Подкласс должен переопределить его, чтобы subgroup() и split() возвращали экземпляры подкласса, а не ExceptionGroup.

subgroup() и split() копируют __traceback__, __cause__, __context__ и __notes__ из исходной группы исключений в группу, возвращаемую derive(), поэтому эти поля не нужно обновлять с помощью derive().

>>> class MyGroup(ExceptionGroup):
...     def derive(self, excs):
...         return MyGroup(self.message, excs)
...
>>> e = MyGroup("eg", [ValueError(1), TypeError(2)])
>>> e.add_note("a note")
>>> e.__context__ = Exception("context")
>>> e.__cause__ = Exception("cause")
>>> try:
...    raise e
... except Exception as e:
...    exc = e
...
>>> match, rest = exc.split(ValueError)
>>> exc, exc.__context__, exc.__cause__, exc.__notes__
(MyGroup('eg', [ValueError(1), TypeError(2)]), Exception('context'), Exception('cause'), ['a note'])
>>> match, match.__context__, match.__cause__, match.__notes__
(MyGroup('eg', [ValueError(1)]), Exception('context'), Exception('cause'), ['a note'])
>>> rest, rest.__context__, rest.__cause__, rest.__notes__
(MyGroup('eg', [TypeError(2)]), Exception('context'), Exception('cause'), ['a note'])
>>> exc.__traceback__ is match.__traceback__ is rest.__traceback__
True

Note that BaseExceptionGroup defines __new__(), so subclasses that need a different constructor signature need to override that rather than __init__(). For example, the following defines an exception group subclass which accepts an exit_code and and constructs the group’s message from it.

class Errors(ExceptionGroup):
   def __new__(cls, errors, exit_code):
      self = super().__new__(Errors, f"exit code: {exit_code}", errors)
      self.exit_code = exit_code
      return self

   def derive(self, excs):
      return Errors(excs, self.exit_code)

Как и ExceptionGroup, любой подкласс BaseExceptionGroup, который также является подклассом Exception, может обертывать только экземпляры Exception.

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

Иерархия исключений

Иерархия классов для встроенных исключений такова:

BaseException
 ├── BaseExceptionGroup
 ├── GeneratorExit
 ├── KeyboardInterrupt
 ├── SystemExit
 └── Exception
      ├── ArithmeticError
      │    ├── FloatingPointError
      │    ├── OverflowError
      │    └── ZeroDivisionError
      ├── AssertionError
      ├── AttributeError
      ├── BufferError
      ├── EOFError
      ├── ExceptionGroup [BaseExceptionGroup]
      ├── ImportError
      │    └── ModuleNotFoundError
      ├── LookupError
      │    ├── IndexError
      │    └── KeyError
      ├── MemoryError
      ├── NameError
      │    └── UnboundLocalError
      ├── OSError
      │    ├── BlockingIOError
      │    ├── ChildProcessError
      │    ├── ConnectionError
      │    │    ├── BrokenPipeError
      │    │    ├── ConnectionAbortedError
      │    │    ├── ConnectionRefusedError
      │    │    └── ConnectionResetError
      │    ├── FileExistsError
      │    ├── FileNotFoundError
      │    ├── InterruptedError
      │    ├── IsADirectoryError
      │    ├── NotADirectoryError
      │    ├── PermissionError
      │    ├── ProcessLookupError
      │    └── TimeoutError
      ├── ReferenceError
      ├── RuntimeError
      │    ├── NotImplementedError
      │    └── RecursionError
      ├── StopAsyncIteration
      ├── StopIteration
      ├── SyntaxError
      │    └── IndentationError
      │         └── TabError
      ├── SystemError
      ├── TypeError
      ├── ValueError
      │    └── UnicodeError
      │         ├── UnicodeDecodeError
      │         ├── UnicodeEncodeError
      │         └── UnicodeTranslateError
      └── Warning
           ├── BytesWarning
           ├── DeprecationWarning
           ├── EncodingWarning
           ├── FutureWarning
           ├── ImportWarning
           ├── PendingDeprecationWarning
           ├── ResourceWarning
           ├── RuntimeWarning
           ├── SyntaxWarning
           ├── UnicodeWarning
           └── UserWarning