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

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

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

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.)

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 элемент списка «from» не найден.

Атрибуты 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

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

exception NameError

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

exception NotImplementedError

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

Примечание

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

Примечание

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

exception OSError([arg])

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

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

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

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

errno

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

winerror

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

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

strerror

Соответствующее сообщение об ошибке, предоставленное операционной системой. Оно форматируется функциями 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

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

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

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 отображает это предупреждение.

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

exception PendingDeprecationWarning

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

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

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

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

exception SyntaxWarning

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

exception RuntimeWarning

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

exception FutureWarning

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

exception ImportWarning

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

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

exception UnicodeWarning

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

exception BytesWarning

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

exception ResourceWarning

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

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

Новое в версии 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
           +-- ResourceWarning