Встроенные исключения
В 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.read()
иio.IOBase.readline()
возвращают пустую строку при достижении EOF.)
-
exception
FloatingPointError
В настоящее время не используется.
-
exception
GeneratorExit
Возникает при закрытии генератора или корутины; см.
generator.close()
иcoroutine.close()
. Он напрямую наследуется отBaseException
вместоException
, поскольку технически это не ошибка.
-
exception
ImportError
Вызывается, когда оператор
import
не может загрузить модуль. Также Вызывается, когда «из списка»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
Вызывается, когда для операции не хватает памяти, но ситуацию можно исправить (удалив некоторые объекты). Связанное значение представляет собой строку, указывающую, для какой (внутренней) операции закончилась память. Обратите внимание, что из-за базовой архитектуры управления памятью (функция 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
Вызывается, когда парсер обнаруживает синтаксическую ошибку. Это может происходить в операторе
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()
. Если значение является целым числом, оно указывает статус выхода из системы (передаётся в функцию Cexit()
); если это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.
Исключения ОС
Следующие исключения являются подклассами 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
.
Добавлено в версии 3.3: Были добавлены все вышеперечисленные подклассы OSError
.
См.также
PEP 3151 — переработка иерархии исключений ОС и ввода-вывода
Предупреждения
Следующие исключения используются как категории предупреждений; см. документацию Категории предупреждений для получения более подробной информации.
-
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