Документация Python: многократная итерация?

При документировании функции Python я считаю более питоническим сказать:

def Foo(i):
    """i: An interable containing…"""

…скорее, чем…

def Foo(i):
    """i: A list of …"""

Когда i действительно не нужно быть list. (Foo с радостью будет работать на set, tuple и т. д.) Проблема в генераторах. Генераторы обычно допускают только 1 итерацию. Большинство функций совместимы с генераторами или итерируемыми объектами, которые допускают только один проход, но некоторые из них не поддерживаются.

Для тех функций, которые не могут принимать генераторы/вещи, которые могут быть повторены только один раз, существует ли четкий, последовательный термин Python, чтобы сказать «вещь, которую можно повторять только более одного раза»?

Глоссарий Python для iterable и iterator, похоже, имеет определение "один раз, но, возможно, и больше, если вам повезет".


python duck-typing
person Thanatos    schedule 29.11.2011    source источник
comment
Коллекция"? Кажется, здесь описаны все типы примеров.   -  person ephemient    schedule 29.11.2011
comment
+1 к использованию контейнера, который, кажется, наиболее лаконично отражает основную идею, но ... я не думаю, что видел контейнер, используемый в какой-либо документации Python?   -  person Richard Levasseur    schedule 29.11.2011
comment
Контейнер — это объект с методом __contains__(), который не является ни необходимым, ни достаточным для повторного использования итерации. docs.python.org/library/collections.html#collections.Container   -  person Michael Hoffman    schedule 29.11.2011

Ответы (2)


arrow_upward
2
arrow_downward

Я не знаю стандартного термина для этого, по крайней мере, не навскидку, но я думаю, что «многоразовый итеративный» поймет суть, если вам нужна короткая фраза.

На практике, как правило, можно структурировать функцию таким образом, чтобы вам не приходилось повторять i более одного раза. В качестве альтернативы вы можете создать список из итерации, а затем перебирать список столько раз, сколько хотите; или вы можете использовать itertools.tee для получения нескольких независимых «копий» итератора. Это позволяет вам принять генератор, даже если вам нужно использовать его более одного раза.

person David Z    schedule 29.11.2011
comment
Обратите внимание, что, как указано в документах, , если один итератор использует большую часть или все данные до запуска другого итератора, быстрее использовать list() вместо tee(). В этом случае tee() будет копировать/сохранять контент несколько раз, тогда как list() сохранит его только один раз. - person waterproof; 18.12.2015

arrow_upward
1
arrow_downward

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

Пример: если я написал функцию, которая ожидает обхода ключей словаря и игнорирует его значения, я пишу:

arg : a dictionary of...

даже если for e in arg: будет работать с другими итерируемыми объектами. Я решил сделать это, потому что в контексте моего кода меня не волнует, будет ли функция все еще работать... Меня больше волнует, что всякий, кто читает документацию, понимает, как эта функция предназначен для использования.

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

  1. задокументировать, какое исключение будет вызвано при определенных условиях [например: "Вызовите TypeError, если итерируемый объект не может быть повторен более одного раза"]
  2. выполните некоторую упреждающую обработку аргументов, которая сделает функцию совместимой с "одноразовыми" итерируемыми объектами.

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

Еще раз: в подходе, который вы хотите использовать, нет ничего плохого, но я считаю, что это один из случаев, когда "явное лучше, чем неявное»: документация, в которой упоминается «многократно используемая итерация», определенно точна, но прилагательное можно легко пропустить.

ХТХ!

person mac    schedule 29.11.2011