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

Базовые классы

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

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» в 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

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

exception NameError

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

exception NotImplementedError

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

Примечание

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

Примечание

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

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 при создании исключения.

Если код генератора напрямую или косвенно возбуждает 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(), или при чтении исходного скрипта или стандартного ввода (также интерактивно).

Метод str() экземпляра исключения возвращает только сообщение об ошибке.

filename

Имя файла, в котором произошла синтаксическая ошибка.

lineno

Номер строки в файле, где произошла ошибка. Индексация с 1: первая строка в файле имеет номер lineno, равный 1.

offset

Номер столбца в строке, где произошла ошибка. Индексация с 1: первый символ в строке имеет номер offset, равный 1.

text

Текст исходного кода, связанный с ошибкой.

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.

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

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

exception Warning

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

exception UserWarning

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

exception DeprecationWarning

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

exception PendingDeprecationWarning

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

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

exception SyntaxWarning

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

exception RuntimeWarning

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

exception FutureWarning

Базовый класс для предупреждений об устаревших функциях, когда эти предупреждения предназначены для конечных пользователей приложений, написанных на Python.

exception ImportWarning

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

exception UnicodeWarning

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

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