cs.seq 20190103

Stuff to do with counters, sequences and iterables.

Stuff to do with counters, sequences and iterables.

Note that any function accepting an iterable will consume some or all of the derived iterator in the course of its function.

Function first(iterable)

Return the first item from an iterable; raise IndexError on empty iterables.

Function get0(iterable, default=None)

Return first element of an iterable, or the default.

Function imerge(*iters, **kw)

Merge an iterable of ordered iterables in order.

Parameters:

• iters: an iterable of iterators
• reverse: keyword parameter: if true, yield items in reverse order. This requires the iterables themselves to also be in reversed order.

This function relies on the source iterables being ordered and their elements being comparable, through slightly misordered iterables (for example, as extracted from web server logs) will produce only slightly misordered results, as the merging is done on the basis of the front elements of each iterable.

Function isordered(s, reverse=False, strict=False)

Test whether an iterable is ordered. Note that the iterable is iterated, so this is a destructive test for nonsequences.

Function last(iterable)

Return the last item from an iterable; raise IndexError on empty iterables.

Function onetomany(func)

A decorator for a method of a sequence to merge the results of passing every element of the sequence to the function, expecting multiple values back.

Example:

  class X(list):
        @onetomany
        def chars(self, item):
              return item
  strs = X(['Abc', 'Def'])
  all_chars = X.chars()

Function onetoone(func)

A decorator for a method of a sequence to merge the results of passing every element of the sequence to the function, expecting a single value back.

Example:

  class X(list):
        @onetoone
        def lower(self, item):
              return item.lower()
  strs = X(['Abc', 'Def'])
  lower_strs = X.lower()

Class Seq

A thread safe wrapper for itertools.count().

Function seq()

Return a new sequential value.

Class StatefulIterator

A trivial iterator which wraps another iterator to expose some tracking state.

This has 2 attributes:

• .it: the internal iterator which should yield (item,new_state)
• .state: the last state value from the internal iterator

The originating use case is resuse of an iterator by independent calls that are typically sequential, specificly the .read method of file like objects. Naive sequential reads require the underlying storage to locate the data on every call, even though the previous call has just performed this task for the previous read. Saving the iterator used from the preceeding call allows the iterator to pick up directly if the file offset hasn't been fiddled in the meantime.

Function tee(iterable, *Qs)

A generator yielding the items from an iterable which also copies those items to a series of queues.

Parameters:

• iterable: the iterable to copy
• Qs: the queues, objects accepting a .put method.

Note: the item is .put onto every queue before being yielded from this generator.

Function the(iterable, context=None)

Returns the first element of an iterable, but requires there to be exactly one.

Class TrackingCounter

A wrapper for a counter which can be incremented and decremented.

A facility is provided to wait for the counter to reach a specific value. The .inc and .dec methods also accept a tag argument to keep individual counts based on the tag to aid debugging.

TODO: add strict option to error and abort if any counter tries to go below zero.