Python documentation: iterable many times?

Question

In documenting a Python function, I find it more Pythonic to say:

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

…rather than…

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

When i really doesn't need to be a list. (Foo will happily operate on a set, tuple, etc.) The problem is generators. Generators typically only allow 1 iteration. Most functions are OK with generators or iterables that only allow a single pass, but some are not.

For those functions that cannot accept generators/things that can only be iterated once, is there a clear, consistent Python term to say "thing that can only be iterated more than once"?

The Python glossary for iterable and iterator seem to have a "once, but maybe more if you're lucky" definition.

Answer 1

I don't know of a standard term for this, at least not offhand, but I think "reusable iterable" would get the point across if you need a short phrase.

In practice, it's generally possible to structure your function so that you don't need to iterate over i more than once. Alternatively, you can create a list out of the iterable and then iterate over the list as many times as you want; or you can use itertools.tee to get multiple independent "copies" of the iterator. That lets you accept a generator even if you do need to use it more than once.

Answer 2

This is probably more a matter of style and preference than anything else, yet... I have a different take on my documentation: I always write the docstring according to the expected input in the context of the program.

Example: if I wrote a function that expect to go over keys of a dictionary and ignore its values I write:

arg : a dictionary of...

even if for e in arg: would work with other iterables. I chose to do so, because within the context of my code, I don't care if the function would still work... I care more that whoever reads the documentation understand how that function is meant to be used.

On the other hand, if I am writing a utility function that can cope with a wide spectrum of iterables by design, I go one of these two ways:

1. document what kind of exception will be rose under certain conditions [ex: "Raise TypeError if the iterable can't be iterated more than once"]
2. perform some pre-emptive argument handling that will make the function compatible with 'once-only' iterables.

In other words, I try to either make my function solid enough to handle edge cases, or to be very outspoken on its limitations.

Again: there's nothing wrong with the approach you want to take, but I consider this one of the cases in which "explicit is better than implicit": a documentation in which is mentioned "reusable iterable" is definitively accurate, but the adjective could easily be overlooked.

HTH!