Skip to content

Магические методы контейнеров __magic_container__ ​

На предыдущем уроке мы спроектировали наш первый Абстрактный Тип Данных (ADT) — Стек на примере Почтовой Коробки. Код работал отлично, но интерфейс взаимодействия (box.push(), box.size()) выглядел чужеродно для экосистемы Python.

В Python действует принцип: интерфейсы должны быть интуитивными. Если ваш класс логически является коллекцией или контейнером, он должен поддерживать стандартный синтаксис языка: работу с функцией len(), доступ по индексам box[0] и проверку вхождения через оператор in.

На этом уроке мы разберем дандер-методы, которые превращают любой кастомный класс в полноценный синтаксический контейнер.

1. Справочник магических методов контейнеров ​

Чтобы объект вашего класса начал вести себя как встроенный список (list), кортеж (tuple) или словарь (dict), достаточно перегрузить следующие методы:

Магический методСинтаксис в PythonЧто делает под капотом
__len__(self)len(container)Возвращает количество элементов (всегда целое число int >= 0).
__getitem__(self, key)value = container[key]Извлекает элемент по индексу или ключу.
__setitem__(self, key, value)container[key] = valueЗаписывает или обновляет значение по индексу/ключу.
__delitem__(self, key)del container[key]Удаляет элемент по индексу или ключу.
__contains__(self, item)item in containerПроверяет, существует ли элемент внутри контейнера (возвращает bool).

2. Модернизация Почтовой Коробки под синтаксис Python ​

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

Наша коробка ParcelBox будет хранить вещи. Мы сделаем так, чтобы:

  1. Количество вещей проверялось через len(box).
  2. Вещи можно было смотреть и менять по индексам, как в обычном списке: box[0] = "Книга".
  3. Поиск вещи внутри посылки работал через if "Чашка" in box:.

Реализация класса ParcelBox ​

python
class ParcelBox:
    """Класс Почтовой Коробки, реализующий интерфейс встроенных контейнеров Python."""

    def __init__(self, max_items: int = 5) -> None:
        """Инициализирует пустую коробку с ограничением по количеству мест.

        Args:
            max_items (int): Максимально допустимое количество вещей в коробке.
        """
        self.max_items: int = max_items
        self._items: list[str] = []  # Внутреннее защищенное хранилище

    def add_item(self, item: str) -> None:
        """Публичный метод для добавления вещи (базовая логика)."""
        if len(self._items) >= self.max_items:
            raise OverflowError("Коробка заполнена! Больше вещей не поместится.")
        self._items.append(item)

    def __len__(self) -> int:
        """Перегрузка функции len(). Возвращает текущее количество вещей."""
        return len(self._items)

    def __getitem__(self, index: int) -> str:
        """Перегрузка чтения по индексу: `item = box[index]`."""
        # Python автоматически выбросит IndexError, если индекс выйдет за границы списка
        return self._items[index]

    def __setitem__(self, index: int, value: str) -> None:
        """Перегрузка записи по индексу: `box[index] = new_value`."""
        if not isinstance(value, str):
            raise TypeError("В почтовую коробку можно класть только строки (названия вещей)!")
        self._items[index] = value

    def __delitem__(self, index: int) -> None:
        """Перегрузка оператора удаления: `del box[index]`."""
        self._items.pop(index)

    def __contains__(self, item: str) -> bool:
        """Перегрузка оператора `in`: `item in box`."""
        return item in self._items

    def __repr__(self) -> str:
        return f"ParcelBox(items={self._items}, capacity={len(self)}/{self.max_items})"


# === Демонстрация «магического» синтаксиса ===
if __name__ == "__main__":
    box = ParcelBox(max_items=3)
    
    # Заполняем коробку
    box.add_item("Книги")
    box.add_item("Шарф")
    
    # 1. Проверяем работу __len__
    print(f"Количество вещей: {len(box)}")  # Вывод: 2
    
    # 2. Проверяем работу __getitem__ (чтение по индексу)
    print(f"Первая вещь в коробке: {box[0]}")  # Вывод: Книги
    
    # 3. Проверяем работу __setitem__ (перезапись по индексу)
    box[1] = "Теплый Шарф"
    print(box)  # Вывод: ParcelBox(items=['Книги', 'Теплый Шарф'], capacity=2/3)
    
    # 4. Проверяем работу __contains__ (оператор `in`)
    if "Книги" in box:
        print("В посылке есть книги, таможня одобряет!")  # Этот блок выполнится
        
    # 5. Проверяем работу __delitem__ (удаление)
    del box[0]
    print(f"После удаления осталось вещей: {len(box)}")  # Вывод: 1

Магия циклов for из коробки!

Интересный факт: как только вы реализуете в своем классе методы __len__ и __getitem__, Python автоматически научит ваш класс поддерживать итерацию! Вы сможете написать for item in box: даже без прохождения темы итераторов, так как Python будет поочередно запрашивать индексы 0, 1, 2..., пока не встретит IndexError.

Проверьте себя (автопроверка) ​

Выполните каждый блок кода и сравните фактический вывод с ожидаемым, записанным в конце строки комментариями. Класс ParcelBox уже определён в предыдущем разделе урока.

Тест 1. Стандартный синтаксис контейнера:

python
test_box = ParcelBox(max_items=3)
test_box.add_item("Книги")
test_box.add_item("Шарф")
test_box.add_item("Чашка")
print(len(test_box), test_box[2])   # 3 Чашка

Тест 2. Переполнение коробки:

python
full = ParcelBox(max_items=1)
full.add_item("Книги")
try:
    full.add_item("Шарф")
except OverflowError as err:
    print(err)   # Коробка заполнена! Больше вещей не поместится.

Тест 3. Валидация записи и оператор in:

python
m = ParcelBox()
m.add_item("Чашка")
try:
    m[0] = 42
except TypeError as err:
    print(err)   # В почтовую коробку можно класть только строки (названия вещей)!
print("Чашка" in m)   # True
print("Шарф" in m)   # False
Пояснения к ответам

Тест 1. Перегруженные __len__ и __getitem__ делают len(test_box) и test_box[2] полностью идентичными по синтаксису работе со встроенным списком.

Тест 2. Лимит вместимости (max_items) контролируется публичным методом add_item, который выбрасывает OverflowError — бизнес-правило отделено от «магического» синтаксиса.

Тест 3. __setitem__ защищён от записи значений не того типа (валидация isinstance), а __contains__ реализует проверку через оператор in на основе внутреннего списка.

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

❓Зачем классу-контейнеру поддержка `len()`, `box[0]` и оператора `in`?
❓Что делает `__len__`?
❓Какая пара методов отвечает за чтение и запись по индексу: `box[0]` и `box[0] = x`?
❓Какой метод реализует оператор `item in container`?
❓Что происходит, если в классе реализованы `__len__` и `__getitem__`?
❓Где в примере урока живёт проверка переполнения (max_items)?

Практические упражнения для закрепления методов контейнеров ​

Продолжаем развивать наши сквозные проекты. В этих заданиях вам предстоит превратить спроектированные ранее абстрактные интерфейсы классов в синтаксически совместимые контейнеры Python.

Упражнение 1: Магический Стек Римских Чисел (RomanHistory) ​

Представьте, что вы пишете калькулятор римских чисел и вам нужно сохранять историю вычислений (историю операций) в виде структуры данных «Стек», но с возможностью просматривать историю по индексам.

Задание: Создайте класс RomanHistory, который внутри хранит список объектов вашего класса RomanNumber (или просто римских строк, если вы выполняете задание изолированно):

  1. Реализуйте метод push(roman_obj) для добавления записи в историю.
  2. Реализуйте __len__, чтобы выражение len(history) возвращало количество сохраненных операций.
  3. Реализуйте __getitem__, чтобы можно было получить доступ к любой записи по индексу (например, history[0] вернет самую старую запись, а history[-1] — последнюю).
  4. Запретите изменять историю напрямую! Метод __setitem__ должен выбрасывать исключение TypeError("История вычислений защищена от перезаписи!").
python
# Ожидаемое поведение:
# history = RomanHistory()
# history.push("X")
# history.push("V")
#
# print(len(history))  # Вывод: 2
# print(history[-1])   # Вывод: V
#
# history[0] = "I"     # raise TypeError: История вычислений защищена от перезаписи!

Упражнение 2: Контейнер Почтовых Индексов Адреса (AddressCard) ​

При отправке посылки на Почтовой Коробке пишется адрес. Адрес состоит из элементов: Страна, Город, Улица, Дом, Квартира. Логично представить карточку адреса как контейнер с фиксированными текстовыми ключами (аналог словаря), но с жесткой валидацией.

Задание: Создайте класс AddressCard:

  1. Внутри класса инициализируйте защищенный словарь _data со следующими ключами и значениями по умолчанию: {'country': None, 'city': None, 'street': None}.
  2. Реализуйте __getitem__(self, key), который возвращает значение поля. Если передан несуществующий ключ (например, 'spaceport'), выбрасывайте KeyError.
  3. Реализуйте __setitem__(self, key, value). Запись должна быть разрешена только для тех ключей, которые изначально есть в словаре по умолчанию. При попытке добавить новый ключ (например, card['phone'] = '123'), метод должен выбросить KeyError("Нельзя добавлять новые поля в карточку адреса!").
  4. Реализуйте __contains__ для проверки наличия заполненного (не равного None) поля через оператор in.

Упражнение 3: Безопасный Дек посылок со срезами (SecureParcelDeque) ​

Вы уже спроектировали Двустороннюю Очередь (ParcelDeque). Давайте превратим её в полноценный защищенный синтаксический контейнер.

Задание: Возьмите за основу логику Двусторонней очереди и реализуйте класс SecureParcelDeque:

  1. Реализуйте методы __len__ и __getitem__.
  2. Продвинутое условие: Сделайте так, чтобы __getitem__ поддерживал не только одиночные индексы, но и срезы (slices)!
    • Подсказка: Проверьте тип приходящего ключа: if isinstance(index, slice):. Если это срез, передайте его во внутренний список return self._storage[index] (встроенные списки Python уже умеют обрабатывать объекты срезов).
  3. Реализуйте __delitem__, но с ограничением: удалять элементы через del deque[index] можно только с краев структуры (индексы 0 или -1). Попытка удалить элемент из середины очереди должна вызывать ошибку ValueError("Удаление элементов из середины очереди запрещено правилами безопасности!").
python
# Ожидаемое поведение со срезами:
# deque = SecureParcelDeque()
# deque.add_rear("Коробка 1")
# deque.add_rear("Коробка 2")
# deque.add_rear("Коробка 3")
#
# print(deque[0:2])  # Должно вернуть срез списка: ['Коробка 1', 'Коробка 2']
# del deque[1]       # raise ValueError (индекс 1 — это середина)

Упражнение 4: Магическая Очередь Посылок на Погрузку (LoadingQueue) ​

Вернемся к нашей конвейерной ленте (ADT Очередь) из 11 урока. Когда коробки стоят на погрузку в автомобиль, логисту необходимо быстро проверять состояние этой очереди с помощью системного синтаксиса Python.

Задание: Создайте класс LoadingQueue:

  1. Реализуйте метод enqueue(item) для добавления посылки в конец очереди.
  2. Реализуйте метод __len__ (длина очереди).
  3. Реализуйте метод __contains__. Оператор in должен позволять мгновенно проверять, находится ли конкретная посылка в очереди на погрузку (например, if "Посылка_№5" in loading_queue:).
  4. Реализуйте метод __getitem__, но настройте его так, чтобы индекс 0 всегда возвращал посылку, которая стоит первой на выход (в начале очереди), а не в конце.

Упражнение 5: Багажная Сетка автомобиля (LuggageMesh) ​

При погрузке посылок в автомобиль используется сетка для удержания груза. Это контейнер, где элементы можно добавлять по индексу «ячейки» сетки, но ячейка имеет ограничение по объему (весу), который она может выдержать.

Задание: Создайте класс LuggageMesh:

  1. Конструктор принимает slots_count: int (количество ячеек, например 3) и max_weight_per_slot: float (лимит веса на одну ячейку). Внутри создается список _slots, изначально заполненный нулями (вес равен 0.0).
  2. Реализуйте __len__, возвращающий общее количество ячеек.
  3. Реализуйте __setitem__(self, index: int, weight: float). Метод принимает индекс ячейки и вес посылки, которую туда кладут. Если вес превышает max_weight_per_slot, выбрасывается ошибка ValueError("Сетка порвется! Слишком большой вес для одной ячейки.").
  4. Реализуйте __getitem__, возвращающий текущий вес в указанной ячейке.

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

Посмотреть решение Упражнения 1 (RomanHistory)
python
class RomanHistory:
    def __init__(self) -> None:
        self._history: list[str] = []

    def push(self, roman_str: str) -> None:
        self._history.append(roman_str)

    def __len__(self) -> int:
        return len(self._history)

    def __getitem__(self, index: int) -> str:
        return self._history[index]

    def __setitem__(self, index: int, value: str) -> None:
        raise TypeError("История вычислений защищена от перезаписи!")

# Демонстрация:
history = RomanHistory()
history.push("X")
history.push("V")
print(len(history))  # 2
print(history[-1])   # V
try:
    history[0] = "I"
except TypeError as err:
    print(err)   # История вычислений защищена от перезаписи!
Посмотреть решение Упражнения 2 (AddressCard)
python
class AddressCard:
    def __init__(self) -> None:
        self._data: dict[str, str | None] = {
            'country': None,
            'city': None,
            'street': None
        }

    def __getitem__(self, key: str) -> str | None:
        if key not in self._data:
            raise KeyError(f"Поле '{key}' отсутствует в карточке адреса!")
        return self._data[key]

    def __setitem__(self, key: str, value: str) -> None:
        if key not in self._data:
            raise KeyError("Нельзя добавлять новые поля в карточку адреса!")
        self._data[key] = value

    def __contains__(self, key: str) -> bool:
        # Поле считается входящим, если оно есть в структуре и уже заполнено
        return key in self._data and self._data[key] is not None

# Демонстрация:
card = AddressCard()
card['city'] = "Минск"
print(card['city'])   # Минск
print('city' in card)   # True (поле заполнено)
print('street' in card)   # False (поле пустое)
try:
    card['phone'] = '123'
except KeyError as err:
    print(err)   # Нельзя добавлять новые поля в карточку адреса!
Посмотреть решение Упражнения 3 (SecureParcelDeque со срезами)
python
class SecureParcelDeque:
    def __init__(self) -> None:
        self._storage: list[str] = []

    def add_rear(self, item: str) -> None:
        self._storage.append(item)

    def add_front(self, item: str) -> None:
        self._storage.insert(0, item)

    def __len__(self) -> int:
        return len(self._storage)

    def __getitem__(self, index: int | slice):
        if isinstance(index, slice):
            return self._storage[index]  # Возвращаем срез списка элементов
        return self._storage[index]

    def __delitem__(self, index: int) -> None:
        # Нормализуем отрицательные индексы (например, -1 переводим в последний индекс)
        actual_index = index if index >= 0 else len(self._storage) + index
        
        if actual_index != 0 and actual_index != len(self._storage) - 1:
            raise ValueError("Удаление элементов из середины очереди запрещено правилами безопасности!")
            
        self._storage.pop(actual_index)

# Демонстрация:
sd = SecureParcelDeque()
sd.add_rear("Коробка 1")
sd.add_rear("Коробка 2")
sd.add_rear("Коробка 3")
print(sd[0:2])   # ['Коробка 1', 'Коробка 2']
try:
    del sd[1]   # элемент из середины — запрещено
except ValueError as err:
    print(err)   # Удаление элементов из середины очереди запрещено правилами безопасности!
del sd[0]   # удаление с края разрешено
print(len(sd))   # 2
Посмотреть решение Упражнения 4 (LoadingQueue)
python
class LoadingQueue:
    def __init__(self) -> None:
        self._queue: list[str] = []

    def enqueue(self, item: str) -> None:
        self._queue.append(item)

    def __len__(self) -> int:
        return len(self._queue)

    def __contains__(self, item: str) -> bool:
        return item in self._queue

    def __getitem__(self, index: int) -> str:
        # Очередь FIFO: индекс 0 всегда должен возвращать элемент из начала списка
        return self._queue[index]

# Демонстрация:
loading = LoadingQueue()
loading.enqueue("Посылка_№1")
loading.enqueue("Посылка_№5")
print(loading[0])   # Посылка_№1 (первая на выход)
print("Посылка_№5" in loading)   # True
print(len(loading))   # 2
Посмотреть решение Упражнения 5 (LuggageMesh)
python
class LuggageMesh:
    def __init__(self, slots_count: int, max_weight_per_slot: float) -> None:
        self.max_weight: float = max_weight_per_slot
        self._slots: list[float] = [0.0] * slots_count

    def __len__(self) -> int:
        return len(self._slots)

    def __getitem__(self, index: int) -> float:
        return self._slots[index]

    def __setitem__(self, index: int, weight: float) -> None:
        if weight > self.max_weight:
            raise ValueError("Сетка порвется! Слишком большой вес для одной ячейки.")
        self._slots[index] = weight

# Демонстрация:
mesh = LuggageMesh(slots_count=3, max_weight_per_slot=5.0)
mesh[0] = 4.5
print(mesh[0])   # 4.5
try:
    mesh[1] = 6.0   # превышает лимит ячеек
except ValueError as err:
    print(err)   # Сетка порвется! Слишком большой вес для одной ячейки.
print(len(mesh))   # 3