errors.md
1> **Источник:** https://python-all.ru/3.11/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.11/library/functions.html#print), поскольку перед ней отсутствует двоеточие (`':'`). Имя файла и номер строки выводятся, чтобы было понятно, где искать, если ввод поступил из скрипта.2425## 8.2. Исключения2627Даже если оператор или выражение синтаксически верны, при попытке его выполнения может возникнуть ошибка. Ошибки, обнаруженные во время выполнения, называются *исключениями* и не являются безусловно фатальными: вы скоро научитесь обрабатывать их в программах на Python. Однако большинство исключений не обрабатываются программами и приводят к сообщениям об ошибках, как показано ниже:2829```python30>>> 10 * (1/0)31Traceback (most recent call last):32 File "<stdin>", line 1, in <module>33ZeroDivisionError: division by zero34>>> 4 + spam*335Traceback (most recent call last):36 File "<stdin>", line 1, in <module>37NameError: name 'spam' is not defined38>>> '2' + 239Traceback (most recent call last):40 File "<stdin>", line 1, in <module>41TypeError: can only concatenate str (not "int") to str42```4344Последняя строка сообщения об ошибке показывает, что произошло. Исключения бывают разных типов, и тип выводится как часть сообщения: в примере это [`ZeroDivisionError`](https://python-all.ru/3.11/library/exceptions.html#ZeroDivisionError), [`NameError`](https://python-all.ru/3.11/library/exceptions.html#NameError) и [`TypeError`](https://python-all.ru/3.11/library/exceptions.html#TypeError). Строка, выводимая как тип исключения, – это имя встроенного исключения, которое произошло. Это верно для всех встроенных исключений, но не обязательно для определяемых пользователем (хотя это полезное соглашение). Стандартные имена исключений – встроенные идентификаторы (не зарезервированные ключевые слова).4546Остальная часть строки содержит подробности в зависимости от типа исключения и того, что его вызвало.4748Предшествующая часть сообщения об ошибке показывает контекст, в котором произошло исключение, в виде трассировки стека. Обычно она содержит трассировку стека с перечислением строк исходного кода; однако строки, прочитанные из стандартного ввода, не отображаются.4950[Встроенные исключения](https://python-all.ru/3.11/library/exceptions.html#bltin-exceptions) содержит список встроенных исключений и их значение.5152## 8.3. Обработка исключений5354Можно писать программы, обрабатывающие выбранные исключения. В следующем примере показан запрос ввода у пользователя до тех пор, пока не будет введено целое число, но при этом пользователь может прервать программу (с помощью `Control-C` или того, что поддерживает операционная система); обратите внимание, что прерывание пользователем вызывает исключение [`KeyboardInterrupt`](https://python-all.ru/3.11/library/exceptions.html#KeyboardInterrupt).5556```python57>>> while True:58... try:59... x = int(input("Please enter a number: "))60... break61... except ValueError:62... print("Oops! That was no valid number. Try again...")63...64```6566Инструкция [`try`](https://python-all.ru/3.11/reference/compound_stmts.html#try) работает следующим образом.6768- Сначала выполняется *try-блок* (инструкции между ключевыми словами [`try`](https://python-all.ru/3.11/reference/compound_stmts.html#try) и [`except`](https://python-all.ru/3.11/reference/compound_stmts.html#except)).69- Если исключение не произошло, *except-блок* пропускается, и выполнение инструкции [`try`](https://python-all.ru/3.11/reference/compound_stmts.html#try) завершается.70- Если во время выполнения [`try`](https://python-all.ru/3.11/reference/compound_stmts.html#try)-блока происходит исключение, оставшаяся часть этого блока пропускается. Затем, если его тип совпадает с исключением, указанным после ключевого слова [`except`](https://python-all.ru/3.11/reference/compound_stmts.html#except), выполняется *except-блок*, после чего выполнение продолжается за пределами блока try/except.71- Если происходит исключение, которое не соответствует исключению, указанному в *except-блоке*, оно передаётся внешним инструкциям [`try`](https://python-all.ru/3.11/reference/compound_stmts.html#try); если обработчик не найден, это *необработанное исключение*, и выполнение останавливается с сообщением об ошибке.7273Оператор [`try`](https://python-all.ru/3.11/reference/compound_stmts.html#try) может иметь более одного *блока except* для указания обработчиков разных исключений. Будет выполнен не более одного обработчика. Обработчики обрабатывают только исключения, возникшие в соответствующем *блоке try*, а не в других обработчиках того же оператора `try`. *Блок except* может указывать несколько исключений в виде кортежа в скобках, например:7475```python76... except (RuntimeError, TypeError, NameError):77... pass78```7980Класс в предложении [`except`](https://python-all.ru/3.11/reference/compound_stmts.html#except) совместим с исключением, если это тот же класс или его базовый класс (но не наоборот – *предложение except*, перечисляющее производный класс, несовместимо с базовым классом). Например, следующий код выведет B, C, D в таком порядке:8182```python83class B(Exception):84 pass8586class C(B):87 pass8889class D(C):90 pass9192for cls in [B, C, D]:93 try:94 raise cls()95 except D:96 print("D")97 except C:98 print("C")99 except B:100 print("B")101```102103Обратите внимание: если бы *except-блоки* были переставлены (`except B` стоял бы первым), то вывелось бы B, B, B – срабатывает первый подходящий *except-блок*.104105Когда возникает исключение, у него могут быть связанные значения, также называемые *аргументами* исключения. Наличие и типы аргументов зависят от типа исключения.106107В *except-блоке* можно указать переменную после имени исключения. Эта переменная привязывается к экземпляру исключения, у которого обычно есть атрибут `args`, хранящий аргументы. Для удобства встроенные типы исключений определяют [`__str__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__str__) так, чтобы выводить все аргументы без явного обращения к `.args`.108109```python110>>> try:111... raise Exception('spam', 'eggs')112... except Exception as inst:113... print(type(inst)) # тип исключения114... print(inst.args) # аргументы, хранящиеся в .args115... print(inst) # __str__ позволяет выводить args напрямую, но может быть переопределён в подклассах исключений116... # но может быть переопределён в подклассах исключений117... x, y = inst.args # распаковать args118... print('x =', x)119... print('y =', y)120...121<class 'Exception'>122('spam', 'eggs')123('spam', 'eggs')124x = spam125y = eggs126```127128Вывод [`__str__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__str__) исключения печатается как последняя часть («подробности») сообщения для необработанных исключений.129130[`BaseException`](https://python-all.ru/3.11/library/exceptions.html#BaseException) – это общий базовый класс всех исключений. Один из его подклассов, [`Exception`](https://python-all.ru/3.11/library/exceptions.html#Exception), является базовым классом для всех нефатальных исключений. Исключения, не являющиеся подклассами [`Exception`](https://python-all.ru/3.11/library/exceptions.html#Exception), обычно не обрабатываются, потому что они используются для указания на то, что программа должна завершиться. К ним относятся [`SystemExit`](https://python-all.ru/3.11/library/exceptions.html#SystemExit), возбуждаемое оператором [`sys.exit()`](https://python-all.ru/3.11/library/sys.html#sys.exit), и [`KeyboardInterrupt`](https://python-all.ru/3.11/library/exceptions.html#KeyboardInterrupt), возбуждаемое, когда пользователь хочет прервать программу.131132[`Exception`](https://python-all.ru/3.11/library/exceptions.html#Exception) можно использовать как универсальный обработчик, который ловит (почти) всё. Однако хорошей практикой является максимальная конкретность в типах исключений, которые мы собираемся обрабатывать, и позволять любым неожиданным исключениям распространяться дальше.133134Наиболее распространённый шаблон обработки [`Exception`](https://python-all.ru/3.11/library/exceptions.html#Exception) – вывести или зарегистрировать исключение, а затем возобновить его снова (позволяя вызывающему коду также обработать исключение):135136```python137import sys138139try:140 f = open('myfile.txt')141 s = f.readline()142 i = int(s.strip())143except OSError as err:144 print("OS error:", err)145except ValueError:146 print("Could not convert data to an integer.")147except Exception as err:148 print(f"Unexpected {err=}, {type(err)=}")149 raise150```151152Инструкция [`try`](https://python-all.ru/3.11/reference/compound_stmts.html#try) … [`except`](https://python-all.ru/3.11/reference/compound_stmts.html#except) имеет необязательный *блок else*, который, если присутствует, должен следовать за всеми *блоками except*. Он полезен для кода, который должен быть выполнен, если *блок try* не возбуждает исключение. Например:153154```python155for arg in sys.argv[1:]:156 try:157 f = open(arg, 'r')158 except OSError:159 print('cannot open', arg)160 else:161 print(arg, 'has', len(f.readlines()), 'lines')162 f.close()163```164165Использование блока `else` лучше, чем добавление дополнительного кода в блок [`try`](https://python-all.ru/3.11/reference/compound_stmts.html#try), поскольку это позволяет избежать случайного перехвата исключения, которое не было возбуждено кодом, защищённым инструкцией `try` … `except`.166167Exception 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:168169```python170>>> def this_fails():171... x = 1/0172...173>>> try:174... this_fails()175... except ZeroDivisionError as err:176... print('Handling run-time error:', err)177...178Handling run-time error: division by zero179```180181## 8.4. Возбуждение исключений182183Инструкция [`raise`](https://python-all.ru/3.11/reference/simple_stmts.html#raise) позволяет программисту принудительно вызвать указанное исключение. Например:184185```python186>>> raise NameError('HiThere')187Traceback (most recent call last):188 File "<stdin>", line 1, in <module>189NameError: HiThere190```191192Единственный аргумент [`raise`](https://python-all.ru/3.11/reference/simple_stmts.html#raise) указывает возбуждаемое исключение. Это должен быть либо экземпляр исключения, либо класс исключения (класс, производный от [`BaseException`](https://python-all.ru/3.11/library/exceptions.html#BaseException), например [`Exception`](https://python-all.ru/3.11/library/exceptions.html#Exception) или один из его подклассов). Если передан класс исключения, он будет неявно создан вызовом его конструктора без аргументов:193194```python195raise ValueError # сокращение для 'raise ValueError()'196```197198Если нужно определить, было ли возбуждено исключение, но обрабатывать его не предполагается, более простая форма инструкции [`raise`](https://python-all.ru/3.11/reference/simple_stmts.html#raise) позволяет повторно возбудить исключение:199200```python201>>> try:202... raise NameError('HiThere')203... except NameError:204... print('An exception flew by!')205... raise206...207An exception flew by!208Traceback (most recent call last):209 File "<stdin>", line 2, in <module>210NameError: HiThere211```212213## 8.5. Цепочка исключений214215Если необработанное исключение возникает внутри раздела [`except`](https://python-all.ru/3.11/reference/compound_stmts.html#except), к нему будет присоединено обрабатываемое исключение, и оно будет включено в сообщение об ошибке:216217```python218>>> try:219... open("database.sqlite")220... except OSError:221... raise RuntimeError("unable to handle error")222...223Traceback (most recent call last):224 File "<stdin>", line 2, in <module>225FileNotFoundError: [Errno 2] No such file or directory: 'database.sqlite'226227During handling of the above exception, another exception occurred:228229Traceback (most recent call last):230 File "<stdin>", line 4, in <module>231RuntimeError: unable to handle error232```233234Чтобы указать, что исключение является прямым следствием другого, инструкция [`raise`](https://python-all.ru/3.11/reference/simple_stmts.html#raise) допускает необязательный блок [`from`](https://python-all.ru/3.11/reference/simple_stmts.html#raise):235236```python237# exc должен быть экземпляром исключения или None.238raise RuntimeError from exc239```240241Это может быть полезно при преобразовании исключений. Например:242243```python244>>> def func():245... raise ConnectionError246...247>>> try:248... func()249... except ConnectionError as exc:250... raise RuntimeError('Failed to open database') from exc251...252Traceback (most recent call last):253 File "<stdin>", line 2, in <module>254 File "<stdin>", line 2, in func255ConnectionError256257The above exception was the direct cause of the following exception:258259Traceback (most recent call last):260 File "<stdin>", line 4, in <module>261RuntimeError: Failed to open database262```263264Он также позволяет отключить автоматическое сцепление исключений с помощью идиомы `from None`:265266```python267>>> try:268... open('database.sqlite')269... except OSError:270... raise RuntimeError from None271...272Traceback (most recent call last):273 File "<stdin>", line 4, in <module>274RuntimeError275```276277Дополнительную информацию о механизме сцепления см. в разделе [Встроенные исключения](https://python-all.ru/3.11/library/exceptions.html#bltin-exceptions).278279## 8.6. Определяемые пользователем исключения280281Программы могут задавать собственные исключения, создавая новый класс исключения (см. [Классы](https://python-all.ru/3.11/tutorial/classes.html#tut-classes) для получения дополнительной информации о классах Python). Исключения обычно должны быть производными от класса [`Exception`](https://python-all.ru/3.11/library/exceptions.html#Exception), прямо или косвенно.282283Классы исключений могут быть определены так, чтобы делать всё, что может любой другой класс, но обычно их оставляют простыми, часто предоставляя лишь несколько атрибутов, позволяющих обработчикам извлекать информацию об ошибке.284285Большинство исключений имеют имена, оканчивающиеся на «Error», подобно именованию стандартных исключений.286287Многие стандартные модули определяют собственные исключения для сообщения об ошибках, которые могут возникнуть в определяемых ими функциях.288289## 8.7. Определение действий по очистке290291Инструкция [`try`](https://python-all.ru/3.11/reference/compound_stmts.html#try) имеет ещё один необязательный блок, предназначенный для определения действий по очистке, которые должны быть выполнены при любых обстоятельствах. Например:292293```python294>>> try:295... raise KeyboardInterrupt296... finally:297... print('Goodbye, world!')298...299Goodbye, world!300Traceback (most recent call last):301 File "<stdin>", line 2, in <module>302KeyboardInterrupt303```304305Если присутствует блок [`finally`](https://python-all.ru/3.11/reference/compound_stmts.html#finally), блок `finally` будет выполнен как последняя задача перед завершением инструкции [`try`](https://python-all.ru/3.11/reference/compound_stmts.html#try). Блок `finally` выполняется независимо от того, вызывает ли инструкция `try` исключение. В следующих пунктах рассматриваются более сложные случаи возникновения исключения:306307- Если исключение возникает во время выполнения блока `try`, оно может быть обработано блоком [`except`](https://python-all.ru/3.11/reference/compound_stmts.html#except). Если исключение не обработано блоком `except`, оно повторно возбуждается после выполнения блока `finally`.308- Исключение может возникнуть во время выполнения блока `except` или `else`. В этом случае исключение также повторно возбуждается после выполнения блока `finally`.309- Если в `finally` блоке выполняется оператор [`break`](https://python-all.ru/3.11/reference/simple_stmts.html#break), [`continue`](https://python-all.ru/3.11/reference/simple_stmts.html#continue) или [`return`](https://python-all.ru/3.11/reference/simple_stmts.html#return), исключения не возбуждаются повторно.310- Если инструкция `try` достигает инструкции [`break`](https://python-all.ru/3.11/reference/simple_stmts.html#break), [`continue`](https://python-all.ru/3.11/reference/simple_stmts.html#continue) или [`return`](https://python-all.ru/3.11/reference/simple_stmts.html#return), блок `finally` выполняется непосредственно перед выполнением инструкции `break`, `continue` или `return`.311- Если в `finally` блоке содержится оператор `return`, возвращаемое значение будет взято из оператора `return` блока `finally`, а не из оператора `return` блока `try`.312313Например:314315```python316>>> def bool_return():317... try:318... return True319... finally:320... return False321...322>>> bool_return()323False324```325326Более сложный пример:327328```python329>>> def divide(x, y):330... try:331... result = x / y332... except ZeroDivisionError:333... print("division by zero!")334... else:335... print("result is", result)336... finally:337... print("executing finally clause")338...339>>> divide(2, 1)340result is 2.0341executing finally clause342>>> divide(2, 0)343division by zero!344executing finally clause345>>> divide("2", "1")346executing finally clause347Traceback (most recent call last):348 File "<stdin>", line 1, in <module>349 File "<stdin>", line 3, in divide350TypeError: unsupported operand type(s) for /: 'str' and 'str'351```352353Как видите, блок [`finally`](https://python-all.ru/3.11/reference/compound_stmts.html#finally) выполняется в любом случае. Исключение [`TypeError`](https://python-all.ru/3.11/library/exceptions.html#TypeError), возбуждённое при делении двух строк, не обрабатывается блоком [`except`](https://python-all.ru/3.11/reference/compound_stmts.html#except) и поэтому повторно возбуждается после выполнения блока `finally`.354355В реальных приложениях блок [`finally`](https://python-all.ru/3.11/reference/compound_stmts.html#finally) полезен для освобождения внешних ресурсов (таких как файлы или сетевые соединения) независимо от того, было ли использование ресурса успешным.356357## 8.8. Предопределённые действия по очистке358359Некоторые объекты определяют стандартные действия по очистке, которые должны быть выполнены, когда объект больше не нужен, независимо от успеха или неудачи операции с этим объектом. Рассмотрим следующий пример, в котором предпринимается попытка открыть файл и вывести его содержимое на экран.360361```python362for line in open("myfile.txt"):363 print(line, end="")364```365366Проблема этого кода в том, что файл остаётся открытым в течение неопределённого времени после завершения выполнения этой части кода. В простых скриптах это не проблема, но может стать проблемой для более крупных приложений. Инструкция [`with`](https://python-all.ru/3.11/reference/compound_stmts.html#with) позволяет использовать такие объекты, как файлы, таким образом, чтобы гарантировать их своевременную и корректную очистку.367368```python369with open("myfile.txt") as f:370 for line in f:371 print(line, end="")372```373374После выполнения инструкции файл *f* всегда закрывается, даже если при обработке строк возникла проблема. Объекты, которые, подобно файлам, предоставляют предопределённые действия по очистке, сообщают об этом в своей документации.375376## 8.9. Возбуждение и обработка нескольких несвязанных исключений377378Бывают ситуации, когда необходимо сообщить о нескольких произошедших исключениях. Это часто встречается во фреймворках параллельного выполнения, когда несколько задач могут завершиться с ошибкой параллельно, но существуют и другие случаи, в которых желательно продолжить выполнение и собрать несколько ошибок, а не возбуждать первое исключение.379380Встроенный [`ExceptionGroup`](https://python-all.ru/3.11/library/exceptions.html#ExceptionGroup) оборачивает список экземпляров исключений, чтобы их можно было возбудить вместе. Сам он является исключением, поэтому его можно перехватить, как любое другое исключение.381382```python383>>> def f():384... excs = [OSError('error 1'), SystemError('error 2')]385... raise ExceptionGroup('there were problems', excs)386...387>>> f()388 + Exception Group Traceback (most recent call last):389 | File "<stdin>", line 1, in <module>390 | File "<stdin>", line 3, in f391 | ExceptionGroup: there were problems392 +-+---------------- 1 ----------------393 | OSError: error 1394 +---------------- 2 ----------------395 | SystemError: error 2396 +------------------------------------397>>> try:398... f()399... except Exception as e:400... print(f'caught {type(e)}: e')401...402caught <class 'ExceptionGroup'>: e403>>>404```405406Используя `except*` вместо `except`, можно выборочно обрабатывать только те исключения в группе, которые соответствуют определённому типу. В следующем примере, демонстрирующем вложенную группу исключений, каждое предложение `except*` извлекает из группы исключения определённого типа, позволяя всем остальным исключениям распространяться к другим предложениям и в конечном итоге быть возбуждёнными снова.407408```python409>>> def f():410... raise ExceptionGroup(411... "group1",412... [413... OSError(1),414... SystemError(2),415... ExceptionGroup(416... "group2",417... [418... OSError(3),419... RecursionError(4)420... ]421... )422... ]423... )424...425>>> try:426... f()427... except* OSError as e:428... print("There were OSErrors")429... except* SystemError as e:430... print("There were SystemErrors")431...432There were OSErrors433There were SystemErrors434 + Exception Group Traceback (most recent call last):435 | File "<stdin>", line 2, in <module>436 | File "<stdin>", line 2, in f437 | ExceptionGroup: group1438 +-+---------------- 1 ----------------439 | ExceptionGroup: group2440 +-+---------------- 1 ----------------441 | RecursionError: 4442 +------------------------------------443>>>444```445446Обратите внимание, что исключения, вложенные в группу исключений, должны быть экземплярами, а не типами. Это связано с тем, что на практике исключения обычно уже возбуждены и перехвачены программой по следующему шаблону:447448```python449>>> excs = []450... for test in tests:451... try:452... test.run()453... except Exception as e:454... excs.append(e)455...456>>> if excs:457... raise ExceptionGroup("Test Failures", excs)458...459```460461## 8.10. Обогащение исключений заметками462463Когда исключение создаётся для возбуждения, оно обычно инициализируется информацией, описывающей произошедшую ошибку. Бывают случаи, когда полезно добавить информацию после перехвата исключения. Для этого у исключений есть метод `add_note(note)`, который принимает строку и добавляет её в список заметок исключения. Стандартный вывод трассировки включает все заметки в порядке их добавления после исключения.464465```python466>>> try:467... raise TypeError('bad type')468... except Exception as e:469... e.add_note('Add some information')470... e.add_note('Add some more information')471... raise472...473Traceback (most recent call last):474 File "<stdin>", line 2, in <module>475TypeError: bad type476Add some information477Add some more information478>>>479```480481Например, при сборе исключений в группу исключений может потребоваться добавить контекстную информацию для каждой отдельной ошибки. В следующем примере каждое исключение в группе содержит заметку, указывающую, когда произошла эта ошибка.482483```python484>>> def f():485... raise OSError('operation failed')486...487>>> excs = []488>>> for i in range(3):489... try:490... f()491... except Exception as e:492... e.add_note(f'Happened in Iteration {i+1}')493... excs.append(e)494...495>>> raise ExceptionGroup('We have some problems', excs)496 + Exception Group Traceback (most recent call last):497 | File "<stdin>", line 1, in <module>498 | ExceptionGroup: We have some problems (3 sub-exceptions)499 +-+---------------- 1 ----------------500 | Traceback (most recent call last):501 | File "<stdin>", line 3, in <module>502 | File "<stdin>", line 2, in f503 | OSError: operation failed504 | Happened in Iteration 1505 +---------------- 2 ----------------506 | Traceback (most recent call last):507 | File "<stdin>", line 3, in <module>508 | File "<stdin>", line 2, in f509 | OSError: operation failed510 | Happened in Iteration 2511 +---------------- 3 ----------------512 | Traceback (most recent call last):513 | File "<stdin>", line 3, in <module>514 | File "<stdin>", line 2, in f515 | OSError: operation failed516 | Happened in Iteration 3517 +------------------------------------518>>>519```520