Свои исключения в Python: класс от Exception

Седьмой урок научил нарушать правила через raise ValueError. У встроенного ValueError есть слабость: он говорит «значение не подошло», но не говорит, какое правило нарушено. В логе с десятью ValueError не разберёшься, что именно пошло не так: не хватило денег, не тот формат заказа или цена вышла за потолок. Для своих правил Python позволяет завести свои исключения — классы с внятными именами, которые попадают в traceback и читаются как заголовки событий.

Первое своё исключение: имя, которое читается

Минимальное своё исключение — класс от Exception с телом из одной строки. Имя класса придумываете вы, и это имя видно всем, кто читает traceback:

class InsufficientFundsError(Exception):
    """На счёте недостаточно денег для операции."""

balance = 100
withdraw = 250

if withdraw > balance:
    raise InsufficientFundsError(f'нужно {withdraw}, на счёте {balance}')

Последняя строка traceback читается как заголовок в журнале: тип ошибки — имя вашего класса, далее — сообщение, которое вы передали в скобках. Строка в теле класса — docstring, она объясняет смысл исключения тем, кто будет читать ваш код через полгода. Никаких других методов для минимального варианта не нужно.

Ловим своё как любое другое

Своё исключение — полноправный член системы: бросается обычным raise, ловится обычным except, а сообщение читается через as e:

class InsufficientFundsError(Exception):
    pass

def withdraw(balance, amount):
    if amount > balance:
        raise InsufficientFundsError(f'нужно {amount}, на счёте {balance}')
    return balance - amount

try:
    withdraw(100, 250)
except InsufficientFundsError as e:
    print('операция отменена:', str(e))

операция отменена: нужно 250, на счёте 100

Ловится строго по имени: ветка except InsufficientFundsError сработает только на ваше исключение, и случайный ValueError из другого места кода в неё не попадёт. Побочный бонус такой точности: имя класса — это документация. Читая заголовок функции, видно, какие правила она может нарушить.

Исключение — это обычный класс, и в нём можно хранить данные о случившемся: номер заказа, имя файла, саму причину. Для этого переопределяют __init__, не забывая позвать родительский через super():

class PaymentError(Exception):
    def __init__(self, order_id, reason):
        super().__init__(reason)
        self.order_id = order_id
        self.reason = reason

try:
    raise PaymentError('ORD-7', 'карта отклонена')
except PaymentError as e:
    print('заказ', e.order_id, '-', e.reason)

заказ ORD-7 - карта отклонена

Вызывающий код теперь отвечает на вопрос «что с заказом?» без разбора строк: атрибуты order_id и reason лежат в объекте ошибки. Сообщение в super().__init__(reason) идёт в стандартное поле, откуда его читает str(e) — и traceback, и журналы показывают осмысленный текст.

Семейство своих исключений

Когда своих ошибок становится несколько, они начинают жить по тем же законам, что и встроенные в девятом уроке об иерархии: заведи общего предка и наследуй остальных от него.

class ShopError(Exception):
    """Общая ошибка магазина."""

class PaymentError(ShopError):
    pass

class DeliveryError(ShopError):
    pass

def process(order):
    raise DeliveryError('курьер недоступен')

try:
    process('ORD-1')
except ShopError as e:
    print('магазин сообщил:', type(e).__name__, '-', str(e))

магазин сообщил: DeliveryError - курьер недоступен

class ShopError(Exception):
    pass

class PaymentError(ShopError):
    pass

print('PaymentError - потомок ShopError:', issubclass(PaymentError, ShopError))
print('PaymentError - потомок Exception:', issubclass(PaymentError, Exception))

PaymentError - потомок ShopError: True
PaymentError - потомок Exception: True

Всё, что вы знали о встроенной иерархии, работает и для своих классов: ловля предка ShopError перехватывает и PaymentError, и DeliveryError, а порядок веток «ребёнок раньше родителя» остаётся в силе. Практический смысл — один обработчик «на все ошибки магазина» на верхнем уровне программы и точные ветки для отдельных случаев ниже.

class AgeError(Exception):
    pass

def parse_age(text):
    value = int(text)
    if value < 0 or value > 130:
        raise AgeError(f'возраст вне диапазона: {value}')
    return value

for text in ['25', '300']:
    try:
        print(text, '->', parse_age(text))
    except AgeError as e:
        print(text, '-> отклонено:', str(e))

25 -> 25
300 -> отклонено: возраст вне диапазона: 300

Типичный приём: своя ошибка вырастает поверх встроенной проверки. Разбор строки в число оставлен int, а бизнес-правило про разумный возраст — вашему классу. Вызывающий код теперь может поймать и AgeError (нарушено правило возраста), и ValueError (строка вообще не число) — по отдельности, как две разные ситуации.

Свой класс исключений — это способ говорить с вызывающим кодом на своём языке: не «что-то не подошло», а «на счёте не хватило денег». В финальном проекте раздела такие классы встретятся на практике: парсер грязных данных сообщит о сбоях своими именами.