Pythonのドキュメント：iterable何度か？ Pythonの機能を文書で

Question

は、私はそれがよりPython的と言って見つける：ではなく

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

を... ...

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

iが本当にlistである必要はありません

。 （ Fooは喜ん等 set、 tuple、上で動作する）という問題が発生します。ジェネレータは通常、1回の反復しか許可しません。 ほとんど機能は、単一パスのみを許可する発電機または反復可能オブジェクトでOKですが、いくつかはそうではありません。

一度しか反復できないジェネレータやものを受け入れることができない関数の場合、「一度しか反復できないもの」と言う明確な一貫したPython用語がありますか？

iterableとiteratorのPython用語集は、「あなたが運が良ければ多分もっと幸運だ」という定義を持っているようです。

Answer 1

が、私は少なくともぶっきらぼうではない、このための標準的な用語を知らないが、私が考える「反復可能な再利用可能な」あなたは短いフレーズが必要な場合は、全体のポイントになるだろう。あなたが複数回iを反復処理する必要がないように、実際には

、それはあなたの関数を構築することが一般的に可能です。または、繰り返し可能なリストからリストを作成し、必要な回数だけリストを反復することもできます。またはあなたは、イテレータの複数の独立した「コピー」を取得するためにitertools.teeを使用することができます。これにより、複数回使用する必要がある場合でも発電機を受け入れることができます。

Answer 2

これはおそらく、何よりもスタイルや好みの問題です...私は別のドキュメントを持っています：私はいつもプログラムの文脈で予想される入力に従ってドキュメントストリングを書いています。

例：私は辞書のキーの上に行くと私が書くその値を無視することを期待機能を書いた場合：

arg : a dictionary of... 

でもfor e in arg:た場合は、他の反復可能オブジェクトで動作します。関数がまだをうまくいくならば、私のコードのコンテキスト内で、私は気にしないので、私は、私は誰でもドキュメントを読み込みすると、その機能がを使用するためのものであるかを理解することがより気に...、そうすることを選びました。私はデザインによってイテレート可能オブジェクトの広い範囲に対応できるユーティリティ関数を書いていた場合一方

、私はこれらの2つの方法の1行く：

1. 文書例外の種類
2. が持つ機能の互換性になりますを扱ういくつかの先制引数を実行します。[「反復可能を複数回反復することができない場合はTypeErrorを上げる」EX]は、一定の条件の下で上昇したことになります'once-only' iterables。言い換えれば

は、私は、エッジケースを処理するのに十分な私の機能が固体にする、またはその限界に非常に率直であることをのどちらかにしてみてください。

もう一度取っておきたいアプローチに間違いはありませんが、「explicit is better than implicit」という文書の「再利用可能な繰り返し可能性」と書かれている文書は確かに正確ですが、形容詞は簡単に見過ごされる。

HTH！