Appearance
Магические методы контейнеров __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 будет хранить вещи. Мы сделаем так, чтобы:
- Количество вещей проверялось через
len(box). - Вещи можно было смотреть и менять по индексам, как в обычном списке:
box[0] = "Книга". - Поиск вещи внутри посылки работал через
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 (или просто римских строк, если вы выполняете задание изолированно):
- Реализуйте метод
push(roman_obj)для добавления записи в историю. - Реализуйте
__len__, чтобы выражениеlen(history)возвращало количество сохраненных операций. - Реализуйте
__getitem__, чтобы можно было получить доступ к любой записи по индексу (например,history[0]вернет самую старую запись, аhistory[-1]— последнюю). - Запретите изменять историю напрямую! Метод
__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:
- Внутри класса инициализируйте защищенный словарь
_dataсо следующими ключами и значениями по умолчанию:{'country': None, 'city': None, 'street': None}. - Реализуйте
__getitem__(self, key), который возвращает значение поля. Если передан несуществующий ключ (например,'spaceport'), выбрасывайтеKeyError. - Реализуйте
__setitem__(self, key, value). Запись должна быть разрешена только для тех ключей, которые изначально есть в словаре по умолчанию. При попытке добавить новый ключ (например,card['phone'] = '123'), метод должен выброситьKeyError("Нельзя добавлять новые поля в карточку адреса!"). - Реализуйте
__contains__для проверки наличия заполненного (не равногоNone) поля через операторin.
Упражнение 3: Безопасный Дек посылок со срезами (SecureParcelDeque)
Вы уже спроектировали Двустороннюю Очередь (ParcelDeque). Давайте превратим её в полноценный защищенный синтаксический контейнер.
Задание: Возьмите за основу логику Двусторонней очереди и реализуйте класс SecureParcelDeque:
- Реализуйте методы
__len__и__getitem__. - Продвинутое условие: Сделайте так, чтобы
__getitem__поддерживал не только одиночные индексы, но и срезы (slices)!- Подсказка: Проверьте тип приходящего ключа:
if isinstance(index, slice):. Если это срез, передайте его во внутренний списокreturn self._storage[index](встроенные списки Python уже умеют обрабатывать объекты срезов).
- Подсказка: Проверьте тип приходящего ключа:
- Реализуйте
__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:
- Реализуйте метод
enqueue(item)для добавления посылки в конец очереди. - Реализуйте метод
__len__(длина очереди). - Реализуйте метод
__contains__. Операторinдолжен позволять мгновенно проверять, находится ли конкретная посылка в очереди на погрузку (например,if "Посылка_№5" in loading_queue:). - Реализуйте метод
__getitem__, но настройте его так, чтобы индекс0всегда возвращал посылку, которая стоит первой на выход (в начале очереди), а не в конце.
Упражнение 5: Багажная Сетка автомобиля (LuggageMesh)
При погрузке посылок в автомобиль используется сетка для удержания груза. Это контейнер, где элементы можно добавлять по индексу «ячейки» сетки, но ячейка имеет ограничение по объему (весу), который она может выдержать.
Задание: Создайте класс LuggageMesh:
- Конструктор принимает
slots_count: int(количество ячеек, например 3) иmax_weight_per_slot: float(лимит веса на одну ячейку). Внутри создается список_slots, изначально заполненный нулями (вес равен 0.0). - Реализуйте
__len__, возвращающий общее количество ячеек. - Реализуйте
__setitem__(self, index: int, weight: float). Метод принимает индекс ячейки и вес посылки, которую туда кладут. Если вес превышаетmax_weight_per_slot, выбрасывается ошибкаValueError("Сетка порвется! Слишком большой вес для одной ячейки."). - Реализуйте
__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