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

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

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

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

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

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

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

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, а также из-за возможной несовместимости расположения памяти.

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

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

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

exception BaseException

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

args

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

with_traceback(tb)

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

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

__traceback__

Поле с возможностью записи, в котором хранится traceback object, связанный с данным исключением. См. также: Заявление raise.

add_note(note)

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

Added in version 3.11.

__notes__

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

Added in version 3.11.

exception Exception

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

exception ArithmeticError

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

exception BufferError

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

exception LookupError

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

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

Ниже перечислены исключения, которые обычно возникают.

exception AssertionError

Возникает при сбое оператора assert.

exception AttributeError

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

Атрибуты name и obj могут быть заданы с помощью аргументов конструктора, содержащих только ключевые слова. При установке они представляют собой имя атрибута, к которому была предпринята попытка доступа, и объекта, к которому был получен доступ для этого атрибута, соответственно.

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

exception EOFError

Возникает, когда функция input() достигает условия конца файла (EOF), не прочитав никаких данных. (N.B.: методы io.IOBase.read() и io.IOBase.readline() возвращают пустую строку при попадании в 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, когда модуль не может быть найден. Он также вызывается, когда None найден в sys.modules.

Added in version 3.6.

exception IndexError

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

exception KeyError

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

exception KeyboardInterrupt

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

Примечание

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

exception MemoryError

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

exception NameError

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

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

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

exception NotImplementedError

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

Примечание

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

Примечание

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

exception OSError([arg])

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

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

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

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

errno

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

winerror

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

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

strerror

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

filename

filename2

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

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

Изменено в версии 3.4: Атрибутом filename теперь является исходное имя файла, переданное функции, а не имя, закодированное в filesystem encoding and error handler или декодированное из filesystem encoding and error handler. Также был добавлен аргумент и атрибут конструктора filename2.

exception OverflowError

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

exception PythonFinalizationError

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

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

• Создание нового потока Python.

• os.fork().

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

Added in version 3.13: Раньше в этом случае появлялся обычный RuntimeError.

exception RecursionError

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

Added in version 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__ import generator_stop, см. PEP 479.

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

exception StopAsyncIteration

Должен быть поднят методом __anext__() объекта asynchronous iterator, чтобы остановить итерацию.

Added in version 3.5.

exception SyntaxError(message, details)

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

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

filename

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

lineno

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

offset

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

text

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

end_lineno

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

end_offset

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

Для ошибок в полях f-строки сообщение снабжается префиксом «f-строка: «, а смещения - это смещения в тексте, построенном из выражения замены. Например, компиляция 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

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

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

exception SystemExit

Это исключение вызывается функцией sys.exit(). Оно наследуется от BaseException, а не от Exception, чтобы его случайно не перехватил код, который перехватывает Exception. Это позволяет исключению правильно распространиться вверх и вызвать выход интерпретатора. Если исключение не обрабатывается, интерпретатор Python завершает работу; отслеживание стека не печатается. Конструктор принимает тот же необязательный аргумент, который передается в sys.exit(). Если значение целое, оно определяет статус выхода системы (передается функции 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.

Исключения в ОС

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

exception BlockingIOError

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

Помимо атрибутов OSError, BlockingIOError может иметь еще один атрибут:

characters_written

Целое число, содержащее количество символов, записанных в поток до его блокировки. Этот атрибут доступен при использовании классов буферизованного ввода-вывода из модуля io.

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: WASI’s ENOTCAPABLE теперь отображается на PermissionError.

exception ProcessLookupError

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

exception TimeoutError

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

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

См.также

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

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

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

exception Warning

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

exception UserWarning

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

exception DeprecationWarning

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

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

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

exception PendingDeprecationWarning

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

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

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

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

exception SyntaxWarning

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

exception RuntimeWarning

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

exception FutureWarning

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

exception ImportWarning

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

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

exception UnicodeWarning

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

exception EncodingWarning

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

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

Added in version 3.10.

exception BytesWarning

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

exception ResourceWarning

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

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

Added in version 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.

message

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

exceptions

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

subgroup(condition)

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

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

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

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

Added in version 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.

Added in version 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
      │    └── IncompleteInputError
      │    └── IndentationError
      │         └── TabError
      ├── SystemError
      ├── TypeError
      ├── ValueError
      │    └── UnicodeError
      │         ├── UnicodeDecodeError
      │         ├── UnicodeEncodeError
      │         └── UnicodeTranslateError
      └── Warning
           ├── BytesWarning
           ├── DeprecationWarning
           ├── EncodingWarning
           ├── FutureWarning
           ├── ImportWarning
           ├── PendingDeprecationWarning
           ├── ResourceWarning
           ├── RuntimeWarning
           ├── SyntaxWarning
           ├── UnicodeWarning
           └── UserWarning