Skip to content

Современные интерфейсы через typing.Protocol ​

Изучив Абстрактные Базовые Классы (ABC) и увидели, как они жестко связывают архитектуру: подкласс обязан явно наследоваться от родителя (class StandardParcel(BaseParcel)), чтобы считаться частью системы. В программировании такой подход называется номинальной типизацией.

Однако визитная карточка Python — это динамическая утиная типизация (Duck Typing): «Если это выглядит как утка, плавает как утка и крякает как утка, то это утка». Нам не важно, от кого унаследован объект, главное — чтобы у него были нужные методы. В современном Python (начиная с версии 3.8, PEP 544) утиную типизацию сделали строгой и понятной для сред разработки (IDE) с помощью инструмента typing.Protocol.

На этом уроке мы разберем, как описывать гибкие интерфейсы-протоколы (структурную типизацию), почему они удобнее жесткого наследования и как применить их к нашей экосистеме Почтовых Коробок.

1. Номинальная типизация (ABC) против Структурной (Protocol) ​

  • ABC (Номинальная): Объект считается подходящим только в том случае, если разработчик явно указал связь в коде через скобки наследования. Если класс написан сторонним разработчиком или взят из чужой библиотеки, мы не сможем заставить его наследоваться от нашего ABC без изменения его исходного кода.
  • Protocol (Структурная): Объект считается подходящим автоматически, если его структура (набор методов и типов) совпадает с протоколом. Никакого явного наследования не требуется! Это обеспечивает максимальную гибкость Production-кода.

2. Реализация Протокола Доставки посылок ​

Давайте опишем протокол Shippable (То, что можно отправить). Любой объект в системе, у которого есть метод calculate_shipping_price() -> float, будет автоматически считаться удовлетворяющим этому протоколу.

python
from typing import Protocol, runtime_checkable

@runtime_checkable
class Shippable(Protocol):
    """Интерфейс-протокол для любых отправляемых объектов.
    
    Декоратор @runtime_checkable позволяет использовать этот протокол 
    внутри функции isinstance() во время работы программы.
    """
    weight: float

    def calculate_shipping_price(self) -> float:
        """Объект должен уметь рассчитывать стоимость своей доставки."""
        ...  # Вместо pass в протоколах принято ставить три точки (Ellipsis)


# Обратите внимание: класс ParcelBox НЕ наследуется от Shippable!
class ParcelBox:
    """Самостоятельный класс Почтовой Коробки."""
    def __init__(self, weight: float) -> None:
        self.weight: float = weight

    def calculate_shipping_price(self) -> float:
        return self.weight * 5.5


# Абсолютно чужой класс из другой системы, у которого совпала структура
class HeavyCargoVehicle:
    """Транспортный контейнер."""
    def __init__(self, weight: float) -> None:
        self.weight: float = weight

    def calculate_shipping_price(self) -> float:
        return (self.weight * 10.0) + 150.0


# --- Полиморфная функция, которая требует выполнения протокола ---
def ship_item(item: Shippable) -> None:
    """Функция принимает любой объект, соответствующий структуре Shippable.
    
    IDE и статические анализаторы (mypy) сразу подскажут, если придет не тот объект.
    """
    # Благодаря @runtime_checkable работает isinstance
    if not isinstance(item, Shippable):
        raise TypeError("Этот груз не соответствует протоколу доставки!")
        
    price = item.calculate_shipping_price()
    print(f"[ТРАНСПОРТ] Объект принят. Стоимость доставки: {price} руб.")


# === Проверка работы Протокола ===
if __name__ == "__main__":
    box = ParcelBox(4.5)
    vehicle = HeavyCargoVehicle(120.0)

    # Оба объекта успешно принимаются функцией, несмотря на отсутствие общего родителя!
    ship_item(box)      # Успех
    ship_item(vehicle)  # Успех

Чек-лист готовности ​

Перед тем как перейти к выполнению практических упражнений, убедитесь, что вы:

  • [ ] Твердо помните: классы, которые должны соответствовать протоколу, не должны указывать класс-протокол в качестве родителя в круглых скобках.
  • [ ] Знаете, зачем нужен декоратор @runtime_checkable: без него проверка isinstance(obj, MyProtocol) вызовет критическую ошибку во время выполнения скрипта.
  • [ ] Понимаете, что внутри методов класса-протокола вместо ключевого слова pass принято использовать синтаксический маркер трех точек ....

Проверьте себя ​

❓Что такое утиная типизация (Duck Typing)?
❓ABC (номинальная) против Protocol (структурная) — в чём разница?
❓Когда и какой спецификацией появился `typing.Protocol`?
❓Зачем нужен декоратор `@runtime_checkable`?
❓Что ставят вместо `pass` в телах методов класса-протокола?
❓Почему `ship_item` принимает и ParcelBox, и HeavyCargoVehicle?

Практические упражнения для Production-кода ​

Выполните эти 5 практических заданий, чтобы научиться проектировать гибкие современные интерфейсы на базе структурной утиной типизации и защищать полиморфизм вашего кода.

Упражнение 1: Протокол валидации Римских Чисел (ConvertibleRoman) ​

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

Задание:

  1. Создайте класс-протокол RomanConvertible(Protocol).
  2. Объявите в нем метод to_arabic(self, roman_str: str) -> int: ....
  3. Создайте независимый класс FastRomanEngine (без наследования от протокола), реализуйте в нем метод to_arabic.
  4. Напишите функцию execute_conversion(engine: RomanConvertible, text: str), которая принимает объект протокола и запускает конвертацию. Проверьте её работу.

Упражнение 2: Ошибка статического анализатора при несовпадении сигнатур (ProtocolMismatch) ​

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

Задание: Перед вами протокол и ошибочный класс курьера. Скопируйте его.

python
from typing import Protocol, runtime_checkable

@runtime_checkable
class Deliverable(Protocol):
    def get_route_distance(self) -> float: ...

class BrokenCourier:
    # Ошибка: метод возвращает строку вместо float!
    def get_route_distance(self) -> str:
        return "15.5 км"
  1. Напишите функцию, проверяющую объект через isinstance(obj, Deliverable).
  2. Запустите код и посмотрите, как Python реагирует на несовпадение типов возвращаемого значения при проверке протокола.
  3. Исправьте класс BrokenCourier, чтобы он строго соответствовал контракту Deliverable.

Упражнение 3: Протокол инспектирования и таможенного досмотра (InspectableCargo) ​

Нам необходимо создать интерфейс для таможенного терминала. Досмотру могут подвергаться самые разные объекты: посылки, паллеты и даже личные вещи курьеров. Наследовать их от одного ABC-класса глупо, поэтому протокол — идеальное решение.

Задание:

  1. Создайте протокол Inspectable со встроенным декоратором @runtime_checkable.
  2. Внутри протокола опишите метод get_content_list(self) -> list[str]: ....
  3. Создайте класс CustomerParcel и независимый класс CourierBag. В обоих классах реализуйте данный метод.
  4. Напишите функцию border_control(item: Inspectable), которая проверяет объект через isinstance и выводит список вещей на экран. Протестируйте её на объектах обоих классов.

Упражнение 4: Протоколы для проверки наличия атрибутов (HasTrackingNumber) ​

Протоколы в Python могут требовать наличия не только методов, но и конкретных свойств (переменных) с определенным типом данных.

Задание:

  1. Создайте протокол HasTrack(Protocol).
  2. Опишите в нем требование к наличию строкового атрибута: tracking_number: str.
  3. Создайте класс Letter (Письмо) и класс Container (Контейнер). Задайте им это свойство в конструкторе.
  4. Пометьте протокол как @runtime_checkable, напишите проверяющую функцию и убедитесь, что Python успешно распознает оба класса как соответствующие протоколу HasTrack по наличию переменной.
python
# Ожидаемый протокол:
@runtime_checkable
class HasTrack(Protocol):
    tracking_number: str

Упражнение 5: Комбинация протоколов в один сложный интерфейс (AdvancedLogisticsProtocol) ​

В крупных проектах протоколы можно наследовать друг от друга, объединяя несколько мелких контрактов в один большой комплексный интерфейс.

Задание: Используйте протоколы Shippable из теоретической части (Блок 1) и HasTrack из Упражнения 4.

  1. Создайте продвинутый протокол PremiumShippable(Shippable, HasTrack, Protocol). Он автоматически объединяет требования к наличию веса, метода расчета стоимости и трек-номера.
  2. Сделайте его @runtime_checkable.
  3. Создайте класс PremiumBox, реализующий все три требования.
  4. Напишите функцию, которая принимает PremiumShippable грузы, и протестируйте её.

Решения для самопроверки ​

Посмотреть решение Упражнения 1 (ConvertibleRoman)
python
from typing import Protocol

class RomanConvertible(Protocol):
    def to_arabic(self, roman_str: str) -> int: ...

class FastRomanEngine:
    def to_arabic(self, roman_str: str) -> int:
        return len(roman_str)  # Упрощенная заглушка

def execute_conversion(engine: RomanConvertible, text: str) -> int:
    return engine.to_arabic(text)
Посмотреть решение Упражнения 2 (Исправление BrokenCourier)
python
from typing import Protocol, runtime_checkable

@runtime_checkable
class Deliverable(Protocol):
    def get_route_distance(self) -> float: ...

class BrokenCourier:
    # Исправление: метод должен возвращать строго тип float
    def get_route_distance(self) -> float:
        return 15.5
Посмотреть решение Упражнения 3 (InspectableCargo)
python
from typing import Protocol, runtime_checkable

@runtime_checkable
class Inspectable(Protocol):
    def get_content_list(self) -> list[str]: ...

class CustomerParcel:
    def get_content_list(self) -> list[str]:
        return ["Одежда", "Книги"]

class CourierBag:
    def get_content_list(self) -> list[str]:
        return ["Ключи", "Обед", "Документы"]

def border_control(item: Inspectable) -> None:
    if not isinstance(item, Inspectable):
        raise TypeError("Объект запрещен к досмотру: не соответствует протоколу!")
    print(f"[ТАМОЖНЯ] Содержимое груза: {item.get_content_list()}")
Посмотреть решение Упражнения 4 (HasTrackingNumber)
python
from typing import Protocol, runtime_checkable

@runtime_checkable
class HasTrack(Protocol):
    tracking_number: str

class Letter:
    def __init__(self, tracking_number: str) -> None:
        self.tracking_number: str = tracking_number

class Container:
    def __init__(self, tracking_number: str) -> None:
        self.tracking_number: str = tracking_number
Посмотреть решение Упражнения 5 (AdvancedLogisticsProtocol)
python
from typing import Protocol, runtime_checkable

# Протоколы Shippable и HasTrack берутся из предыдущих заданий

@runtime_checkable
class PremiumShippable(Shippable, HasTrack, Protocol):
    pass

class PremiumBox:
    def __init__(self, tracking_number: str, weight: float) -> None:
        self.tracking_number: str = tracking_number
        self.weight: float = weight

    def calculate_shipping_price(self) -> float:
        return self.weight * 15.0