8. Помилки та винятки¶

До цього часу повідомлення про помилки не згадувалися, але якщо ви спробували приклади, ви, ймовірно, бачили деякі. Існує (принаймні) два різновиди помилок: синтаксичні помилки та винятки.

8.1. Синтаксичні помилки¶

Синтаксичні помилки, також відомі як помилки синтаксичного аналізу, є, мабуть, найпоширенішим типом скарг, які ви отримуєте, поки вивчаєте Python:

>>> while True print('Hello world')
  File "<stdin>", line 1
    while True print('Hello world')
               ^^^^^
SyntaxError: invalid syntax

The parser repeats the offending line and displays little arrows pointing at the token in the line where the error was detected. The error may be caused by the absence of a token before the indicated token. In the example, the error is detected at the function print(), since a colon (':') is missing before it. File name and line number are printed so you know where to look in case the input came from a script.

8.2. Винятки¶

Навіть якщо оператор або вираз синтаксично правильний, це може спричинити помилку під час спроби його виконання. Помилки, виявлені під час виконання, називаються винятками і не є безумовно фатальними: незабаром ви дізнаєтесь, як їх обробляти в програмах Python. Однак більшість винятків не обробляються програмами, і вони призводять до повідомлень про помилки, як показано тут:

>>> 10 * (1/0)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ZeroDivisionError: division by zero
>>> 4 + spam*3
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: name 'spam' is not defined
>>> '2' + 2
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: can only concatenate str (not "int") to str

Останній рядок повідомлення про помилку вказує на те, що сталося. Винятки бувають різних типів, і тип друкується як частина повідомлення: типи в прикладі: ZeroDivisionError, NameError і TypeError. Рядок, надрукований як тип винятку, є назвою вбудованого винятку, який стався. Це справедливо для всіх вбудованих винятків, але не обов’язково для винятків, визначених користувачем (хоча це корисна угода). Стандартні назви винятків є вбудованими ідентифікаторами (а не зарезервованими ключовими словами).

Решта рядка надає деталі на основі типу винятку та причини його виникнення.

Попередня частина повідомлення про помилку показує контекст, у якому сталася виняток, у формі зворотного стека. Загалом, він містить зворотне трасування стека зі списком вихідних рядків; однак він не відображатиме рядки, прочитані зі стандартного введення.

Вбудовані винятки містить список вбудованих винятків та їх значення.

8.3. Обробка винятків¶

Можна писати програми, які оброблятимуть вибрані винятки. Подивіться на наступний приклад, який запитує у користувача введення, доки не буде введено дійсне ціле число, але дозволяє користувачеві перервати програму (за допомогою Control-C або іншого, що підтримується операційною системою); зауважте, що створене користувачем переривання сигналізується за допомогою виклику винятку KeyboardInterrupt.

>>> while True:
...     try:
...         x = int(input("Please enter a number: "))
...         break
...     except ValueError:
...         print("Oops!  That was no valid number.  Try again...")
...

Оператор try працює наступним чином.

Спочатку виконується пропозиція try (вираз(и) між ключовими словами try і except).
Якщо винятків не відбувається, пункт except пропускається, і виконання оператора try завершується.
Якщо під час виконання пропозиції try виникає виняток, решта пропозиції пропускається. Тоді, якщо його тип відповідає винятку, названому за ключовим словом except, виконується except, а потім виконання продовжується після блоку try/except.
If an exception occurs which does not match the exception named in the except clause, it is passed on to outer try statements; if no handler is found, it is an unhandled exception and execution stops with an error message.

Оператор try може мати більше ніж одне виключення, щоб вказати обробники для різних винятків. Буде виконано щонайбільше один обробник. Обробники обробляють лише винятки, які виникають у відповідному реченні try, а не в інших обробниках того самого оператора try. Речення except може називати кілька винятків у вигляді кортежу в дужках, наприклад:

... except (RuntimeError, TypeError, NameError):
...     pass

A class in an except clause matches exceptions which are instances of the class itself or one of its derived classes (but not the other way around — an except clause listing a derived class does not match instances of its base classes). For example, the following code will print B, C, D in that order:

class B(Exception):
    pass

class C(B):
    pass

class D(C):
    pass

for cls in [B, C, D]:
    try:
        raise cls()
    except D:
        print("D")
    except C:
        print("C")
    except B:
        print("B")

Зауважте, що якби except пункти були перевернуті (з except B спочатку), було б надруковано B, B, B — спрацьовує перше відповідне except пункт.

When an exception occurs, it may have associated values, also known as the exception’s arguments. The presence and types of the arguments depend on the exception type.

The except clause may specify a variable after the exception name. The variable is bound to the exception instance which typically has an args attribute that stores the arguments. For convenience, builtin exception types define __str__() to print all the arguments without explicitly accessing .args.

>>> try:
...     raise Exception('spam', 'eggs')
... except Exception as inst:
...     print(type(inst))    # the exception type
...     print(inst.args)     # arguments stored in .args
...     print(inst)          # __str__ allows args to be printed directly,
...                          # but may be overridden in exception subclasses
...     x, y = inst.args     # unpack args
...     print('x =', x)
...     print('y =', y)
...
<class 'Exception'>
('spam', 'eggs')
('spam', 'eggs')
x = spam
y = eggs

The exception’s __str__() output is printed as the last part („detail“) of the message for unhandled exceptions.

BaseException is the common base class of all exceptions. One of its subclasses, Exception, is the base class of all the non-fatal exceptions. Exceptions which are not subclasses of Exception are not typically handled, because they are used to indicate that the program should terminate. They include SystemExit which is raised by sys.exit() and KeyboardInterrupt which is raised when a user wishes to interrupt the program.

Exception can be used as a wildcard that catches (almost) everything. However, it is good practice to be as specific as possible with the types of exceptions that we intend to handle, and to allow any unexpected exceptions to propagate on.

The most common pattern for handling Exception is to print or log the exception and then re-raise it (allowing a caller to handle the exception as well):

import sys

try:
    f = open('myfile.txt')
    s = f.readline()
    i = int(s.strip())
except OSError as err:
    print("OS error:", err)
except ValueError:
    print("Could not convert data to an integer.")
except Exception as err:
    print(f"Unexpected {err=}, {type(err)=}")
    raise

Оператор try … except має необов’язкову пропозицію else, яка, якщо є, має слідувати за всіма пропозиціями except. Це корисно для коду, який потрібно виконати, якщо речення try не викликає винятку. Наприклад:

for arg in sys.argv[1:]:
    try:
        f = open(arg, 'r')
    except OSError:
        print('cannot open', arg)
    else:
        print(arg, 'has', len(f.readlines()), 'lines')
        f.close()

Використання пропозиції else краще, ніж додавання додаткового коду до пропозиції try, оскільки це дозволяє уникнути випадкового перехоплення виняткової ситуації, яка не була викликана кодом, захищеним try … except оператор.

Exception 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:

>>> def this_fails():
...     x = 1/0
...
>>> try:
...     this_fails()
... except ZeroDivisionError as err:
...     print('Handling run-time error:', err)
...
Handling run-time error: division by zero

8.4. Створення винятків¶

Оператор raise дозволяє програмісту примусово викликати певний виняток. Наприклад:

>>> raise NameError('HiThere')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: HiThere

The sole argument to raise indicates the exception to be raised. This must be either an exception instance or an exception class (a class that derives from BaseException, such as Exception or one of its subclasses). If an exception class is passed, it will be implicitly instantiated by calling its constructor with no arguments:

raise ValueError  # shorthand for 'raise ValueError()'

Якщо вам потрібно визначити, чи був викликаний виняток, але ви не маєте наміру його обробляти, простіша форма оператора raise дозволяє повторно викликати виняток:

>>> try:
...     raise NameError('HiThere')
... except NameError:
...     print('An exception flew by!')
...     raise
...
An exception flew by!
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
NameError: HiThere

8.5. З’єднання винятків¶

If an unhandled exception occurs inside an except section, it will have the exception being handled attached to it and included in the error message:

>>> try:
...     open("database.sqlite")
... except OSError:
...     raise RuntimeError("unable to handle error")
...
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
FileNotFoundError: [Errno 2] No such file or directory: 'database.sqlite'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "<stdin>", line 4, in <module>
RuntimeError: unable to handle error

To indicate that an exception is a direct consequence of another, the raise statement allows an optional from clause:

# exc must be exception instance or None.
raise RuntimeError from exc

Це може бути корисним, коли ви перетворюєте винятки. Наприклад:

>>> def func():
...     raise ConnectionError
...
>>> try:
...     func()
... except ConnectionError as exc:
...     raise RuntimeError('Failed to open database') from exc
...
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
  File "<stdin>", line 2, in func
ConnectionError

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "<stdin>", line 4, in <module>
RuntimeError: Failed to open database

It also allows disabling automatic exception chaining using the from None idiom:

>>> try:
...     open('database.sqlite')
... except OSError:
...     raise RuntimeError from None
...
Traceback (most recent call last):
  File "<stdin>", line 4, in <module>
RuntimeError

Для отримання додаткової інформації про механіку ланцюжка див. Вбудовані винятки.

8.6. Винятки, визначені користувачем¶

Програми можуть називати свої власні винятки, створюючи новий клас винятків (перегляньте Класи, щоб дізнатися більше про класи Python). Винятки зазвичай мають бути похідними від класу Exception, прямо чи опосередковано.

Можна визначити класи винятків, які роблять усе, що може зробити будь-який інший клас, але зазвичай вони прості, часто пропонують лише ряд атрибутів, які дозволяють обробникам витягувати інформацію про помилку для винятку.

Більшість винятків визначаються іменами, які закінчуються на «Помилка», подібно до назв стандартних винятків.

Many standard modules define their own exceptions to report errors that may occur in functions they define.

8.7. Визначення дій з очищення¶

Інструкція try має інше необов’язкове положення, призначене для визначення дій очищення, які необхідно виконувати за будь-яких обставин. Наприклад:

>>> try:
...     raise KeyboardInterrupt
... finally:
...     print('Goodbye, world!')
...
Goodbye, world!
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
KeyboardInterrupt

Якщо присутня пропозиція finally, пропозиція finally виконуватиметься як останнє завдання перед завершенням інструкції try. Речення finally виконується незалежно від того, створює виняток оператор try чи ні. У наступних пунктах розглядаються більш складні випадки, коли виникає виняток:

Якщо виняток виникає під час виконання пропозиції try, виняток може бути оброблено за допомогою пропозиції except. Якщо виняток не обробляється пропозицією except, виняток виникає повторно після того, як пропозиція finally буде виконана.
Виняток може статися під час виконання пропозиції except або else. Знову ж таки, виняток повторно викликається після виконання пункту finally.
Якщо пропозиція finally виконує оператор break, continue або return, винятки не виникають повторно.
Якщо оператор try досягає оператора break, continue або return, пункт finally буде виконано безпосередньо перед break, continue або return виконання оператора.
Якщо пропозиція finally містить інструкцію return, поверненим значенням буде значення з інструкції return пропозиції finally, а не значення з оператора return пункту try.

Наприклад:

>>> def bool_return():
...     try:
...         return True
...     finally:
...         return False
...
>>> bool_return()
False

Більш складний приклад:

>>> def divide(x, y):
...     try:
...         result = x / y
...     except ZeroDivisionError:
...         print("division by zero!")
...     else:
...         print("result is", result)
...     finally:
...         print("executing finally clause")
...
>>> divide(2, 1)
result is 2.0
executing finally clause
>>> divide(2, 0)
division by zero!
executing finally clause
>>> divide("2", "1")
executing finally clause
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<stdin>", line 3, in divide
TypeError: unsupported operand type(s) for /: 'str' and 'str'

Як бачите, пункт finally виконується в будь-якій події. Помилка TypeError, викликана розділенням двох рядків, не обробляється пропозицією except і тому повторно виникає після виконання пропозиції finally.

У додатках реального світу пункт finally корисний для звільнення зовнішніх ресурсів (таких як файли або мережеві підключення), незалежно від того, чи було використання ресурсу успішним.

8.8. Попередньо визначені дії з очищення¶

Деякі об’єкти визначають стандартні дії з очищення, які необхідно виконати, коли об’єкт більше не потрібний, незалежно від того, чи була операція з використанням об’єкта успішною чи невдалою. Подивіться на наступний приклад, який намагається відкрити файл і вивести його вміст на екран.

for line in open("myfile.txt"):
    print(line, end="")

Проблема з цим кодом полягає в тому, що він залишає файл відкритим протягом невизначеного періоду часу після завершення виконання цієї частини коду. Це не проблема для простих сценаріїв, але може бути проблемою для великих програм. Оператор with дозволяє використовувати такі об’єкти, як файли, таким чином, щоб вони завжди були своєчасно та правильно очищені.

with open("myfile.txt") as f:
    for line in f:
        print(line, end="")

Після виконання виразу файл f завжди закривається, навіть якщо під час обробки рядків виникла проблема. Об’єкти, які, як і файли, забезпечують попередньо визначені дії очищення, вкажуть це у своїй документації.

8.9. Raising and Handling Multiple Unrelated Exceptions¶

There are situations where it is necessary to report several exceptions that have occurred. This is often the case in concurrency frameworks, when several tasks may have failed in parallel, but there are also other use cases where it is desirable to continue execution and collect multiple errors rather than raise the first exception.

The builtin ExceptionGroup wraps a list of exception instances so that they can be raised together. It is an exception itself, so it can be caught like any other exception.

>>> def f():
...     excs = [OSError('error 1'), SystemError('error 2')]
...     raise ExceptionGroup('there were problems', excs)
...
>>> f()
  + Exception Group Traceback (most recent call last):
  |   File "<stdin>", line 1, in <module>
  |   File "<stdin>", line 3, in f
  | ExceptionGroup: there were problems
  +-+---------------- 1 ----------------
    | OSError: error 1
    +---------------- 2 ----------------
    | SystemError: error 2
    +------------------------------------
>>> try:
...     f()
... except Exception as e:
...     print(f'caught {type(e)}: e')
...
caught <class 'ExceptionGroup'>: e
>>>

By using except* instead of except, we can selectively handle only the exceptions in the group that match a certain type. In the following example, which shows a nested exception group, each except* clause extracts from the group exceptions of a certain type while letting all other exceptions propagate to other clauses and eventually to be reraised.

>>> def f():
...     raise ExceptionGroup(
...         "group1",
...         [
...             OSError(1),
...             SystemError(2),
...             ExceptionGroup(
...                 "group2",
...                 [
...                     OSError(3),
...                     RecursionError(4)
...                 ]
...             )
...         ]
...     )
...
>>> try:
...     f()
... except* OSError as e:
...     print("There were OSErrors")
... except* SystemError as e:
...     print("There were SystemErrors")
...
There were OSErrors
There were SystemErrors
  + Exception Group Traceback (most recent call last):
  |   File "<stdin>", line 2, in <module>
  |   File "<stdin>", line 2, in f
  | ExceptionGroup: group1
  +-+---------------- 1 ----------------
    | ExceptionGroup: group2
    +-+---------------- 1 ----------------
      | RecursionError: 4
      +------------------------------------
>>>

Note that the exceptions nested in an exception group must be instances, not types. This is because in practice the exceptions would typically be ones that have already been raised and caught by the program, along the following pattern:

>>> excs = []
... for test in tests:
...     try:
...         test.run()
...     except Exception as e:
...         excs.append(e)
...
>>> if excs:
...    raise ExceptionGroup("Test Failures", excs)
...

8.10. Enriching Exceptions with Notes¶

When an exception is created in order to be raised, it is usually initialized with information that describes the error that has occurred. There are cases where it is useful to add information after the exception was caught. For this purpose, exceptions have a method add_note(note) that accepts a string and adds it to the exception’s notes list. The standard traceback rendering includes all notes, in the order they were added, after the exception.

>>> try:
...     raise TypeError('bad type')
... except Exception as e:
...     e.add_note('Add some information')
...     e.add_note('Add some more information')
...     raise
...
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
TypeError: bad type
Add some information
Add some more information
>>>

For example, when collecting exceptions into an exception group, we may want to add context information for the individual errors. In the following each exception in the group has a note indicating when this error has occurred.

>>> def f():
...     raise OSError('operation failed')
...
>>> excs = []
>>> for i in range(3):
...     try:
...         f()
...     except Exception as e:
...         e.add_note(f'Happened in Iteration {i+1}')
...         excs.append(e)
...
>>> raise ExceptionGroup('We have some problems', excs)
  + Exception Group Traceback (most recent call last):
  |   File "<stdin>", line 1, in <module>
  | ExceptionGroup: We have some problems (3 sub-exceptions)
  +-+---------------- 1 ----------------
    | Traceback (most recent call last):
    |   File "<stdin>", line 3, in <module>
    |   File "<stdin>", line 2, in f
    | OSError: operation failed
    | Happened in Iteration 1
    +---------------- 2 ----------------
    | Traceback (most recent call last):
    |   File "<stdin>", line 3, in <module>
    |   File "<stdin>", line 2, in f
    | OSError: operation failed
    | Happened in Iteration 2
    +---------------- 3 ----------------
    | Traceback (most recent call last):
    |   File "<stdin>", line 3, in <module>
    |   File "<stdin>", line 2, in f
    | OSError: operation failed
    | Happened in Iteration 3
    +------------------------------------
>>>