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

В 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__ — ложь.

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

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

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

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 нет имени, которое не может быть найдено.

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

Вызывается, когда парсер обнаруживает синтаксическую ошибку. Это может происходить в операторе 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.

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

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

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

См.также

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

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

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

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

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

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

exception PendingDeprecationWarning

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

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

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

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

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

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

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

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

exception ResourceWarning: Базовый класс для предупреждений, связанных с использованием ресурсов. Игнорируется фильтрами предупреждений по умолчанию.

Добавлено в версии 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