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

В 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. Базовые классы

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

exceptionBaseException¶

Базовый класс для всех встроенных исключений. Он не предназначен для прямого наследования пользовательскими классами (для этого используйте Exception). Если для экземпляра этого класса вызван str(), возвращается представление аргумента(ов) экземпляра или пустая строка, если аргументов не было.

args¶

Кортеж аргументов, переданных конструктору исключения. Некоторые встроенные исключения (например, OSError) ожидают определённое количество аргументов и придают особое значение элементам этого кортежа, в то время как другие обычно вызываются только с одной строкой, содержащей сообщение об ошибке.

with_traceback(tb)¶

Этот метод устанавливает tb в качестве новой трассировки для исключения и возвращает объект исключения. Обычно используется в коде обработки исключений, например так:

try:
    ...
except SomeException:
    tb = sys.exc_info()[2]
    raise OtherException(...).with_traceback(tb)

exceptionException¶

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

exceptionArithmeticError¶

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

exceptionBufferError¶

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

exceptionLookupError¶

Базовый класс для исключений, которые возбуждаются, когда ключ или индекс, используемые в отображении или последовательности, недопустимы: IndexError, KeyError. Оно может быть возбуждено непосредственно с помощью codecs.lookup().

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

Следующие исключения – это исключения, которые обычно возбуждаются.

exceptionAssertionError¶

Возбуждается, когда assert не выполняется.

exceptionAttributeError¶

Возбуждается, когда обращение к атрибуту (см. Обращения к атрибутам) или присваивание не удаётся. (Когда объект вообще не поддерживает обращение к атрибутам или их присваивание, возбуждается TypeError.)

exceptionEOFError¶

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

exceptionFloatingPointError¶

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

exceptionGeneratorExit¶

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

exceptionImportError¶

Возникает, когда оператор import не может загрузить модуль. Также возникает, когда «from list» в from ... import содержит имя, которое не удаётся найти.

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

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

exceptionModuleNotFoundError¶

Подкласс ImportError, который вызывается import, когда модуль не найден. Также вызывается, когда None найдена в sys.modules.

Новое в версии 3.6.

exceptionIndexError¶

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

exceptionKeyError¶

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

exceptionKeyboardInterrupt¶

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

exceptionMemoryError¶

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

exceptionNameError¶

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

exceptionNotImplementedError¶

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

Примечание

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

Примечание

NotImplementedError и NotImplemented не взаимозаменяемы, даже несмотря на схожие названия и назначение. Подробнее о том, когда их использовать, см. в NotImplemented.

exceptionOSError([arg])¶

exceptionOSError(errno, strerror[, filename[, winerror[, filename2]]])

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

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

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

errno¶

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

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.

exceptionOverflowError¶

Возбуждается, когда результат арифметической операции слишком велик для представления. Для целых чисел этого не может произойти (они скорее возбудят MemoryError, чем откажутся). Однако по историческим причинам OverflowError иногда возбуждается для целых чисел, выходящих за пределы требуемого диапазона. Из-за отсутствия стандартизации обработки исключений с плавающей точкой в C большинство операций с плавающей точкой не проверяются.

exceptionRecursionError¶

Это исключение является производным от RuntimeError. Оно возбуждается, когда интерпретатор обнаруживает, что превышена максимальная глубина рекурсии (см. sys.getrecursionlimit()).

Новое в версии 3.5: Ранее возбуждалось простое RuntimeError.

exceptionReferenceError¶

Это исключение возбуждается, когда прокси-объект слабой ссылки, созданный функцией weakref.proxy(), используется для доступа к атрибуту референта после его сборки мусора. Дополнительную информацию о слабых ссылках см. в модуле weakref.

exceptionRuntimeError¶

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

exceptionStopIteration¶

Вызывается встроенной функцией next() и методом __next__() итератора, чтобы указать, что итератор больше не производит элементы.

У объекта исключения есть единственный атрибут value, который передаётся как аргумент при создании исключения и по умолчанию равен None.

Когда функция генератора или корутины возвращает значение, возбуждается новый экземпляр StopIteration, и возвращённое функцией значение используется в качестве параметра value конструктора исключения.

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

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

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

exceptionStopAsyncIteration¶

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

Новое в версии 3.5.

exceptionSyntaxError¶

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

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

exceptionIndentationError¶

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

exceptionTabError¶

Возникает, когда в отступах используется непоследовательное сочетание табуляции и пробелов. Является подклассом IndentationError.

exceptionSystemError¶

Возбуждается, когда интерпретатор обнаруживает внутреннюю ошибку, но ситуация не настолько серьезна, чтобы ему пришлось полностью отказаться от дальнейшего выполнения. Ассоциированное значение – строка, поясняющая, что пошло не так (на низком уровне).

Сообщите об этом автору или сопровождающему вашего интерпретатора Python. Обязательно укажите версию интерпретатора Python (sys.version; она также выводится в начале интерактивного сеанса Python), точное сообщение об ошибке (ассоциированное значение исключения) и, если возможно, исходный код программы, вызвавшей ошибку.

exceptionSystemExit¶

Это исключение вызывается функцией sys.exit(). Оно наследуется от BaseException, а не от Exception, чтобы его случайно не перехватил код, перехватывающий Exception. Это позволяет исключению корректно распространяться вверх и приводить к выходу интерпретатора. Если оно не обработано, интерпретатор Python завершает работу; стек вызовов не выводится. Конструктор принимает тот же необязательный аргумент, который передаётся функции sys.exit(). Если значение – целое число, оно задаёт системный статус выхода (передаётся функции exit() из C); если это None, статус выхода – ноль; если оно имеет другой тип (например, строку), значение объекта выводится, а статус выхода – единица.

Вызов sys.exit() преобразуется в исключение, чтобы могли выполниться обработчики очистки (предложения finally инструкций try), а отладчик мог выполнить сценарий без риска потерять управление. Функцию os._exit() можно использовать, если абсолютно необходимо выйти немедленно (например, в дочернем процессе после вызова os.fork()).

code¶

Статус выхода или сообщение об ошибке, передаваемое конструктору. (По умолчанию None.)

exceptionTypeError¶

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

Это исключение может быть вызвано пользовательским кодом, чтобы указать, что предпринятая операция над объектом не поддерживается и не должна поддерживаться. Если объект должен поддерживать данную операцию, но ещё не предоставил реализацию, правильным исключением будет NotImplementedError.

Передача аргументов неверного типа (например, передача list, когда ожидается int) должна приводить к TypeError, а передача аргументов с неверным значением (например, числа вне ожидаемых границ) должна приводить к ValueError.

exceptionUnboundLocalError¶

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

exceptionUnicodeError¶

Возникает, когда происходит ошибка кодирования или декодирования, связанная с Unicode. Является подклассом ValueError.

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

encoding¶

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

reason¶

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

object¶

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

start¶

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

end¶

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

exceptionUnicodeEncodeError¶

Возникает при ошибке, связанной с Unicode, во время кодирования. Является подклассом UnicodeError.

exceptionUnicodeDecodeError¶

Возникает при ошибке, связанной с Unicode, во время декодирования. Является подклассом UnicodeError.

exceptionUnicodeTranslateError¶

Возникает при ошибке, связанной с Unicode, во время трансляции. Является подклассом UnicodeError.

exceptionValueError¶

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

exceptionZeroDivisionError¶

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

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

exceptionEnvironmentError¶

exceptionIOError¶

exceptionWindowsError¶

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

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

Следующие исключения являются подклассами OSError; они возникают в зависимости от системного кода ошибки.

exceptionBlockingIOError¶

Возникает, когда операция привела бы к блокировке объекта (например, сокета), установленного в неблокирующий режим. Соответствует errno EAGAIN, EALREADY, EWOULDBLOCK и EINPROGRESS.

В дополнение к атрибутам OSError, BlockingIOError может иметь ещё один атрибут:

characters_written¶

Целое число, содержащее количество символов, записанных в поток до его блокировки. Этот атрибут доступен при использовании буферизированных классов ввода-вывода из модуля io.

exceptionChildProcessError¶

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

exceptionConnectionError¶

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

Подклассами являются BrokenPipeError, ConnectionAbortedError, ConnectionRefusedError и ConnectionResetError.

exceptionBrokenPipeError¶

Подкласс ConnectionError, возбуждаемый при попытке записи в канал, когда другой конец закрыт, или при попытке записи в сокет, который был закрыт для записи. Соответствует errno, EPIPE и ESHUTDOWN.

exceptionConnectionAbortedError¶

Подкласс ConnectionError, возбуждаемый, когда попытка соединения прерывается удалённой стороной. Соответствует errno ECONNABORTED.

exceptionConnectionRefusedError¶

Подкласс ConnectionError, возбуждаемый, когда попытка соединения отклоняется удалённой стороной. Соответствует errno ECONNREFUSED.

exceptionConnectionResetError¶

Подкласс ConnectionError, возбуждаемый, когда соединение сбрасывается удалённой стороной. Соответствует errno ECONNRESET.

exceptionFileExistsError¶

Возбуждается при попытке создать файл или каталог, который уже существует. Соответствует errno EEXIST.

exceptionFileNotFoundError¶

Возбуждается, когда запрашивается файл или каталог, который не существует. Соответствует errno ENOENT.

exceptionInterruptedError¶

Возбуждается, когда системный вызов прерывается входящим сигналом. Соответствует errno EINTR.

Изменено в версии 3.5: Теперь Python повторяет системные вызовы, когда системный вызов прерывается сигналом, за исключением случаев, когда обработчик сигнала возбуждает исключение (см. PEP 475 с обоснованием), вместо возбуждения InterruptedError.

exceptionIsADirectoryError¶

Возбуждается, когда файловая операция (например, os.remove()) запрашивается для каталога. Соответствует errno EISDIR.

exceptionNotADirectoryError¶

Возбуждается, когда запрашивается операция с каталогом (например, os.listdir()) над объектом, который не является каталогом. Соответствует errno ENOTDIR.

exceptionPermissionError¶

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

exceptionProcessLookupError¶

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

exceptionTimeoutError¶

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

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

Смотрите также

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

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

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

exceptionWarning¶

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

exceptionUserWarning¶

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

exceptionDeprecationWarning¶

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

exceptionPendingDeprecationWarning¶

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

exceptionSyntaxWarning¶

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

exceptionRuntimeWarning¶

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

exceptionFutureWarning¶

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

exceptionImportWarning¶

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

exceptionUnicodeWarning¶

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

exceptionBytesWarning¶

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

exceptionResourceWarning¶

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

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