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

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

При создании нового исключения, когда другое исключение уже обрабатывается, атрибут __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.

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

Наследование от встроенных исключений¶

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

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

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

exception BaseException¶

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

args¶

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

with_traceback(tb)¶

Этот метод устанавливает tb в качестве нового обратного пути для исключения и возвращает объект исключения. Этот метод чаще всего использовался до появления возможностей цепочки исключений в PEP 3134. Следующий пример показывает, как мы можем преобразовать экземпляр SomeException в экземпляр OtherException, сохраняя при этом обратную связь. После поднятия текущий кадр выталкивается в трассировку OtherException, как это произошло бы с трассировкой исходного SomeException, если бы мы позволили ему распространиться на вызывающую сторону.

try:
    ...
except SomeException:
    tb = sys.exc_info()[2]
    raise OtherException(...).with_traceback(tb)

exception Exception¶

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

exception ArithmeticError¶

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

exception BufferError¶

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

exception LookupError¶

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

Бетонные исключения¶

Ниже перечислены исключения, которые обычно поднимаются.

exception AssertionError¶

Возникает при неудачном выполнении оператора assert.

exception AttributeError¶

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

Атрибуты name и obj могут быть установлены с помощью аргументов конструктора, содержащих только ключевые слова. Когда они установлены, они представляют имя атрибута, к которому пытались получить доступ, и объекта, к которому был получен доступ для этого атрибута, соответственно.

Изменено в версии 3.10: Добавлены атрибуты name и obj.

exception EOFError¶

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

exception FloatingPointError¶

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

exception GeneratorExit¶

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

exception ImportError¶

Возникает, когда оператор import испытывает проблемы при попытке загрузить модуль. Также вызывается, когда «from list» в 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¶

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

exception NameError¶

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

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

Изменено в версии 3.10: Добавлен атрибут name.

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¶

Соответствующее сообщение об ошибке, предоставляемое операционной системой. Форматируется функциями языка Си 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 теперь является исходное имя файла, переданное функции, а не имя, закодированное в или декодированное из filesystem encoding and error handler. Также был добавлен аргумент и атрибут конструктора filename2.

exception OverflowError¶

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

exception RecursionError¶

Это исключение является производным от RuntimeError. Оно возникает, когда интерпретатор обнаруживает, что превышена максимальная глубина рекурсии (см. sys.getrecursionlimit()).

Добавлено в версии 3.5: Ранее выдавалось обычное RuntimeError.

exception ReferenceError¶

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

exception RuntimeError¶

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

exception StopIteration¶

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

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

Когда функция generator или coroutine возвращается, поднимается новый экземпляр 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__() объекта asynchronous iterator для остановки итерации.

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

exception SyntaxError(message, details)¶

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

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

filename¶

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

lineno¶

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

offset¶

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

text¶

Текст исходного кода, в котором произошла ошибка.

end_lineno¶

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

end_offset¶

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

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

Изменено в версии 3.10: Добавлены атрибуты end_lineno и end_offset.

exception IndentationError¶

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

exception TabError¶

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

exception SystemError¶

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

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

exception SystemExit¶

Это исключение вызывается функцией sys.exit(). Оно наследуется от BaseException вместо Exception, чтобы оно не было случайно поймано кодом, который ловит Exception. Это позволяет исключению правильно распространиться вверх и вызвать выход интерпретатора. Если исключение не обрабатывается, интерпретатор Python завершает работу; отслеживание стека не печатается. Конструктор принимает тот же необязательный аргумент, который передается в sys.exit(). Если значение целое, то оно определяет статус выхода системы (передается в функцию Си 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¶

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

exception ValueError¶

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

exception ZeroDivisionError¶

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

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

exception EnvironmentError¶

exception IOError¶

exception WindowsError¶

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

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

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

exception Warning¶

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

exception UserWarning¶

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

exception DeprecationWarning¶

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

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

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

exception PendingDeprecationWarning¶

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

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

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

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

exception SyntaxWarning¶

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

exception RuntimeWarning¶

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

exception FutureWarning¶

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

exception ImportWarning¶

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

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

exception UnicodeWarning¶

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

exception EncodingWarning¶

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

Подробнее см. в разделе Кодирование по желаниюПредупреждение.

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

exception BytesWarning¶

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

exception ResourceWarning¶

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

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

Добавлено в версии 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
           +-- EncodingWarning
           +-- ResourceWarning