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

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

При возникновении нового исключения, когда другое исключение уже обрабатывается, атрибут нового исключения __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__ ложно.

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

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

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

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

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

exception BaseException

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

args

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

with_traceback(tb)

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

try:
    ...
except SomeException:
    tb = sys.exc_info()[2]
    raise OtherException(...).with_traceback(tb)

exception Exception

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

exception ArithmeticError

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

exception BufferError

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

exception LookupError

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

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

Следующие исключения — это исключения, которые обычно поднимаются.

exception AssertionError

Поднимается, когда оператор assert терпит неудачу.

exception AttributeError

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

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

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

exception EOFError

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

exception FloatingPointError

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

exception GeneratorExit

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

exception ImportError

Поднимается, когда оператор import сталкивается с ошибками при загрузке модуля. Также поднимается, когда имя из списка импорта from ... import не найдено.

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

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

exception NotImplementedError

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

Примечание

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

Примечание

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

exception OSError([arg])

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

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

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

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

exception OverflowError

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

exception RecursionError

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

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

exception ReferenceError

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

exception RuntimeError

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

exception StopIteration

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

Объект исключения имеет единственный атрибут 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

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

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

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

exception PendingDeprecationWarning

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

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

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

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

exception SyntaxWarning

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

exception RuntimeWarning

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

exception FutureWarning

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

exception ImportWarning

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

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

exception UnicodeWarning

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

exception EncodingWarning

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

См. Предупреждения о кодировке (EncodingWarning) для получения подробной информации.

New in version 3.10.

exception BytesWarning

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

exception ResourceWarning

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

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

New in version 3.2.

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

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

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