Встроенные исключения¶
В Python все исключения должны быть экземплярами класса, производного от BaseException
. В операторе try
с предложением except
, в котором упоминается определенный класс, это предложение также обрабатывает любые классы исключений, производные от этого класса (но не классы исключений, от которых он является производным). Два класса исключений, не связанных между собой через подклассы, никогда не будут эквивалентными, даже если у них одинаковое имя.
Встроенные исключения, перечисленные в этой главе, могут быть сгенерированы интерпретатором или встроенными функциями. За исключением упомянутых случаев, они имеют «ассоциированное значение», указывающее на подробную причину ошибки. Это может быть строка или кортеж из нескольких элементов информации (например, код ошибки и строка, поясняющая код). Связанное значение обычно передается в качестве аргумента в конструктор класса исключения.
Пользовательский код может вызывать встроенные исключения. Это можно использовать для проверки обработчика исключений или для сообщения об ошибке, «похожей» на ту, в которой интерпретатор вызывает то же исключение; но следует помнить, что ничто не мешает пользовательскому коду вызвать неподходящую ошибку.
Встроенные классы исключений могут быть подклассами для определения новых исключений; программистам рекомендуется создавать новые исключения на основе класса Exception
или одного из его подклассов, а не на основе BaseException
. Более подробную информацию об определении исключений можно найти в учебнике Python в разделе Определяемые пользователем исключения.
Контекст исключения¶
Три атрибута объектов исключений предоставляют информацию о контексте, в котором было вызвано исключение:
- BaseException.__context__¶
- BaseException.__cause__¶
- BaseException.__suppress_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.В любом случае, само исключение всегда показывается после всех цепочек исключений, так что последняя строка трассировки всегда показывает последнее поднятое исключение.
Наследование от встроенных исключений¶
Пользовательский код может создавать подклассы, наследующие от типа исключения. Рекомендуется создавать подклассы только одного типа исключений одновременно, чтобы избежать возможных конфликтов между тем, как базы обрабатывают атрибут args
, а также из-за возможной несовместимости расположения памяти.
Детали реализации CPython: Большинство встроенных исключений реализовано на языке C для повышения эффективности, см: Objects/exceptions.c. Некоторые из них имеют собственную схему размещения в памяти, что делает невозможным создание подкласса, наследующего от нескольких типов исключений. Разметка памяти типа является деталью реализации и может меняться между версиями Python, что приведет к новым конфликтам в будущем. Поэтому рекомендуется избегать подклассов нескольких типов исключений.
Базовые классы¶
Следующие исключения используются в основном как базовые классы для других исключений.
- exception BaseException¶
Базовый класс для всех встроенных исключений. Он не предназначен для прямого наследования пользовательскими классами (для этого используйте
Exception
). При вызовеstr()
на экземпляре этого класса возвращается представление аргумента(ов) экземпляра, либо пустая строка, если аргументов не было.- args¶
Кортеж аргументов, передаваемых конструктору исключения. Некоторые встроенные исключения (например,
OSError
) ожидают определенного количества аргументов и присваивают элементам этого кортежа особое значение, в то время как другие обычно вызываются только с одной строкой, дающей сообщение об ошибке.
- with_traceback(tb)¶
Этот метод устанавливает tb в качестве нового обратного пути для исключения и возвращает объект исключения. Он чаще всего использовался до того, как стали доступны возможности цепочки исключений PEP 3134. В следующем примере показано, как можно преобразовать экземпляр
SomeException
в экземплярOtherException
, сохранив при этом traceback. После поднятия текущий кадр выталкивается в следOtherException
, как это произошло бы со следом исходногоSomeException
, если бы мы позволили ему распространиться на вызывающего.try: ... except SomeException: tb = sys.exception().__traceback__ raise OtherException(...).with_traceback(tb)
- __traceback__¶
Поле с возможностью записи, в котором хранится traceback object, связанный с данным исключением. См. также: Заявление raise.
- add_note(note)¶
Добавьте строку
note
к примечаниям исключения, которые появляются в стандартной трассировке после строки исключения. Если строкаnote
не является строкой, возникает ошибкаTypeError
.Added in version 3.11.
- __notes__¶
Список примечаний данного исключения, которые были добавлены с помощью
add_note()
. Этот атрибут создается при вызовеadd_note()
.Added in version 3.11.
- exception Exception¶
Все встроенные, не выходящие за пределы системы исключения являются производными от этого класса. Все определяемые пользователем исключения также должны быть производными от этого класса.
- exception ArithmeticError¶
Базовый класс для встроенных исключений, возникающих при различных арифметических ошибках:
OverflowError
,ZeroDivisionError
,FloatingPointError
.
- exception LookupError¶
Базовый класс для исключений, которые возникают, когда ключ или индекс, используемый в отображении или последовательности, недействителен:
IndexError
,KeyError
. Это может быть вызвано непосредственноcodecs.lookup()
.
Бетонные исключения¶
Ниже перечислены исключения, которые обычно возникают.
- 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, которые используются только для ключевых слов, устанавливают соответствующие атрибуты:
- name¶
Имя модуля, который пытались импортировать.
- path¶
Путь к любому файлу, вызвавшему исключение.
- exception ModuleNotFoundError¶
Подкласс
ImportError
, который вызываетсяimport
, когда модуль не может быть найден. Он также вызывается, когдаNone
найден вsys.modules
.Added in version 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¶
Соответствующее сообщение об ошибке, выдаваемое операционной системой. Форматируется функциями языка 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
теперь является исходное имя файла, переданное функции, а не имя, закодированное в filesystem encoding and error handler или декодированное из filesystem encoding and error handler. Также был добавлен аргумент и атрибут конструктора filename2.
- exception OverflowError¶
Возникает, когда результат арифметической операции слишком велик для представления. Это не может произойти для целых чисел (которые скорее поднимут
MemoryError
, чем сдадутся). Однако по историческим причинам OverflowError иногда вызывается для целых чисел, которые выходят за пределы требуемого диапазона. Из-за отсутствия стандартизации обработки исключений в языке C большинство операций с плавающей точкой не проверяется.
- exception PythonFinalizationError¶
Это исключение является производным от
RuntimeError
. Оно возникает, когда операция блокируется во время выключения интерпретатора, также известного как Python finalization.Примеры операций, которые могут быть заблокированы с помощью
PythonFinalizationError
во время финализации Python:Создание нового потока Python.
См. также функцию
sys.is_finalizing()
.Added in version 3.13: Раньше в этом случае появлялся обычный
RuntimeError
.
- exception RecursionError¶
Это исключение является производным от
RuntimeError
. Оно возникает, когда интерпретатор обнаруживает превышение максимальной глубины рекурсии (см.sys.getrecursionlimit()
).Added in version 3.5: Раньше в этом случае появлялся обычный
RuntimeError
.
- exception ReferenceError¶
Это исключение возникает, когда прокси слабой ссылки, созданный функцией
weakref.proxy()
, используется для доступа к атрибуту референта после того, как он был собран в мусор. Дополнительные сведения о слабых ссылках см. в модулеweakref
.
- exception RuntimeError¶
Возникает при обнаружении ошибки, которая не попадает ни в одну из других категорий. Связанное значение - это строка, указывающая, что именно пошло не так.
- exception StopIteration¶
Вызывается встроенной функцией
next()
и методом iterator__next__()
итератора, чтобы сообщить, что больше нет элементов, созданных итератором.- value¶
Объект исключения имеет единственный атрибут
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, чтобы остановить итерацию.Added in version 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¶
Объект, который кодек пытался закодировать или декодировать.
- 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.
Исключения в ОС¶
Следующие исключения являются подклассами OSError
, они вызываются в зависимости от кода системной ошибки.
- exception BlockingIOError¶
Возникает, когда операция блокирует объект (например, сокет), настроенный на неблокирующую работу. Соответствует
errno
EAGAIN
,EALREADY
,EWOULDBLOCK
иEINPROGRESS
.Помимо атрибутов
OSError
,BlockingIOError
может иметь еще один атрибут:
- 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()
) запрашивается для чего-то, что не является каталогом. На большинстве платформ POSIX она также может быть вызвана, если операция пытается открыть или обойти файл, не являющийся каталогом, как если бы он был каталогом. Соответствуетerrno
ENOTDIR
.
- exception PermissionError¶
Возникает при попытке выполнить операцию без соответствующих прав доступа - например, прав доступа к файловой системе. Соответствует
errno
EACCES
,EPERM
иENOTCAPABLE
.Изменено в версии 3.11.1: WASI’s
ENOTCAPABLE
теперь отображается наPermissionError
.
- exception ProcessLookupError¶
Возникает, когда данный процесс не существует. Соответствует
errno
ESRCH
.
- exception TimeoutError¶
Возникает, когда системная функция завершается по таймеру на системном уровне. Соответствует
errno
ETIMEDOUT
.
Added in version 3.3: Были добавлены все перечисленные выше подклассы OSError
.
См.также
PEP 3151 - Переработка иерархии исключений ОС и IO
Предупреждения¶
В качестве категорий предупреждений используются следующие исключения; подробнее см. документацию Предупреждающие категории.
- 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¶
Базовый класс для предупреждений, связанных с кодировками.
Подробности см. в разделе ОптКодированиеПредупреждение.
Added in version 3.10.
- exception ResourceWarning¶
Базовый класс для предупреждений, связанных с использованием ресурсов.
Игнорируется фильтрами предупреждений по умолчанию. Включение Python Development Mode показывает это предупреждение.
Added in version 3.2.
Группы исключений¶
Следующие исключения используются, когда необходимо вызвать несколько несвязанных исключений. Они являются частью иерархии исключений, поэтому их можно обрабатывать с помощью except
, как и все остальные исключения. Кроме того, они распознаются except*
, который сопоставляет их подгруппы на основе типов содержащихся в них исключений.
- exception ExceptionGroup(msg, excs)¶
- exception BaseExceptionGroup(msg, excs)¶
Оба этих типа исключений оборачивают исключения в последовательность
excs
. Параметрmsg
должен быть строкой. Разница между этими двумя классами заключается в том, чтоBaseExceptionGroup
расширяетBaseException
и может обернуть любое исключение, аExceptionGroup
расширяетException
и может обернуть только подклассыException
. Это сделано для того, чтобыexcept Exception
ловилExceptionGroup
, но не ловилBaseExceptionGroup
.Конструктор
BaseExceptionGroup
возвращаетExceptionGroup
, а неBaseExceptionGroup
, если все содержащиеся в нем исключения являются экземплярамиException
, поэтому его можно использовать для автоматического выбора. КонструкторExceptionGroup
, с другой стороны, возвращаетTypeError
, если любое содержащееся в нем исключение не является подклассомException
.- message¶
Аргумент
msg
для конструктора. Это атрибут, доступный только для чтения.
- exceptions¶
Кортеж исключений в последовательности
excs
, переданной конструктору. Этот атрибут доступен только для чтения.
- subgroup(condition)¶
Возвращает группу исключений, содержащую только те исключения из текущей группы, которые соответствуют условию, или
None
, если результат пуст.Условие может быть типом исключения или кортежем типов исключений, в этом случае каждое исключение проверяется на совпадение с помощью той же проверки, которая используется в предложении
except
. Условие также может быть вызываемым объектом (отличным от объекта типа), который принимает исключение в качестве единственного аргумента и возвращает true для исключений, которые должны быть в подгруппе.Структура вложенности текущего исключения сохраняется в результате, как и значения его полей
message
,__traceback__
,__cause__
,__context__
и__notes__
. Пустые вложенные группы исключаются из результата.Условие проверяется для всех исключений во вложенной группе исключений, включая группу верхнего уровня и все вложенные группы исключений. Если условие истинно для такой группы исключений, она включается в результат полностью.
Added in version 3.13:
condition
может быть любым вызываемым объектом, не являющимся объектом типа.
- split(condition)¶
Аналогично
subgroup()
, но возвращает пару(match, rest)
, гдеmatch
- этоsubgroup(condition)
, аrest
- оставшаяся не совпадающая часть.
- derive(excs)¶
Возвращает группу исключений с тем же
message
, но в которую обернуты исключения изexcs
.Этот метод используется
subgroup()
иsplit()
. Подкласс должен переопределить его, чтобыsubgroup()
иsplit()
возвращали экземпляры подкласса, а неExceptionGroup
.subgroup()
иsplit()
копируют поля__traceback__
,__cause__
,__context__
и__notes__
из исходной группы исключений в группу, возвращаемуюderive()
, поэтому эти поля не нужно обновлять с помощьюderive()
.>>> class MyGroup(ExceptionGroup): ... def derive(self, excs): ... return MyGroup(self.message, excs) ... >>> e = MyGroup("eg", [ValueError(1), TypeError(2)]) >>> e.add_note("a note") >>> e.__context__ = Exception("context") >>> e.__cause__ = Exception("cause") >>> try: ... raise e ... except Exception as e: ... exc = e ... >>> match, rest = exc.split(ValueError) >>> exc, exc.__context__, exc.__cause__, exc.__notes__ (MyGroup('eg', [ValueError(1), TypeError(2)]), Exception('context'), Exception('cause'), ['a note']) >>> match, match.__context__, match.__cause__, match.__notes__ (MyGroup('eg', [ValueError(1)]), Exception('context'), Exception('cause'), ['a note']) >>> rest, rest.__context__, rest.__cause__, rest.__notes__ (MyGroup('eg', [TypeError(2)]), Exception('context'), Exception('cause'), ['a note']) >>> exc.__traceback__ is match.__traceback__ is rest.__traceback__ True
Обратите внимание, что
BaseExceptionGroup
определяет__new__()
, поэтому подклассы, которым нужна другая сигнатура конструктора, должны переопределять ее, а не__init__()
. Например, ниже определен подкласс группы исключений, который принимает код exit_code и на его основе строит сообщение группы.class Errors(ExceptionGroup): def __new__(cls, errors, exit_code): self = super().__new__(Errors, f"exit code: {exit_code}", errors) self.exit_code = exit_code return self def derive(self, excs): return Errors(excs, self.exit_code)
Как и
ExceptionGroup
, любой подклассBaseExceptionGroup
, который также является подклассомException
, может обернуть только экземплярыException
.Added in version 3.11.
Иерархия исключений¶
Иерархия классов для встроенных исключений такова:
BaseException
├── BaseExceptionGroup
├── GeneratorExit
├── KeyboardInterrupt
├── SystemExit
└── Exception
├── ArithmeticError
│ ├── FloatingPointError
│ ├── OverflowError
│ └── ZeroDivisionError
├── AssertionError
├── AttributeError
├── BufferError
├── EOFError
├── ExceptionGroup [BaseExceptionGroup]
├── 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
│ ├── PythonFinalizationError
│ └── RecursionError
├── StopAsyncIteration
├── StopIteration
├── SyntaxError
│ └── IncompleteInputError
│ └── IndentationError
│ └── TabError
├── SystemError
├── TypeError
├── ValueError
│ └── UnicodeError
│ ├── UnicodeDecodeError
│ ├── UnicodeEncodeError
│ └── UnicodeTranslateError
└── Warning
├── BytesWarning
├── DeprecationWarning
├── EncodingWarning
├── FutureWarning
├── ImportWarning
├── PendingDeprecationWarning
├── ResourceWarning
├── RuntimeWarning
├── SyntaxWarning
├── UnicodeWarning
└── UserWarning