5. Встроенные исключения¶Built-in Exceptions

5.1. Базовые классы¶Base classes

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

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

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

Обычно возбуждаются следующие исключения.

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¶

Возбуждается при вызове у генератора метода 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, как описано ниже в разделе исключения ОС. Конкретный подкласс зависит от конечного значения 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, VMSError, socket.error, select.error и mmap.error были объединены в OSError, и конструктор может возвращать подкласс.

Изменено в версии 3.4: Атрибут filename теперь является исходным именем файла, переданным функции, а не именем, закодированным или декодированным из кодировки файловой системы. Кроме того, были добавлены аргумент конструктора и атрибут filename2.

exception OverflowError¶

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

exception ReferenceError¶

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

exception RuntimeError¶

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

exception StopIteration¶

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

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

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

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

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(). Если значение является целым числом, оно задаёт код завершения системы (передаётся функции exit() в C); если это 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.

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

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

5.4. Иерархия исключений¶Exception hierarchy

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

BaseException
 +-- SystemExit
 +-- KeyboardInterrupt
 +-- GeneratorExit
 +-- Exception
      +-- StopIteration
      +-- 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
      +-- SyntaxError
      |    +-- IndentationError
      |         +-- TabError
      +-- SystemError
      +-- TypeError
      +-- ValueError
      |    +-- UnicodeError
      |         +-- UnicodeDecodeError
      |         +-- UnicodeEncodeError
      |         +-- UnicodeTranslateError
      +-- Warning
           +-- DeprecationWarning
           +-- PendingDeprecationWarning
           +-- RuntimeWarning
           +-- SyntaxWarning
           +-- UserWarning
           +-- FutureWarning
           +-- ImportWarning
           +-- UnicodeWarning
           +-- BytesWarning
           +-- ResourceWarning