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

В 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__ ложно.

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

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

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

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.readline() и io.IOBase.read() возвращают пустую строку, когда сталкиваются с EOF.)

exception FloatingPointError

В настоящее время не используется.

exception GeneratorExit

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

exception ImportError

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

Атрибуты 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

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

exception NameError

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

exception NotImplementedError

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

Примечание

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

Примечание

NotImplementedError и NotImplemented не взаимозаменяемы, даже если они имеют похожие имена и назначение. Подробности о том, когда использовать 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(), используется для доступа к атрибуту referent после того, как он был собран сборщиком мусора. Дополнительную информацию о слабых ссылках см. в модуле 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(), или при чтении исходного скрипта или стандартного ввода (в интерактивном режиме).

Экземпляры этого класса имеют атрибуты 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

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

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

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

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

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

exception ValueError

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

exception ZeroDivisionError

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

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

exception EnvironmentError

exception IOError

exception WindowsError

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

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

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

Категории предупреждений

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

exception Warning

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

exception UserWarning

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

exception DeprecationWarning

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

exception PendingDeprecationWarning

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

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

exception SyntaxWarning

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

exception RuntimeWarning

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

exception FutureWarning

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

exception ImportWarning

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

exception UnicodeWarning

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

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