[Python-ideas] Introduce collections.Reiterable

[Stephen J. Turnbull]

Neil Girdhar writes:

 > Most importantly, there's no sure *and* easy way to assert that the
 > input a function is reiterable, and so the silent breakages are
 > hard to discover.

But you haven't defined "reiterable" yet, except "it fixes the
breakage I've experienced".

"Reiterable" could mean that the same object can be passed to
iteration contexts freely, and in each one it will start from the
beginning and the context will receive the same sequence of objects
(in the same order).  Or order might not be guaranteed.  It might mean
that the same object once exhausted can be passed to another iteration
context and it will restart.  Or it might mean that the object
supports a rewind method that must be explicitly called, but can be
called even if the object hasn't been exhausted.  Or it might mean
that the object is clonable, and functions that iterate objects passed
into them must clone them unless they know that the object will never
be reiterated.

All of the above also have concurrent variations: in a threading
context, multiple threads have access to each object and might be
iterating with arbitrary timing.  (Eg, if a program is rewritten to
use threads, a sequential reiteration could easily become a
parallel/concurrent reiteration.)  Oh, another: AFAIK even
non-iterator iterables may change their content when iterated.  Eg,
weak containers: I forget if there are any iterables that allow
deletions and insertions in underlying containers, but in the case of
a weak ref deleting a ref elsewhere may cause the ref itself to
disappear.  Should "reiterable" provide any guarantees there?

 > Even if the user should be the one deciding what to do, the dev has
 > to be able to assert that the right thing was done.

But there's no such need *between user and dev*.  Assertions protect a
dev from *herself*.  Users do what they do, and devs either protect
themselves from user vagaries, or they don't.  If the dev wants to
protect herself from undesirable user choices, cloning an iterator in
Python should be cheap.  If it isn't, let's fix that.

Assertions are useful, indeed.  But in this case, where the assertion
itself is based on an undefined term as far as I can tell (I suspect
this is because different use cases actually want different
definitions), rather than an assertion the dev should treat herself
(as a writer of other modules) as a user.  Ie, she should protect
herself from herself in the same way by cloning the iterator (for
efficiency converting the iterable to an iterator then cloning).

Regards,