# 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 place where the error was detected. Note that this is not always the place that needs to be fixed. In the example, the error is detected at the function `print()`, since a colon (`':'`) is missing just before it.

The file name (`<stdin>` in our example) and line number are printed so you know where to look in case the input came from a file.

## 8.2. Винятки

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

    >>> 10 * (1/0)
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
        10 * (1/0)
              ~^~
    ZeroDivisionError: division by zero
    >>> 4 + spam*3
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
        4 + spam*3
            ^^^^
    NameError: name 'spam' is not defined
    >>> '2' + 2
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
        '2' + 2
        ~~~~^~~
    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.

A `try` statement may have more than one except clause, to specify handlers for different exceptions. At most one handler will be executed. Handlers only handle exceptions that occur in the corresponding try clause, not in other handlers of the same `try` statement. An except clause may name multiple exceptions, for example:

    ... 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>
        raise NameError('HiThere')
    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>
        raise NameError('HiThere')
    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>
        open("database.sqlite")
        ~~~~^^^^^^^^^^^^^^^^^^^
    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>
        raise RuntimeError("unable to handle error")
    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>
        func()
        ~~~~^^
      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>
        raise RuntimeError('Failed to open database') from exc
    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>
        raise RuntimeError from None
    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>
        raise KeyboardInterrupt
    KeyboardInterrupt

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

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

- Виняток може статися під час виконання пропозиції `except` або `else`. Знову ж таки, виняток повторно викликається після виконання пункту `finally`.

- If the `finally` clause executes a `break`, `continue` or `return` statement, exceptions are not re-raised. This can be confusing and is therefore discouraged. From version 3.14 the compiler emits a `SyntaxWarning` for it (see PEP 765).

- Якщо оператор `try` досягає оператора `break`, `continue` або `return`, пункт `finally` буде виконано безпосередньо перед `break`, `continue` або `return` виконання оператора.

- If a `finally` clause includes a `return` statement, the returned value will be the one from the `finally` clause’s `return` statement, not the value from the `try` clause’s `return` statement. This can be confusing and is therefore discouraged. From version 3.14 the compiler emits a `SyntaxWarning` for it (see PEP 765).

Наприклад:

    >>> 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>
        divide("2", "1")
        ~~~~~~^^^^^^^^^^
      File "<stdin>", line 3, in divide
        result = x / y
                 ~~^~~
    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>
      |     f()
      |     ~^^
      |   File "<stdin>", line 3, in f
      |     raise ExceptionGroup('there were problems', excs)
      | ExceptionGroup: there were problems (2 sub-exceptions)
      +-+---------------- 1 ----------------
        | OSError: error 1
        +---------------- 2 ----------------
        | SystemError: error 2
        +------------------------------------
    >>> try:
    ...     f()
    ... except Exception as e:
    ...     print(f'caught {type(e)}: {e}')
    ...
    caught <class 'ExceptionGroup'>: there were problems (2 sub-exceptions)
    >>>

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>
      |     f()
      |     ~^^
      |   File "<stdin>", line 2, in f
      |     raise ExceptionGroup(
      |     ...<12 lines>...
      |     )
      | ExceptionGroup: group1 (1 sub-exception)
      +-+---------------- 1 ----------------
        | ExceptionGroup: group2 (1 sub-exception)
        +-+---------------- 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>
        raise TypeError('bad type')
    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>
      |     raise ExceptionGroup('We have some problems', excs)
      | ExceptionGroup: We have some problems (3 sub-exceptions)
      +-+---------------- 1 ----------------
        | Traceback (most recent call last):
        |   File "<stdin>", line 3, in <module>
        |     f()
        |     ~^^
        |   File "<stdin>", line 2, in f
        |     raise OSError('operation failed')
        | OSError: operation failed
        | Happened in Iteration 1
        +---------------- 2 ----------------
        | Traceback (most recent call last):
        |   File "<stdin>", line 3, in <module>
        |     f()
        |     ~^^
        |   File "<stdin>", line 2, in f
        |     raise OSError('operation failed')
        | OSError: operation failed
        | Happened in Iteration 2
        +---------------- 3 ----------------
        | Traceback (most recent call last):
        |   File "<stdin>", line 3, in <module>
        |     f()
        |     ~^^
        |   File "<stdin>", line 2, in f
        |     raise OSError('operation failed')
        | OSError: operation failed
        | Happened in Iteration 3
        +------------------------------------
    >>>