Documentation: How to specify iterable with content type?

[AndydeCleyre]

How to specify that an item should be iterable, with the contents being a specific type? In the case I'm looking at, all the following should pass:

• list of strs
• tuple of strs
• odict_values of strs

etc.

[flying-sheep]

That’s the fundamental problem with library: In library code (where type annotations and -checkers are most useful), one rarely wants to define a function on basic types.

What use is a function that says it takes lists while in reality it takes indexable collections or even just iterables? Will you dive into the code to find out what it really needs? Then the type annotation is useless? Will you believe the annotation and convert your numpy.ndarray to a list? Then it’s harmful, because it made you do a useless operation.

It would make more sense to map them something like this:

• {str} = Collection[str] = __contains__(str) → bool & __len__ → int & __iter__() → Iterator[str]
• [str] = IndexedCollection[str] = Collection[str] & __getitem__(int) → str
• {str: bytes} = Mapping[str, bytes] = Collection[str] & __getitem__(str) → bytes (& maybe also keys(), values(), items())
• (str, int) = Tuple[str, int] = A fixed-length (possibly) heterogeneous tuple
• (str, ...) = Tuple[str, ...] = A variable-length, homogeneous tuple