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

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

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

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

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

При поднятии (или повторном поднятии) исключения в фрагменте except или finally __context__ автоматически устанавливается на последнее пойманное исключение; если новое исключение не обрабатывается, трассировка стека, которая в конечном итоге отображается, будет содержать исходные исключения и конечное исключение.

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

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

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

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

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

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

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

exception AssertionError

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

exception AttributeError

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

exception EOFError

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

exception FloatingPointError

Генерируется, когда операция с плавающей точкой терпит неудачу. Это исключение всегда определено, но может быть сгенерировано только при конфигурации Python с опцией --with-fpectl или символом WANT_SIGFPE_HANDLER в файле pyconfig.h.

exception GeneratorExit

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

exception ImportError

Генерируется, когда оператор import испытывает проблемы с загрузкой модуля. Также генерируется, когда в «списке from» в 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, и таким образом предотвратить выход интерпретатора.

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, как описано в разделе 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 конструктора исключения.

Если функция-генератор, определённая в присутствии директивы from __future__ import generator_stop, вызывает StopIteration, то она преобразуется в RuntimeError (при этом StopIteration сохраняется как причина нового исключения).

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

Изменено в версии 3.5: Введено преобразование в RuntimeError.

exception StopAsyncIteration

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

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

exception SyntaxError

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

Экземпляры этого класса имеют атрибуты filename, lineno, offset и text для более удобного доступа к деталям. str() экземпляра исключения возвращает только сообщение.

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

Вызывается при возникновении ошибки кодирования или декодирования, связанной с Юникодом. Это подкласс ValueError.

UnicodeError имеет атрибуты, описывающие ошибку кодирования или декодирования. Например, err.object[err.start:err.end] содержит конкретный неверный ввод, по которому кодек не смог выполнить операцию.

encoding

Имя кодировки, вызвавшей ошибку.

reason

Строка, описывающая конкретную ошибку кодека.

object

Объект, который кодек пытался закодировать или декодировать.

start

Первый индекс недопустимых данных в object.

end

Индекс после последнего недопустимого элемента в object.

exception UnicodeEncodeError

Вызывается, когда происходит ошибка кодирования, связанная с Юникодом. Это подкласс UnicodeError.

exception UnicodeDecodeError

Вызывается, когда происходит ошибка декодирования, связанная с Юникодом. Это подкласс UnicodeError.

exception UnicodeTranslateError

Вызывается, когда происходит ошибка преобразования, связанная с Юникодом. Это подкласс UnicodeError.

exception ValueError

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

exception ZeroDivisionError

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

Следующие исключения сохраняются для совместимости с предыдущими версиями; начиная с Python 3.3, они являются псевдонимами OSError.

exception EnvironmentError

exception IOError

exception WindowsError

Доступно только в Windows.

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

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

exception PermissionError

Вызывается при попытке выполнить операцию без необходимых прав доступа — например, права доступа к файловой системе. Соответствует errno EACCES и EPERM.

exception ProcessLookupError

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

exception TimeoutError

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

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

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

exception Warning

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

exception UserWarning

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

exception DeprecationWarning

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

exception PendingDeprecationWarning

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

exception SyntaxWarning

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

exception RuntimeWarning

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

exception FutureWarning

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

exception ImportWarning

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

exception UnicodeWarning

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

exception BytesWarning

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

exception ResourceWarning

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

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

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

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

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