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

В 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