Metadata-Version: 2.1
Name: cs.seq
Version: 20200914
Summary: Stuff to do with counters, sequences and iterables.
Home-page: https://bitbucket.org/cameron_simpson/css/commits/all
Author: Cameron Simpson
Author-email: cs@cskk.id.au
License: GNU General Public License v3 or later (GPLv3+)
Description: Stuff to do with counters, sequences and iterables.
        
        *Latest release 20200914*:
        New common_prefix_length and common_suffix_length for comparing prefixes and suffixes of sequences.
        
        Note that any function accepting an iterable
        will consume some or all of the derived iterator
        in the course of its function.
        
        ## Function `common_prefix_length(*seqs)`
        
        Return the length of the common prefix of sequences `seqs`.
        
        ## Function `common_suffix_length(*seqs)`
        
        Return the length of the common suffix of sequences `seqs`.
        
        ## 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.
        
        ### Method `TrackingCounter.__init__(self, value=0, name=None, lock=None)`
        
        Initialise the counter to `value` (default 0) with the optional `name`.
        
        ### Method `TrackingCounter.check(self)`
        
        Internal consistency check.
        
        ### Method `TrackingCounter.dec(self, tag=None)`
        
        Decrement the counter.
        Wake up any threads waiting for its new value.
        
        ### Method `TrackingCounter.inc(self, tag=None)`
        
        Increment the counter.
        Wake up any threads waiting for its new value.
        
        ### Method `TrackingCounter.wait(self, value)`
        
        Wait for the counter to reach the specified `value`.
        
        # Release Log
        
        
        
        *Release 20200914*:
        New common_prefix_length and common_suffix_length for comparing prefixes and suffixes of sequences.
        
        *Release 20190103*:
        Documentation update.
        
        *Release 20190101*:
        * New and UNTESTED class StatefulIterator to associate some externally visible state with an iterator.
        * Seq: accept optional `lock` parameter.
        
        *Release 20171231*:
        * Python 2 backport for imerge().
        * New tee function to duplicate an iterable to queues.
        * Function isordered() is now a test instead of an assertion.
        * Drop NamedTuple, NamedTupleClassFactory (unused).
        
        *Release 20160918*:
        * New function isordered() to test ordering of a sequence.
        * imerge: accept new `reverse` parameter for merging reversed iterables.
        
        *Release 20160828*:
        Modify DISTINFO to say "install_requires", fixes pypi requirements.
        
        *Release 20160827*:
        TrackingCounter: accept presupplied lock object. Python 3 exec fix.
        
        *Release 20150118*:
        metadata update
        
        *Release 20150111*:
        Initial PyPI release.
Keywords: python2,python3
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Description-Content-Type: text/markdown
