Python文档：iterable多次？

Question

在编写Python函数的文档时，我发现说：

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

…而不是

^{pr2}$

当i真的不需要是list时。（Foo将在set、tuple等上愉快地运行）问题在于生成器。生成器通常只允许1次迭代。大多数函数都是单循环的。在

对于那些不能接受只能迭代一次的生成器/事物的函数，有没有一个明确、一致的Python术语来表示“只能多次迭代的事物”？在

iterable和{a2}的Python词汇表似乎有一个“一次，但如果幸运的话可能会更多”的定义。在

Answer 1

我不知道这方面的标准术语，至少不是草率的，但我认为如果你需要一个简短的短语，“可重用的iterable”会让你明白这一点。在

一般来说，你不需要在你的函数中重复一次。或者，您可以从iterable中创建一个列表，然后根据需要对该列表进行多次迭代；或者可以使用itertools.tee获取迭代器的多个独立“副本”。这样，即使需要多次使用生成器，也可以接受它。在

Answer 2

这可能更像是一个风格和偏好的问题，而不是其他任何事情。。。我对我的文档有不同的看法：我总是根据程序上下文中预期的输入来编写docstring。在

示例：如果我编写了一个函数，它希望遍历字典的键而忽略它的值，我会写：

arg : a dictionary of...

即使for e in arg:可以与其他iterable一起工作。我选择这样做，因为在我的代码上下文中，我不在乎函数是否仍然有效。。。我更关心的是，无论是谁阅读文档，都能理解这个函数是如何被使用的。在

另一方面，如果我正在编写一个可以通过设计来处理各种各样的可调函数的效用函数，我可以采用以下两种方法之一：

1. 记录在某些条件下，会出现什么样的异常[例如：“如果iterable不能被多次迭代，则引发TypeError”]
2. 执行一些先发制人的参数处理，这将使函数与“仅一次”Iterable兼容。在

换言之，我试图使我的函数足够坚固以处理边缘情况，或者对其局限性非常坦率。在

再次重申：您所采用的方法没有任何问题，但是我认为这是“explicit is better than implicit”的一个例子：其中提到的“可重用的iterable”的文档是绝对准确的，但是形容词很容易被忽略。在

啊！在