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

Question

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

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

… а не…

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

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

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

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

Answer 1

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

Answer 2

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

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

arg : a dictionary of...

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

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

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

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

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