Что значит «генератор» в Python на примере readComponents

Разбираемся, что в Python значит «генератор»: функция‑генератор или итератор‑генератор. На примере vobject.readComponents, как работать с next() и for.

Когда в документации пишут, что функция «является генератором», это означает, что сама функция — генератор, или что она возвращает генератор? Этот нюанс всплывает в readComponents из vobject: в описании его называют генератором, а в примерах его явно используют как объект, по которому итерируются или у которого вызывают next(). Прояснение экономит время и помогает избежать тонких ошибок при итерации.

Контекст

В документации readComponents описывается как генератор формулировкой вроде «Постепенно извлекает по одному Component из потока». При этом в примерах им пользуются так, будто он возвращает итератор‑генератор: вызывают next() или сразу передают в цикл for.

Код, из‑за которого возникает путаница

Рассмотрим два типичных способа использования. Оба опираются на одно и то же поведение, но воспринимаются по‑разному, если неясно, что именно подразумевается под «генератором».

from vobject import readComponents as emit_parts

# Получить одно значение через next()
cal_src = ical_stream_source
first_dt = next(emit_parts(cal_src)).vevent.dtstart.value

# Итерироваться по всем компонентам
vcf_source = vcf_stream_source
for comp in emit_parts(vcf_source):
    handle(comp)

Если многократно вызывать функцию, которая возвращает итератор‑генератор, каждый раз будет создаваться новый итератор. Это важно, когда вы рассчитываете продолжить с того места, где остановились.

Что здесь означает «генератор»

В Python слово «генератор» может означать либо функцию‑генератор, либо итератор‑генератор (его также называют объектом‑генератором). Вызов функции‑генератора каждый раз создаёт новый итератор‑генератор, и каждый такой итератор можно исчерпать только один раз. Это согласуется с формулировкой из глоссария Python:

Функция, которая возвращает итератор‑генератор. Внешне это обычная функция, но она содержит выражения yield, которые порождают последовательность значений, пригодных для использования в цикле for или для поштучного извлечения с помощью функции next().

Обычно под этим понимают функцию‑генератор, но в некоторых контекстах это может означать итератор‑генератор. Когда смысл может быть неочевиден, лучше использовать полные термины, чтобы избежать двусмысленности.

В контексте vobject.readComponents: это генератор в смысле функции‑генератора, которая возвращает итератор‑генератор. Модули редко содержат сами итераторы‑генераторы как объекты верхнего уровня, поэтому в документации разумно понимать «генератор» как функцию.

Практическое решение

Если нужно пройтись по данным один раз и сохранять позицию, свяжите возвращаемый итератор‑генератор с переменной и используйте его последовательно, вместо многократных вызовов функции.

from vobject import readComponents as emit_parts

cal_src = ical_stream_source
items_iter = emit_parts(cal_src)

first_dt = next(items_iter).vevent.dtstart.value

for comp in items_iter:
    handle(comp)

Так вы не создадите новый итератор случайно и пройдёте поток ровно один раз, по порядку.

Почему этот нюанс важен

Различие между функцией и итератором помогает избежать случайных перезапусков потока и путаницы при совмещении next() с циклом for. Оно также задаёт верные ожидания: каждый вызов функции‑генератора создаёт независимый одноразовый итератор, и его можно исчерпать только один раз.

Итоги

Когда в документации что‑то называют «генератором», воспринимайте это как сокращение для «функция‑генератор», если контекст явно не указывает на итератор‑генератор. Для vobject.readComponents считайте, что это функция, возвращающая итератор‑генератор. Если вы собираетесь продвигаться по потоку постепенно, сохраните итератор и используйте его последовательно. Нужен новый проход — вызовите функцию ещё раз и получите новый итератор.