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

Исключения должны быть объектами классов. Исключение определены в модуле exceptions. Этот модуль никогда не нужно импортировать явно: исключения предоставляются в встроенном пространстве имён, а также в модуле exceptions.

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

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

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

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

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

exception BaseException

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

New in version 2.5.

args

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

exception Exception

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

Изменено в версии 2.5: Изменено для наследования от BaseException.

exception StandardError

Базовый класс для всех встроенных исключений, кроме StopIteration, GeneratorExit, KeyboardInterrupt и SystemExit. Сам StandardError происходит от Exception.

exception ArithmeticError

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

exception BufferError

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

exception LookupError

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

exception EnvironmentError

Базовый класс для исключений, которые могут возникнуть вне системы Python: IOError, OSError. При создании исключений этого типа с 2-кортежем, первый элемент доступен в атрибуте экземпляра errno (предполагается, что это номер ошибки), а второй элемент доступен в атрибуте strerror (обычно это соответствующее сообщение об ошибке). Сам кортеж также доступен в атрибуте args.

New in version 1.5.2.

Когда исключение EnvironmentError создаётся с 3-кортежем, первые два элемента доступны, как и выше, а третий элемент доступен в атрибуте filename. Однако для обратной совместимости, атрибут args содержит только 2-кортеж из первых двух аргументов конструктора.

Атрибут filename является None когда это исключение создаётся с другими аргументами, кроме 3. Атрибуты errno и strerror также None когда экземпляр был создан с аргументами, отличными от 2 или 3. В последнем случае args содержит фактические аргументы конструктора в виде кортежа.

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

exception AssertionError

Вызывается, когда оператор assert терпит неудачу.

exception AttributeError

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

exception EOFError

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

exception FloatingPointError

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

exception GeneratorExit

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

Новая функция с версии 2.5.

Изменено в версии 2.6: Изменено наследование от BaseException.

exception IOError

Вызывается, когда операция ввода-вывода (например, оператор print, встроенная функция open() или метод объекта файла) завершается неудачно по причине, связанной с вводом-выводом, например, «файл не найден» или «диск заполнен».

Этот класс наследуется от EnvironmentError. См. обсуждение выше для получения дополнительной информации об атрибутах экземпляра исключения.

Изменено в версии 2.6: Изменено, socket.error использует этот класс в качестве базового.

exception ImportError

Вызывается, когда оператор import не находит определение модуля или когда from ... import не находит имя для импорта.

exception IndexError

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

exception KeyError

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

exception KeyboardInterrupt

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

Изменено в версии 2.5: Изменено наследование от BaseException.

exception MemoryError

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

exception NameError

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

exception NotImplementedError

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

Новая функция с версии 1.5.2.

exception OSError

Это исключение наследуется от EnvironmentError. Оно вызывается, когда функция возвращает системную ошибку (не для недопустимых типов аргументов или других случайных ошибок). Атрибут errno — числовой код ошибки из errno, а атрибут strerror — соответствующая строка, которая будет напечатана функцией C perror(). См. модуль errno, который содержит имена кодов ошибок, определённых базовой операционной системой.

Для исключений, связанных с путём к файлу (например, chdir() или unlink()), экземпляр исключения будет содержать третий атрибут filename, который является именем файла, переданным в функцию.

Новая функция с версии 1.5.2.

exception OverflowError

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

exception ReferenceError

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

Новая функция с версии 2.2: Ранее было известно как исключение weakref.ReferenceError.

exception RuntimeError

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

exception StopIteration

Вызывается методом next() итератора итератора для указания, что дополнительных значений больше нет. Этот класс наследуется от Exception, а не от StandardError, так как это не считается ошибкой в его обычном применении.

Новая функция с версии 2.2.

exception SyntaxError

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

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

exception IndentationError

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

exception TabError

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

exception SystemError

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

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

exception SystemExit

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

У экземпляров есть атрибут code, который устанавливается в предлагаемый код завершения или сообщение об ошибке (по умолчанию None). Кроме того, это исключение непосредственно происходит от BaseException, а не от StandardError, так как технически это не ошибка.

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

Исключение наследуется от BaseException, а не от StandardError или Exception, чтобы избежать случайного перехвата кодом, ловящим Exception. Это позволяет исключению корректно распространяться вверх и привести к завершению интерпретатора.

Изменено в версии 2.5: Изменено на наследование от BaseException.

exception TypeError

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

exception UnboundLocalError

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

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

exception UnicodeError

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

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

encoding

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

reason

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

object

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

start

Первый индекс неверных данных в object.

end

Индекс после последнего неверного данных в object.

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

exception UnicodeEncodeError

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

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

exception UnicodeDecodeError

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

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

exception UnicodeTranslateError

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

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

exception ValueError

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

exception VMSError

Доступна только на VMS. Возникает при возникновении ошибки, специфичной для VMS.

exception WindowsError

Возникает при возникновении ошибки, специфичной для Windows, или когда номер ошибки не соответствует значению errno. Значения winerror и strerror создаются из возвращаемых значений функций GetLastError() и FormatMessage() из платформенного API Windows. Значение errno сопоставляет значение winerror с соответствующими значениями errno.h. Это подкласс OSError.

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

Изменено в версии 2.5: Предыдущие версии помещали коды GetLastError() в errno.

exception ZeroDivisionError

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

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

exception Warning

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

exception UserWarning

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

exception DeprecationWarning

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

exception PendingDeprecationWarning

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

exception SyntaxWarning

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

exception RuntimeWarning

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

exception FutureWarning

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

exception ImportWarning

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

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

exception UnicodeWarning

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

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

exception BytesWarning

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

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

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

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

BaseException
 +-- SystemExit
 +-- KeyboardInterrupt
 +-- GeneratorExit
 +-- Exception
      +-- StopIteration
      +-- StandardError
      |    +-- BufferError
      |    +-- ArithmeticError
      |    |    +-- FloatingPointError
      |    |    +-- OverflowError
      |    |    +-- ZeroDivisionError
      |    +-- AssertionError
      |    +-- AttributeError
      |    +-- EnvironmentError
      |    |    +-- IOError
      |    |    +-- OSError
      |    |         +-- WindowsError (Windows)
      |    |         +-- VMSError (VMS)
      |    +-- EOFError
      |    +-- ImportError
      |    +-- LookupError
      |    |    +-- IndexError
      |    |    +-- KeyError
      |    +-- MemoryError
      |    +-- NameError
      |    |    +-- UnboundLocalError
      |    +-- ReferenceError
      |    +-- RuntimeError
      |    |    +-- NotImplementedError
      |    +-- SyntaxError
      |    |    +-- IndentationError
      |    |         +-- TabError
      |    +-- SystemError
      |    +-- TypeError
      |    +-- ValueError
      |         +-- UnicodeError
      |              +-- UnicodeDecodeError
      |              +-- UnicodeEncodeError
      |              +-- UnicodeTranslateError
      +-- Warning
           +-- DeprecationWarning
           +-- PendingDeprecationWarning
           +-- RuntimeWarning
           +-- SyntaxWarning
           +-- UserWarning
           +-- FutureWarning
	   +-- ImportWarning
	   +-- UnicodeWarning
	   +-- BytesWarning