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

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

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

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

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

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

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

exception IndexError

Вызывается, когда индекс последовательности выходит за пределы допустимого диапазона. (Индексы срезов молча обрезаются до допустимого диапазона; если индекс не является целым числом, вызывается TypeError.)

exception KeyError

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

exception KeyboardInterrupt

Вызывается, когда пользователь нажимает клавишу прерывания (обычно Control-C или Delete). Во время выполнения регулярно проверяются прерывания. Исключение наследуется от BaseException, чтобы код, который перехватывает Exception, случайно его не перехватил, и тем самым не помешал интерпретатору завершить работу.

exception MemoryError

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

exception NameError

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

exception NotImplementedError

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

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

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

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.

2.1. Исключения OS

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

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

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

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

BaseException
 +-- SystemExit
 +-- KeyboardInterrupt
 +-- GeneratorExit
 +-- Exception
      +-- StopIteration
      +-- StopAsyncIteration
      +-- ArithmeticError
      |    +-- FloatingPointError
      |    +-- OverflowError
      |    +-- ZeroDivisionError
      +-- AssertionError
      +-- AttributeError
      +-- BufferError
      +-- EOFError
      +-- ImportError
      +-- 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