errors.md
1> **Источник:** https://python-all.ru/3.12/tutorial/errors.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 8. Ошибки и исключения89До сих пор мы лишь упоминали сообщения об ошибках, но если вы пробовали примеры, то, скорее всего, уже с ними сталкивались. Существует (как минимум) два различимых вида ошибок: *синтаксические ошибки* и *исключения*.1011## 8.1. Синтаксические ошибки1213Синтаксические ошибки, также известные как ошибки разбора, – пожалуй, самый распространённый вид неполадок, с которыми вы сталкиваетесь, пока учите Python:1415```python16>>> while True print('Hello world')17 File "<stdin>", line 118 while True print('Hello world')19 ^^^^^20SyntaxError: invalid syntax21```2223Синтаксический анализатор повторяет ошибочную строку и показывает маленькие стрелочки, указывающие на место, где обнаружена ошибка. Заметьте, что это не всегда то место, которое нужно исправить. В примере ошибка обнаружена в районе функции [`print()`](https://python-all.ru/3.12/library/functions.html#print), так как перед ней не хватает двоеточия (`':'`).2425Имя файла (в нашем примере `<stdin>`) и номер строки выводятся, чтобы вы знали, куда смотреть, если входные данные были получены из файла.2627## 8.2. Исключения2829Даже если оператор или выражение синтаксически верны, при попытке его выполнения может возникнуть ошибка. Ошибки, обнаруженные во время выполнения, называются *исключениями* и не являются безусловно фатальными: вы скоро научитесь обрабатывать их в программах на Python. Однако большинство исключений не обрабатываются программами и приводят к сообщениям об ошибках, как показано ниже:3031```python32>>> 10 * (1/0)33Traceback (most recent call last):34 File "<stdin>", line 1, in <module>35ZeroDivisionError: division by zero36>>> 4 + spam*337Traceback (most recent call last):38 File "<stdin>", line 1, in <module>39NameError: name 'spam' is not defined40>>> '2' + 241Traceback (most recent call last):42 File "<stdin>", line 1, in <module>43TypeError: can only concatenate str (not "int") to str44```4546Последняя строка сообщения об ошибке показывает, что произошло. Исключения бывают разных типов, и тип выводится как часть сообщения: в примере это [`ZeroDivisionError`](https://python-all.ru/3.12/library/exceptions.html#ZeroDivisionError), [`NameError`](https://python-all.ru/3.12/library/exceptions.html#NameError) и [`TypeError`](https://python-all.ru/3.12/library/exceptions.html#TypeError). Строка, выводимая как тип исключения, – это имя встроенного исключения, которое произошло. Это верно для всех встроенных исключений, но не обязательно для определяемых пользователем (хотя это полезное соглашение). Стандартные имена исключений – встроенные идентификаторы (не зарезервированные ключевые слова).4748Остальная часть строки содержит подробности в зависимости от типа исключения и того, что его вызвало.4950Предшествующая часть сообщения об ошибке показывает контекст, в котором произошло исключение, в виде трассировки стека. Обычно она содержит трассировку стека с перечислением строк исходного кода; однако строки, прочитанные из стандартного ввода, не отображаются.5152[Встроенные исключения](https://python-all.ru/3.12/library/exceptions.html#bltin-exceptions) содержит список встроенных исключений и их значение.5354## 8.3. Обработка исключений5556Можно писать программы, которые обрабатывают выбранные исключения. Посмотрите на следующий пример, который запрашивает у пользователя ввод до тех пор, пока не будет введено целое число, но при этом позволяет прервать программу (с помощью `Control`-`C` или того, что поддерживает операционная система); обратите внимание, что прерывание, инициированное пользователем, сигнализируется возбуждением исключения [`KeyboardInterrupt`](https://python-all.ru/3.12/library/exceptions.html#KeyboardInterrupt).5758```python59>>> while True:60... try:61... x = int(input("Please enter a number: "))62... break63... except ValueError:64... print("Oops! That was no valid number. Try again...")65...66```6768Инструкция [`try`](https://python-all.ru/3.12/reference/compound_stmts.html#try) работает следующим образом.6970- Сначала выполняется *try-блок* (инструкции между ключевыми словами [`try`](https://python-all.ru/3.12/reference/compound_stmts.html#try) и [`except`](https://python-all.ru/3.12/reference/compound_stmts.html#except)).71- Если исключение не произошло, *except-блок* пропускается, и выполнение инструкции [`try`](https://python-all.ru/3.12/reference/compound_stmts.html#try) завершается.72- Если во время выполнения [`try`](https://python-all.ru/3.12/reference/compound_stmts.html#try)-блока происходит исключение, оставшаяся часть этого блока пропускается. Затем, если его тип совпадает с исключением, указанным после ключевого слова [`except`](https://python-all.ru/3.12/reference/compound_stmts.html#except), выполняется *except-блок*, после чего выполнение продолжается за пределами блока try/except.73- Если происходит исключение, которое не соответствует исключению, указанному в *except-блоке*, оно передаётся внешним инструкциям [`try`](https://python-all.ru/3.12/reference/compound_stmts.html#try); если обработчик не найден, это *необработанное исключение*, и выполнение останавливается с сообщением об ошибке.7475Оператор [`try`](https://python-all.ru/3.12/reference/compound_stmts.html#try) может иметь более одного *блока except* для указания обработчиков разных исключений. Будет выполнен не более одного обработчика. Обработчики обрабатывают только исключения, возникшие в соответствующем *блоке try*, а не в других обработчиках того же оператора `try`. *Блок except* может указывать несколько исключений в виде кортежа в скобках, например:7677```python78... except (RuntimeError, TypeError, NameError):79... pass80```8182Класс в [`except`](https://python-all.ru/3.12/reference/compound_stmts.html#except)-блоке соответствует исключениям, которые являются экземплярами самого этого класса или его производных классов (но не наоборот – *except-блок*, перечисляющий производный класс, не соответствует экземплярам его базовых классов). Например, следующий код выведет B, C, D именно в таком порядке:8384```python85class B(Exception):86 pass8788class C(B):89 pass9091class D(C):92 pass9394for cls in [B, C, D]:95 try:96 raise cls()97 except D:98 print("D")99 except C:100 print("C")101 except B:102 print("B")103```104105Обратите внимание: если бы *except-блоки* были переставлены (`except B` стоял бы первым), то вывелось бы B, B, B – срабатывает первый подходящий *except-блок*.106107Когда возникает исключение, у него могут быть связанные значения, также называемые *аргументами* исключения. Наличие и типы аргументов зависят от типа исключения.108109В *except-блоке* можно указать переменную после имени исключения. Эта переменная привязывается к экземпляру исключения, у которого обычно есть атрибут `args`, хранящий аргументы. Для удобства встроенные типы исключений определяют [`__str__()`](https://python-all.ru/3.12/reference/datamodel.html#object.__str__) так, чтобы выводить все аргументы без явного обращения к `.args`.110111```python112>>> try:113... raise Exception('spam', 'eggs')114... except Exception as inst:115... print(type(inst)) # тип исключения116... print(inst.args) # аргументы, хранящиеся в .args117... print(inst) # __str__ позволяет выводить args напрямую, но может быть переопределён в подклассах исключений118... # но может быть переопределён в подклассах исключений119... x, y = inst.args # распаковать args120... print('x =', x)121... print('y =', y)122...123<class 'Exception'>124('spam', 'eggs')125('spam', 'eggs')126x = spam127y = eggs128```129130Вывод [`__str__()`](https://python-all.ru/3.12/reference/datamodel.html#object.__str__) исключения печатается как последняя часть («подробности») сообщения для необработанных исключений.131132[`BaseException`](https://python-all.ru/3.12/library/exceptions.html#BaseException) – это общий базовый класс всех исключений. Один из его подклассов, [`Exception`](https://python-all.ru/3.12/library/exceptions.html#Exception), является базовым классом для всех нефатальных исключений. Исключения, не являющиеся подклассами [`Exception`](https://python-all.ru/3.12/library/exceptions.html#Exception), обычно не обрабатываются, потому что они используются для указания на то, что программа должна завершиться. К ним относятся [`SystemExit`](https://python-all.ru/3.12/library/exceptions.html#SystemExit), возбуждаемое оператором [`sys.exit()`](https://python-all.ru/3.12/library/sys.html#sys.exit), и [`KeyboardInterrupt`](https://python-all.ru/3.12/library/exceptions.html#KeyboardInterrupt), возбуждаемое, когда пользователь хочет прервать программу.133134[`Exception`](https://python-all.ru/3.12/library/exceptions.html#Exception) можно использовать как универсальный обработчик, который ловит (почти) всё. Однако хорошей практикой является максимальная конкретность в типах исключений, которые мы собираемся обрабатывать, и позволять любым неожиданным исключениям распространяться дальше.135136Наиболее распространённый шаблон обработки [`Exception`](https://python-all.ru/3.12/library/exceptions.html#Exception) – вывести или зарегистрировать исключение, а затем возобновить его снова (позволяя вызывающему коду также обработать исключение):137138```python139import sys140141try:142 f = open('myfile.txt')143 s = f.readline()144 i = int(s.strip())145except OSError as err:146 print("OS error:", err)147except ValueError:148 print("Could not convert data to an integer.")149except Exception as err:150 print(f"Unexpected {err=}, {type(err)=}")151 raise152```153154Инструкция [`try`](https://python-all.ru/3.12/reference/compound_stmts.html#try) … [`except`](https://python-all.ru/3.12/reference/compound_stmts.html#except) имеет необязательный *блок else*, который, если присутствует, должен следовать за всеми *блоками except*. Он полезен для кода, который должен быть выполнен, если *блок try* не возбуждает исключение. Например:155156```python157for arg in sys.argv[1:]:158 try:159 f = open(arg, 'r')160 except OSError:161 print('cannot open', arg)162 else:163 print(arg, 'has', len(f.readlines()), 'lines')164 f.close()165```166167Использование блока `else` лучше, чем добавление дополнительного кода в блок [`try`](https://python-all.ru/3.12/reference/compound_stmts.html#try), поскольку это позволяет избежать случайного перехвата исключения, которое не было возбуждено кодом, защищённым инструкцией `try` … `except`.168169Exception handlers do not handle only exceptions that occur immediately in the *try clause*, but also those that occur inside functions that are called (even indirectly) in the *try clause*. For example:170171```python172>>> def this_fails():173... x = 1/0174...175>>> try:176... this_fails()177... except ZeroDivisionError as err:178... print('Handling run-time error:', err)179...180Handling run-time error: division by zero181```182183## 8.4. Возбуждение исключений184185Инструкция [`raise`](https://python-all.ru/3.12/reference/simple_stmts.html#raise) позволяет программисту принудительно вызвать указанное исключение. Например:186187```python188>>> raise NameError('HiThere')189Traceback (most recent call last):190 File "<stdin>", line 1, in <module>191NameError: HiThere192```193194Единственный аргумент [`raise`](https://python-all.ru/3.12/reference/simple_stmts.html#raise) указывает возбуждаемое исключение. Это должен быть либо экземпляр исключения, либо класс исключения (класс, производный от [`BaseException`](https://python-all.ru/3.12/library/exceptions.html#BaseException), например [`Exception`](https://python-all.ru/3.12/library/exceptions.html#Exception) или один из его подклассов). Если передан класс исключения, он будет неявно создан вызовом его конструктора без аргументов:195196```python197raise ValueError # сокращение для 'raise ValueError()'198```199200Если нужно определить, было ли возбуждено исключение, но обрабатывать его не предполагается, более простая форма инструкции [`raise`](https://python-all.ru/3.12/reference/simple_stmts.html#raise) позволяет повторно возбудить исключение:201202```python203>>> try:204... raise NameError('HiThere')205... except NameError:206... print('An exception flew by!')207... raise208...209An exception flew by!210Traceback (most recent call last):211 File "<stdin>", line 2, in <module>212NameError: HiThere213```214215## 8.5. Цепочка исключений216217Если необработанное исключение возникает внутри раздела [`except`](https://python-all.ru/3.12/reference/compound_stmts.html#except), к нему будет присоединено обрабатываемое исключение, и оно будет включено в сообщение об ошибке:218219```python220>>> try:221... open("database.sqlite")222... except OSError:223... raise RuntimeError("unable to handle error")224...225Traceback (most recent call last):226 File "<stdin>", line 2, in <module>227FileNotFoundError: [Errno 2] No such file or directory: 'database.sqlite'228229During handling of the above exception, another exception occurred:230231Traceback (most recent call last):232 File "<stdin>", line 4, in <module>233RuntimeError: unable to handle error234```235236Чтобы указать, что исключение является прямым следствием другого, инструкция [`raise`](https://python-all.ru/3.12/reference/simple_stmts.html#raise) допускает необязательный блок [`from`](https://python-all.ru/3.12/reference/simple_stmts.html#raise):237238```python239# exc должен быть экземпляром исключения или None.240raise RuntimeError from exc241```242243Это может быть полезно при преобразовании исключений. Например:244245```python246>>> def func():247... raise ConnectionError248...249>>> try:250... func()251... except ConnectionError as exc:252... raise RuntimeError('Failed to open database') from exc253...254Traceback (most recent call last):255 File "<stdin>", line 2, in <module>256 File "<stdin>", line 2, in func257ConnectionError258259The above exception was the direct cause of the following exception:260261Traceback (most recent call last):262 File "<stdin>", line 4, in <module>263RuntimeError: Failed to open database264```265266Он также позволяет отключить автоматическое сцепление исключений с помощью идиомы `from None`:267268```python269>>> try:270... open('database.sqlite')271... except OSError:272... raise RuntimeError from None273...274Traceback (most recent call last):275 File "<stdin>", line 4, in <module>276RuntimeError277```278279Дополнительную информацию о механизме сцепления см. в разделе [Встроенные исключения](https://python-all.ru/3.12/library/exceptions.html#bltin-exceptions).280281## 8.6. Определяемые пользователем исключения282283Программы могут задавать собственные исключения, создавая новый класс исключения (см. [Классы](https://python-all.ru/3.12/tutorial/classes.html#tut-classes) для получения дополнительной информации о классах Python). Исключения обычно должны быть производными от класса [`Exception`](https://python-all.ru/3.12/library/exceptions.html#Exception), прямо или косвенно.284285Классы исключений могут быть определены так, чтобы делать всё, что может любой другой класс, но обычно их оставляют простыми, часто предоставляя лишь несколько атрибутов, позволяющих обработчикам извлекать информацию об ошибке.286287Большинство исключений имеют имена, оканчивающиеся на «Error», подобно именованию стандартных исключений.288289Многие стандартные модули определяют собственные исключения для сообщения об ошибках, которые могут возникнуть в определяемых ими функциях.290291## 8.7. Определение действий по очистке292293Инструкция [`try`](https://python-all.ru/3.12/reference/compound_stmts.html#try) имеет ещё один необязательный блок, предназначенный для определения действий по очистке, которые должны быть выполнены при любых обстоятельствах. Например:294295```python296>>> try:297... raise KeyboardInterrupt298... finally:299... print('Goodbye, world!')300...301Goodbye, world!302Traceback (most recent call last):303 File "<stdin>", line 2, in <module>304KeyboardInterrupt305```306307Если присутствует блок [`finally`](https://python-all.ru/3.12/reference/compound_stmts.html#finally), блок `finally` будет выполнен как последняя задача перед завершением инструкции [`try`](https://python-all.ru/3.12/reference/compound_stmts.html#try). Блок `finally` выполняется независимо от того, вызывает ли инструкция `try` исключение. В следующих пунктах рассматриваются более сложные случаи возникновения исключения:308309- Если исключение возникает во время выполнения блока `try`, оно может быть обработано блоком [`except`](https://python-all.ru/3.12/reference/compound_stmts.html#except). Если исключение не обработано блоком `except`, оно повторно возбуждается после выполнения блока `finally`.310- Исключение может возникнуть во время выполнения блока `except` или `else`. В этом случае исключение также повторно возбуждается после выполнения блока `finally`.311- Если в `finally` блоке выполняется оператор [`break`](https://python-all.ru/3.12/reference/simple_stmts.html#break), [`continue`](https://python-all.ru/3.12/reference/simple_stmts.html#continue) или [`return`](https://python-all.ru/3.12/reference/simple_stmts.html#return), исключения не возбуждаются повторно.312- Если инструкция `try` достигает инструкции [`break`](https://python-all.ru/3.12/reference/simple_stmts.html#break), [`continue`](https://python-all.ru/3.12/reference/simple_stmts.html#continue) или [`return`](https://python-all.ru/3.12/reference/simple_stmts.html#return), блок `finally` выполняется непосредственно перед выполнением инструкции `break`, `continue` или `return`.313- Если в `finally` блоке содержится оператор `return`, возвращаемое значение будет взято из оператора `return` блока `finally`, а не из оператора `return` блока `try`.314315Например:316317```python318>>> def bool_return():319... try:320... return True321... finally:322... return False323...324>>> bool_return()325False326```327328Более сложный пример:329330```python331>>> def divide(x, y):332... try:333... result = x / y334... except ZeroDivisionError:335... print("division by zero!")336... else:337... print("result is", result)338... finally:339... print("executing finally clause")340...341>>> divide(2, 1)342result is 2.0343executing finally clause344>>> divide(2, 0)345division by zero!346executing finally clause347>>> divide("2", "1")348executing finally clause349Traceback (most recent call last):350 File "<stdin>", line 1, in <module>351 File "<stdin>", line 3, in divide352TypeError: unsupported operand type(s) for /: 'str' and 'str'353```354355Как видите, блок [`finally`](https://python-all.ru/3.12/reference/compound_stmts.html#finally) выполняется в любом случае. Исключение [`TypeError`](https://python-all.ru/3.12/library/exceptions.html#TypeError), возбуждённое при делении двух строк, не обрабатывается блоком [`except`](https://python-all.ru/3.12/reference/compound_stmts.html#except) и поэтому повторно возбуждается после выполнения блока `finally`.356357В реальных приложениях блок [`finally`](https://python-all.ru/3.12/reference/compound_stmts.html#finally) полезен для освобождения внешних ресурсов (таких как файлы или сетевые соединения) независимо от того, было ли использование ресурса успешным.358359## 8.8. Предопределённые действия по очистке360361Некоторые объекты определяют стандартные действия по очистке, которые должны быть выполнены, когда объект больше не нужен, независимо от успеха или неудачи операции с этим объектом. Рассмотрим следующий пример, в котором предпринимается попытка открыть файл и вывести его содержимое на экран.362363```python364for line in open("myfile.txt"):365 print(line, end="")366```367368Проблема этого кода в том, что файл остаётся открытым в течение неопределённого времени после завершения выполнения этой части кода. В простых скриптах это не проблема, но может стать проблемой для более крупных приложений. Инструкция [`with`](https://python-all.ru/3.12/reference/compound_stmts.html#with) позволяет использовать такие объекты, как файлы, таким образом, чтобы гарантировать их своевременную и корректную очистку.369370```python371with open("myfile.txt") as f:372 for line in f:373 print(line, end="")374```375376После выполнения инструкции файл *f* всегда закрывается, даже если при обработке строк возникла проблема. Объекты, которые, подобно файлам, предоставляют предопределённые действия по очистке, сообщают об этом в своей документации.377378## 8.9. Возбуждение и обработка нескольких несвязанных исключений379380Бывают ситуации, когда необходимо сообщить о нескольких произошедших исключениях. Это часто встречается во фреймворках параллельного выполнения, когда несколько задач могут завершиться с ошибкой параллельно, но существуют и другие случаи, в которых желательно продолжить выполнение и собрать несколько ошибок, а не возбуждать первое исключение.381382Встроенный [`ExceptionGroup`](https://python-all.ru/3.12/library/exceptions.html#ExceptionGroup) оборачивает список экземпляров исключений, чтобы их можно было возбудить вместе. Сам он является исключением, поэтому его можно перехватить, как любое другое исключение.383384```python385>>> def f():386... excs = [OSError('error 1'), SystemError('error 2')]387... raise ExceptionGroup('there were problems', excs)388...389>>> f()390 + Exception Group Traceback (most recent call last):391 | File "<stdin>", line 1, in <module>392 | File "<stdin>", line 3, in f393 | ExceptionGroup: there were problems394 +-+---------------- 1 ----------------395 | OSError: error 1396 +---------------- 2 ----------------397 | SystemError: error 2398 +------------------------------------399>>> try:400... f()401... except Exception as e:402... print(f'caught {type(e)}: e')403...404caught <class 'ExceptionGroup'>: e405>>>406```407408Используя `except*` вместо `except`, можно выборочно обрабатывать только те исключения в группе, которые соответствуют определённому типу. В следующем примере, демонстрирующем вложенную группу исключений, каждое предложение `except*` извлекает из группы исключения определённого типа, позволяя всем остальным исключениям распространяться к другим предложениям и в конечном итоге быть возбуждёнными снова.409410```python411>>> def f():412... raise ExceptionGroup(413... "group1",414... [415... OSError(1),416... SystemError(2),417... ExceptionGroup(418... "group2",419... [420... OSError(3),421... RecursionError(4)422... ]423... )424... ]425... )426...427>>> try:428... f()429... except* OSError as e:430... print("There were OSErrors")431... except* SystemError as e:432... print("There were SystemErrors")433...434There were OSErrors435There were SystemErrors436 + Exception Group Traceback (most recent call last):437 | File "<stdin>", line 2, in <module>438 | File "<stdin>", line 2, in f439 | ExceptionGroup: group1440 +-+---------------- 1 ----------------441 | ExceptionGroup: group2442 +-+---------------- 1 ----------------443 | RecursionError: 4444 +------------------------------------445>>>446```447448Обратите внимание, что исключения, вложенные в группу исключений, должны быть экземплярами, а не типами. Это связано с тем, что на практике исключения обычно уже возбуждены и перехвачены программой по следующему шаблону:449450```python451>>> excs = []452... for test in tests:453... try:454... test.run()455... except Exception as e:456... excs.append(e)457...458>>> if excs:459... raise ExceptionGroup("Test Failures", excs)460...461```462463## 8.10. Обогащение исключений заметками464465Когда исключение создаётся для возбуждения, оно обычно инициализируется информацией, описывающей произошедшую ошибку. Бывают случаи, когда полезно добавить информацию после перехвата исключения. Для этого у исключений есть метод `add_note(note)`, который принимает строку и добавляет её в список заметок исключения. Стандартный вывод трассировки включает все заметки в порядке их добавления после исключения.466467```python468>>> try:469... raise TypeError('bad type')470... except Exception as e:471... e.add_note('Add some information')472... e.add_note('Add some more information')473... raise474...475Traceback (most recent call last):476 File "<stdin>", line 2, in <module>477TypeError: bad type478Add some information479Add some more information480>>>481```482483Например, при сборе исключений в группу исключений может потребоваться добавить контекстную информацию для каждой отдельной ошибки. В следующем примере каждое исключение в группе содержит заметку, указывающую, когда произошла эта ошибка.484485```python486>>> def f():487... raise OSError('operation failed')488...489>>> excs = []490>>> for i in range(3):491... try:492... f()493... except Exception as e:494... e.add_note(f'Happened in Iteration {i+1}')495... excs.append(e)496...497>>> raise ExceptionGroup('We have some problems', excs)498 + Exception Group Traceback (most recent call last):499 | File "<stdin>", line 1, in <module>500 | ExceptionGroup: We have some problems (3 sub-exceptions)501 +-+---------------- 1 ----------------502 | Traceback (most recent call last):503 | File "<stdin>", line 3, in <module>504 | File "<stdin>", line 2, in f505 | OSError: operation failed506 | Happened in Iteration 1507 +---------------- 2 ----------------508 | Traceback (most recent call last):509 | File "<stdin>", line 3, in <module>510 | File "<stdin>", line 2, in f511 | OSError: operation failed512 | Happened in Iteration 2513 +---------------- 3 ----------------514 | Traceback (most recent call last):515 | File "<stdin>", line 3, in <module>516 | File "<stdin>", line 2, in f517 | OSError: operation failed518 | Happened in Iteration 3519 +------------------------------------520>>>521```522