Built-in ExceptionsВстроенные исключения

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

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

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

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

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

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

BaseException.__context__¶

BaseException.__cause__¶

BaseException.__suppress_context__¶

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

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

python

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.

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

Inheriting from built-in exceptionsНаследование от встроенных исключений

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

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

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

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

exception BaseException¶

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

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

with_traceback(tb)¶

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

python

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¶: Возбуждается, когда не может быть выполнена операция, связанная с буфером.

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

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

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

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 list» в from ... import содержит имя, которое не удаётся найти.

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

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

path¶: Путь к файлу, который вызвал исключение.

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

exception ModuleNotFoundError¶: Подкласс ImportError, который вызывается import, когда модуль не найден. Также вызывается, когда None найдена в sys.modules.

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

exception ImportCycleError¶: Подкласс ImportError, который вызывается, когда ленивый импорт не удаётся, поскольку он (прямо или косвенно) пытается импортировать сам себя.

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

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 содержит только 2-кортеж из первых двух аргументов конструктора.

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

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

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 теперь содержит исходное имя файла, переданное функции, вместо имени, закодированного или декодированного с использованием кодировки файловой системы и обработчика ошибок. Кроме того, был добавлен аргумент конструктора и атрибут filename2.

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

exception PythonFinalizationError¶

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

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

Создание нового потока Python.
Joining запущенного потока-демона.
os.fork(),
захват блокировки, такой как threading.Lock, когда известно, что в противном случае операция приведёт к взаимоблокировке.

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

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

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

Изменено в версии 3.15: Это исключение может возбуждаться при получении threading.Lock() или threading.RLock().

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() экземпляра исключения возвращает только сообщение об ошибке. Details представляет собой кортеж, члены которого также доступны как отдельные атрибуты.

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(). Если значение – целое число, оно задаёт системный статус выхода (передаётся функции exit() из C); если это 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.

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

Следующие исключения являются подклассами 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 ENOTCAPABLE теперь отображается на PermissionError.

exception ProcessLookupError¶: Возбуждается, когда указанный процесс не существует. Соответствует errno ESRCH.

exception TimeoutError¶: Возбуждается, когда системная функция превысила время ожидания на системном уровне. Соответствует errno ETIMEDOUT.

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

Смотрите также

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

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

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

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¶

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

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

exception EncodingWarning¶

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

Подробнее см. Opt-in EncodingWarning.

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

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

exception ResourceWarning¶

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

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

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

Следующие используются, когда необходимо возбудить несколько не связанных между собой исключений. Они являются частью иерархии исключений, поэтому их можно обрабатывать с помощью 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. Условие также может быть вызываемым объектом (отличным от объекта типа), который принимает исключение в качестве единственного аргумента и возвращает true для исключений, которые должны быть в подгруппе.

Структура вложенности текущего исключения сохраняется в результате, как и значения его полей 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().

python

>>> 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 и конструирует сообщение группы из него.

python

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.

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

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

text

BaseException
 ├── BaseExceptionGroup
 ├── GeneratorExit
 ├── KeyboardInterrupt
 ├── SystemExit
 └── Exception
      ├── ArithmeticError
      │    ├── FloatingPointError
      │    ├── OverflowError
      │    └── ZeroDivisionError
      ├── AssertionError
      ├── AttributeError
      ├── BufferError
      ├── EOFError
      ├── ExceptionGroup [BaseExceptionGroup]
      ├── ImportError
      │    └── ImportCycleError
      │    └── 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

Built-in ExceptionsВстроенные исключения​

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

Inheriting from built-in exceptionsНаследование от встроенных исключений​

Base classesБазовые классы​

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

OS exceptionsИсключения ОС​

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

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

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

Built-in ExceptionsВстроенные исключения

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

Inheriting from built-in exceptionsНаследование от встроенных исключений

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

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

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

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

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

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