Skip to content

Протокол итератора (__iter__ и __next__) ​

На прошлом уроке мы превратили нашу Почтовую Коробку (ParcelBox) в синтаксический контейнер с помощью методов __len__ и __getitem__. Мы заметили магический эффект: коробку стало можно перебирать в цикле for.

Однако этот способ итерации — лишь запасной механизм Python. Он работает «вслепую», просто перебирая индексы от 0 до тех пор, пока не возникнет ошибка IndexError.

Сегодня мы разберем Протокол Итератора — официальный, гибкий и профессиональный способ обхода объектов в Python. Он позволяет настраивать уникальную логику обхода (например, перебирать вещи по приоритету, в обратном порядке или только хрупкие предметы), не привязываясь к индексам.

1. Разница между Iterable и Iterator ​

Чтобы понять, как устроен цикл for в Python под капотом, нужно четко различать два понятия:

  1. Iterable (Итерируемый объект) — это сам контейнер, который хранит данные (например, список, словарь или ваша коробка). В нем реализован метод __iter__. Этот метод не умеет перебирать элементы, его единственная задача — вернуть объект-итератор.
  2. Iterator (Итератор) — это специальный «курсор» или «указатель», который создается для конкретного обхода. Он знает, на каком элементе мы сейчас находимся, и умеет переходить к следующему. В нем реализован метод __next__.

Как цикл for работает изнутри: ​

Когда вы пишете:

python
# for item in box:
#     print(item)

Python скрытно от вас выполняет следующий алгоритм:

  1. Вызывает iterator = iter(box), что внутри класса запускает метод box.__iter__().
  2. Запускает бесконечный цикл, где на каждом шаге вызывает item = next(iterator), что внутри запускает метод iterator.__next__().
  3. Как только элементы заканчиваются, метод __next__ выбрасывает специальное сигнальное исключение StopIteration. Цикл for ловит его и аккуратно завершает свою работу.

2. Реализация Итератора для Почтовой Коробки ​

Давайте напишем правильный протокол итератора для класса ParcelBox.

В промышленной разработке хорошим тоном считается разделение: сам класс контейнера возвращает отдельный класс-итератор. Это позволяет запускать несколько независимых циклов for по одной и той же коробке одновременно.

python
class ParcelBoxIterator:
    """Класс-итератор («курсор») для обхода вещей в почтовой коробке."""

    def __init__(self, items_list: list[str]) -> None:
        self._items: list[str] = items_list
        self._cursor: int = 0  # Текущая позиция обхода

    def __iter__(self) -> "ParcelBoxIterator":
        # Итератор обязан возвращать самого себя (требование PEP 234),
        # иначе списковые включения [x for x in box] упадут с TypeError
        return self

    def __next__(self) -> str:
        """Возвращает следующий элемент или останавливает цикл."""
        if self._cursor >= len(self._items):
            # Элементы закончились — подаем сигнал циклу for
            raise StopIteration
        
        item = self._items[self._cursor]
        self._cursor += 1  # Сдвигаем курсор вперед
        return item


class ParcelBox:
    """Класс Почтовой Коробки (Итерируемый объект)."""

    def __init__(self) -> None:
        self._items: list[str] = []

    def add_item(self, item: str) -> None:
        self._items.append(item)

    def __iter__(self) -> ParcelBoxIterator:
        """Возвращает новый объект-итератор, готовый к обходу с нуля."""
        return ParcelBoxIterator(self._items)

    def __repr__(self) -> str:
        return f"ParcelBox({self._items})"


# === Демонстрация работы ===
if __name__ == "__main__":
    box = ParcelBox()
    box.add_item("Книги")
    box.add_item("Шарф")
    box.add_item("Чашка")

    # 1. Классический, красивый обход через цикл for
    print("--- Обход через цикл for ---")
    for item in box:
        print(f"Извлечен предмет для осмотра: {item}")

    # 2. Ручной обход (имитируем то, что делает Python внутри)
    print("\n--- Ручной обход под капотом ---")
    my_iterator = iter(box)  # Вызывает __iter__()
    
    print(next(my_iterator))  # Вывод: Книги
    print(next(my_iterator))  # Вывод: Шарф
    print(next(my_iterator))  # Вывод: Чашка
    
    # Следующий вызов вызовет ошибку StopIteration
    # print(next(my_iterator))

Упрощенный вариант (Self-Iterator)

Если вам не нужно запускать параллельные циклы по одному объекту, класс может возвращать в __iter__ самого себя (return self). В таком случае методы __iter__ и __next__ пишутся внутри одного и того же класса. Вы увидите этот подход в практических упражнениях.

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

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

Тест 1. Два независимых обхода одной коробки:

python
check_box = ParcelBox()
check_box.add_item("Книги")
check_box.add_item("Шарф")
first = [item for item in check_box]
second = [item for item in check_box]
print(first)   # ['Книги', 'Шарф']
print(second)   # ['Книги', 'Шарф'] — второй цикл снова стартует с начала

Тест 2. Ручной обход и сигнал StopIteration:

python
man = ParcelBox()
man.add_item("Чашка")
it = iter(man)
print(next(it))   # Чашка
try:
    next(it)
except StopIteration:
    print("StopIteration: элементы закончились")

Тест 3. Цикл for по пустой коробке:

python
empty_box = ParcelBox()
count = 0
for item in empty_box:
    count += 1
print(count)   # 0
Пояснения к ответам

Тест 1. Каждый вызов __iter__ создаёт новый объект ParcelBoxIterator с курсором 0, поэтому два последовательных цикла по одной коробке полностью независимы.

Тест 2. Когда курсор выходит за пределы списка, __next__ выбрасывает StopIteration — именно это сигнальное исключение цикл for перехватывает незаметно для программиста.

Тест 3. Для пустого контейнера первый же вызов __next__ останавливает цикл, поэтому тело цикла не выполнится ни разу.

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

❓В чём разница между Iterable и Iterator?
❓Какая единственная задача метода `__iter__`?
❓Как цикл `for` узнаёт, что элементы закончились?
❓Опишите алгоритм работы `for item in box:` изнутри:
❓Зачем выносить итератор в отдельный класс (ParcelBoxIterator)?
❓Почему `__iter__` у самого итератора обязан возвращать `self`?

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

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

Упражнение 1: Обратный итератор Римских Чисел (RomanReverseHistory) ​

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

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

  1. Метод push(roman_str) добавляет римское число в защищенный список _history.
  2. Реализуйте класс-итератор или метод __iter__ и __next__ так, чтобы при запуске цикла for item in history: элементы выдавались с конца списка к началу (в обратном порядке).
  3. По достижении начала списка итерация должна корректно завершаться через StopIteration.
python
# Ожидаемое поведение:
# history = RomanReverseHistory()
# history.push("I")
# history.push("V")
# history.push("X")
#
# for num in history:
#     print(num)  # Должно вывести поочередно: X, затем V, затем I

Упражнение 2: Итератор ускоренной разгрузки по две посылки (DoubleLoadingQueue) ​

При разгрузке конвейерной ленты (LoadingQueue) логисты решили ускорить процесс: за один шаг цикла for робот должен забирать сразу пару посылок (в виде кортежа), стоящих первыми в очереди.

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

  1. Метод enqueue(item) добавляет элемент в конец очереди.
  2. Реализуйте протокол итератора. Каждый вызов next() должен возвращать кортеж из двух элементов (item1, item2).
  3. Если в очереди остался один последний элемент, верните кортеж, где второй элемент равен None, например ("Посылка №5", None).
  4. После этого итерация завершается.
python
# Ожидаемое поведение:
# queue = DoubleLoadingQueue()
# queue.enqueue("Коробка 1")
# queue.enqueue("Коробка 2")
# queue.enqueue("Коробка 3")
#
# for batch in queue:
#     print(batch)
# # Вывод:
# # ('Коробка 1', 'Коробка 2')
# # ('Коробка 3', None)

Упражнение 3: Приоритетный обход хрупких посылок (FragileFirstBox) ​

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

Задание: Создайте класс FragileFirstBox, хранящий вещи в виде кортежей (название, хрупкость_bool):

  1. Метод add_item(name: str, is_fragile: bool) добавляет вещь в коробку.
  2. Реализуйте кастомный итератор. При обходе через for item in box: цикл должен сначала выдать все хрупкие предметы, а затем все обычные предметы, независимо от того, в каком порядке они изначально лежали в списке.
python
# Ожидаемое поведение:
# box = FragileFirstBox()
# box.add_item("Кирпич", is_fragile=False)
# box.add_item("Ваза", is_fragile=True)
# box.add_item("Книга", is_fragile=False)
# box.add_item("Бокал", is_fragile=True)
#
# for item in box:
#     print(item)  # Вывод строго в порядке: Ваза, Бокал, Кирпич, Книга

Упражнение 4: Бесконечный генератор случайных трек-номеров (TrackNumberGenerator) ​

Для тестирования базы данных почты нужен класс, который генерирует бесконечный поток случайных трек-номеров вида RU-XXXXX, где XXXXX — случайное число. Бесконечные циклы — это классическая сфера применения итераторов.

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

  1. Класс не хранит элементы внутри списка, он генерирует их на лету в методе __next__. Для генерации чисел используйте модуль import random.
  2. Этот итератор никогда не должен вызывать ошибку StopIteration — он бесконечен.
  3. Протестируйте итератор в цикле for, но обязательно поставьте счетчик и break, чтобы программа не зависла!
python
# Ожидаемое поведение:
# gen = TrackNumberGenerator()
# for idx, track in enumerate(gen):
#     print(track)  # Вывод: RU-49281, RU-02941...
#     if idx == 2:
#         break  # Печатаем только 3 штуки и останавливаемся

Упражнение 5: Циклический обход дежурных курьеров (CourierCarousel) ​

В курьерской службе есть фиксированный список сотрудников (например, Алиса, Боб, Чарли). Посылки поступают непрерывно, и их нужно распределять по кругу («каруселью»): Алиса -> Боб -> Чарли -> Алиса -> Боб...

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

  1. Конструктор принимает список имен курьеров.
  2. Реализуйте итератор, который бесконечно ходит по кругу. Когда элементы списка курьеров заканчиваются, курсор должен автоматически сбрасываться на индекс 0.
  3. Добавьте метод stop_carousel(), который переключает внутренний флаг, после чего следующий вызов __next__ наконец-то выбросит StopIteration и остановит цикл.

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

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

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

    def __iter__(self) -> "RomanReverseHistory":
        # Используем self-итератор. Запоминаем стартовую позицию с конца
        self._cursor = len(self._history) - 1
        return self

    def __next__(self) -> str:
        if self._cursor < 0:
            raise StopIteration
        
        item = self._history[self._cursor]
        self._cursor -= 1
        return item

# Демонстрация:
rh = RomanReverseHistory()
rh.push("I")
rh.push("V")
rh.push("X")
print([num for num in rh])   # ['X', 'V', 'I']
Посмотреть решение Упражнения 2 (DoubleLoadingQueue)
python
class DoubleLoadingQueue:
    def __init__(self) -> None:
        self._queue: list[str] = []

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

    def __iter__(self) -> "DoubleLoadingQueue":
        self._cursor = 0
        return self

    def __next__(self) -> tuple[str, str | None]:
        if self._cursor >= len(self._queue):
            raise StopIteration
        
        # Берем первый элемент пары
        item1 = self._queue[self._cursor]
        self._cursor += 1
        
        # Проверяем, есть ли второй элемент
        if self._cursor < len(self._queue):
            item2 = self._queue[self._cursor]
            self._cursor += 1
        else:
            item2 = None
            
        return (item1, item2)

# Демонстрация:
dlq = DoubleLoadingQueue()
dlq.enqueue("Коробка 1")
dlq.enqueue("Коробка 2")
dlq.enqueue("Коробка 3")
for batch in dlq:
    print(batch)   # ('Коробка 1', 'Коробка 2'), затем ('Коробка 3', None)
Посмотреть решение Упражнения 3 (FragileFirstBox)
python
class FragileFirstBoxIterator:
    def __init__(self, raw_items: list[tuple[str, bool]]) -> None:
        # При инициализации сразу делим элементы на две группы
        self.fragile = [name for name, is_f in raw_items if is_f]
        self.regular = [name for name, is_f in raw_items if not is_f]
        # Объединяем их: сначала хрупкие, потом обычные
        self.sorted_items = self.fragile + self.regular
        self.cursor = 0

    def __iter__(self) -> "FragileFirstBoxIterator":
        # Итератор обязан возвращать самого себя (требование PEP 234)
        return self

    def __next__(self) -> str:
        if self.cursor >= len(self.sorted_items):
            raise StopIteration
        item = self.sorted_items[self.cursor]
        self.cursor += 1
        return item


class FragileFirstBox:
    def __init__(self) -> None:
        self._items: list[tuple[str, bool]] = []

    def add_item(self, name: str, is_fragile: bool) -> None:
        self._items.append((name, is_fragile))

    def __iter__(self) -> FragileFirstBoxIterator:
        return FragileFirstBoxIterator(self._items)

# Демонстрация:
fbox = FragileFirstBox()
fbox.add_item("Кирпич", is_fragile=False)
fbox.add_item("Ваза", is_fragile=True)
fbox.add_item("Книга", is_fragile=False)
fbox.add_item("Бокал", is_fragile=True)
print([item for item in fbox])   # ['Ваза', 'Бокал', 'Кирпич', 'Книга']
Посмотреть решение Упражнения 4 (TrackNumberGenerator)
python
import random

class TrackNumberGenerator:
    def __iter__(self) -> "TrackNumberGenerator":
        return self

    def __next__(self) -> str:
        # Генерируем случайное число от 10000 до 99999
        random_code = random.randint(10000, 99999)
        return f"RU-{random_code}"

# Демонстрация:
gen = TrackNumberGenerator()
for idx, track in enumerate(gen):
    print(track)   # RU-XXXXX — случайный код
    if idx == 2:
        break
Посмотреть решение Упражнения 5 (CourierCarousel)
python
class CourierCarousel:
    def __init__(self, couriers: list[str]) -> None:
        self._couriers: list[str] = couriers
        self._is_active: bool = True
        self._cursor: int = 0

    def stop_carousel(self) -> None:
        self._is_active = False

    def __iter__(self) -> "CourierCarousel":
        self._cursor = 0
        return self

    def __next__(self) -> str:
        if not self._is_active or not self._couriers:
            raise StopIteration
        
        courier = self._couriers[self._cursor]
        
        # Сдвигаем курсор, используя остаток от деления для зацикливания
        self._cursor = (self._cursor + 1) % len(self._couriers)
        return courier

# Демонстрация:
carousel = CourierCarousel(["Алиса", "Боб", "Чарли"])
for idx, courier in enumerate(carousel):
    print(courier)   # Алиса, Боб, Чарли, Алиса, Боб, Чарли
    if idx == 5:
        break

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

Перед отправкой кода на ревью проверьте, что: • Метод __iter__ возвращает объект, у которого есть метод __next__. • Остановка цикла во всех конечных структурах сопровождается вызовом raise StopIteration. • Итераторы не изменяют и не разрушают данные внутри исходного класса-контейнера при обходе.