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

Контекст исключения¶Exception context

При возбуждении нового исключения, когда другое исключение уже обрабатывается, атрибут __context__ нового исключения автоматически устанавливается на обрабатываемое исключение. Исключение может обрабатываться при использовании предложения except или finally, или оператора with.

Этот неявный контекст исключения может быть дополнен явной причиной с помощью 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.

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

Наследование от встроенных исключений¶Inheriting from built-in exceptions

Пользовательский код может создавать подклассы, которые наследуют от типа исключения. Рекомендуется создавать подкласс только одного типа исключения за раз, чтобы избежать возможных конфликтов в обработке атрибута args базовыми классами, а также из-за возможных несовместимостей компоновки памяти.

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

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

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

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, и тем самым не заблокировал завершение интерпретатора.

Примечание

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

exception MemoryError¶

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

exception NameError¶

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

exception NotImplementedError¶

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

Примечание

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

Примечание

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

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, 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(message, details)¶

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

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

filename¶

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

lineno¶

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

offset¶

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

text¶

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

Для ошибок в полях f-строк к сообщению добавляется префикс “f-string: ”, а смещения вычисляются в тексте, построенном из выражения подстановки. Например, компиляция f’Bad {a b} field’ приводит к такому атрибуту args: (‘f-string: …’, (‘’, 1, 4, ‘(a b)n’)).

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¶

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

Это исключение может вызываться пользовательским кодом, чтобы указать, что попытка выполнить операцию над объектом не поддерживается и не предполагается. Если объект должен поддерживать данную операцию, но ещё не имеет реализации, правильным исключением будет 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¶

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

exception ValueError¶

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

exception ZeroDivisionError¶

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

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

exception EnvironmentError¶

exception IOError¶

exception WindowsError¶

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

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

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

exception Warning¶

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

exception UserWarning¶

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

exception DeprecationWarning¶

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

Игнорируется фильтрами предупреждений по умолчанию, за исключением модуля __main__ (PEP 565). Включение режима разработки Python показывает это предупреждение.

Политика устаревания описана в PEP 387.

exception PendingDeprecationWarning¶

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

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

Игнорируется фильтрами предупреждений по умолчанию. Включение режима разработки Python отображает это предупреждение.

Политика устаревания описана в PEP 387.

exception SyntaxWarning¶

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

exception RuntimeWarning¶

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

exception FutureWarning¶

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

exception ImportWarning¶

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

Игнорируется фильтрами предупреждений по умолчанию. Включение режима разработки Python отображает это предупреждение.

exception UnicodeWarning¶

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

exception BytesWarning¶

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

exception ResourceWarning¶

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

Игнорируется фильтрами предупреждений по умолчанию. Включение режима разработки Python отображает это предупреждение.

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

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

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

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