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

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

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

BaseException.__context__

BaseException.__cause__

BaseException.__suppress_context__

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

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

raise new_exc from original_exc

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

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

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

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

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

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

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

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 к примечаниям исключения, которые отображаются в стандартной трассировке после строки исключения. Если note не является строкой, возбуждается исключение TypeError.

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

__notes__

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

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

exception Exception

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

exception ArithmeticError

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

exception BufferError

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

exception LookupError

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

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

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

exception AssertionError

Возбуждается, когда инструкция assert завершается неудачно.

exception AttributeError

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

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

name

Имя атрибута, к которому пытались получить доступ.

obj

Объект, к атрибуту которого с указанным именем пытались получить доступ.

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

exception EOFError

Возбуждается, когда функция input() достигает конца файла (EOF), не прочитав ни одного байта данных. (Примечание: методы io.TextIOBase.read() и io.IOBase.readline() возвращают пустую строку при достижении EOF.)

exception FloatingPointError

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

exception GeneratorExit

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

exception ImportError

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

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

name

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

path

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

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

exception ModuleNotFoundError

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

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

exception IndexError

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

exception KeyError

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

exception KeyboardInterrupt

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

Примечание

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

exception MemoryError

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

exception NameError

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

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

name

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

Изменено в версии 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

Соответствующее сообщение об ошибке, предоставленное операционной системой. В POSIX оно форматируется функциями C perror(), а в Windows — FormatMessage().

filename

filename2

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

Изменено в версии 3.3: EnvironmentError, IOError, WindowsError, socket.error, select.error и mmap.error объединены в OSError, и конструктор может возвращать подкласс.

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

exception OverflowError

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

exception PythonFinalizationError

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

Примеры операций, которые могут быть заблокированы с возбуждением PythonFinalizationError во время завершения работы Python:

• Создание нового потока Python.
• Joining работающего потока-демона.
• os.fork().

См. также функцию sys.is_finalizing().

Добавлено в версии 3.13: Ранее возбуждалось обычное исключение RuntimeError.

Изменено в версии 3.14: Теперь threading.Thread.join() может возбуждать это исключение.

exception RecursionError

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

Добавлено в версии 3.5: Ранее возбуждалось обычное исключение RuntimeError.

exception ReferenceError

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

exception RuntimeError

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

exception StopIteration

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

value

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

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

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

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

Изменено в версии 3.5: Добавлено преобразование в RuntimeError через from __future__ import generator_stop; см. PEP 479.

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

exception StopAsyncIteration

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

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

exception SyntaxError(message, details)

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

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

filename

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

lineno

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

offset

Номер столбца в строке, в котором произошла ошибка. Нумерация начинается с 1: первый символ строки имеет offset, равный 1.

text

Текст исходного кода, в котором произошла ошибка.

end_lineno

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

end_offset

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

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

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

exception IndentationError

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

exception TabError

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

exception SystemError

Возбуждается, когда интерпретатор обнаруживает внутреннюю ошибку, но ситуация не настолько серьёзна, чтобы пришлось отказаться от дальнейшей работы. Связанное значение — строка, указывающая, что пошло не так (на низком уровне). В CPython это исключение может быть вызвано неправильным использованием C API Python, например возвратом значения NULL без установленного исключения.

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

exception SystemExit

Это исключение возбуждается функцией sys.exit(). Оно наследуется от BaseException, а не от Exception, чтобы его случайно не перехватил код, обрабатывающий Exception. Это позволяет исключению корректно распространяться вверх по стеку и приводить к завершению интерпретатора. Если исключение не обрабатывается, интерпретатор Python завершает работу без вывода трассировки стека. Конструктор принимает тот же необязательный аргумент, что и sys.exit(). Если значение является целым числом, оно задаёт код завершения системы (передаваемый функции C exit()); если оно равно None, код завершения равен нулю; если оно имеет другой тип (например, строка), выводится значение объекта, а код завершения равен единице.

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

code

Код завершения или сообщение об ошибке, передаваемые конструктору. (По умолчанию равно None.)

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.

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

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

exception Warning

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

exception UserWarning

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

exception DeprecationWarning

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

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

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

exception PendingDeprecationWarning

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

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

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

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

exception SyntaxWarning

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

Обычно это предупреждение выдаётся при компиляции исходного кода Python и, как правило, не появляется при запуске уже скомпилированного кода.

exception RuntimeWarning

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

exception FutureWarning

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

exception ImportWarning

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

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

exception UnicodeWarning

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

exception EncodingWarning

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

Подробности см. в разделе Предупреждение EncodingWarning по запросу.

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

exception BytesWarning

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

exception ResourceWarning

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

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

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

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

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

exception ExceptionGroup(msg, excs)

exception BaseExceptionGroup(msg, excs)

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

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

Группы исключений являются обобщёнными по типу содержащихся в них исключений.

Особенность реализации CPython: Параметр excs может быть любой последовательностью, но списки и кортежи обрабатываются здесь эффективнее. Для оптимальной производительности передавайте кортеж в качестве excs.

message

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

exceptions

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

subgroup(condition)

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

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

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

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

Добавлено в версии 3.13: condition может быть любым вызываемым объектом, не являющимся объектом типа.

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

Обратите внимание, что BaseExceptionGroup определяет __new__(), поэтому подклассы, которым требуется другая сигнатура конструктора, должны переопределять именно его, а не __init__(). Например, следующий код определяет подкласс группы исключений, который принимает exit_code и формирует по нему сообщение группы.

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
      │    ├── PythonFinalizationError
      │    └── 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