Documentation: How to specify iterable with content type? about obiwan

[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