adafruit_itertools

Python’s itertools adapted for CircuitPython by Dave Astels

Copyright 2001-2019 Python Software Foundation; All Rights Reserved

  • Author(s): The PSF and Dave Astels

Implementation Notes

Hardware:

Software and Dependencies:

adafruit_itertools.adafruit_itertools.accumulate(iterable, func=<function <lambda>>)

Make an iterator that returns accumulated sums, or accumulated results of other binary functions (specified via the optional func argument). If func is supplied, it should be a function of two arguments that returns a value. Elements of the input iterable may be any type that can be accepted as arguments to func. (For example, with the default operation of addition, elements may be any addable type including Decimal or Fraction.) If the input iterable is empty, the output iterable will also be empty.

Parameters:
  • iterable – the source of values to be accumulated
  • func – the function to combine the accumulated value with the next one
adafruit_itertools.adafruit_itertools.chain(*iterables)

Make an iterator that returns elements from the first iterable until it is exhausted, then proceeds to the next iterable, until all of the iterables are exhausted. Used for treating consecutive sequences as a single sequence.

Parameters:p – a list of iterable from which to yield values
adafruit_itertools.adafruit_itertools.chain_from_iterable(iterables)

Alternate constructor for chain(). Gets chained inputs from a single iterable argument that is evaluated lazily.

Parameters:iterables – an iterable of iterables
adafruit_itertools.adafruit_itertools.combinations(iterable, r)

Return r length subsequences of elements from the input iterable. Combinations are emitted in lexicographic sort order. So, if the input iterable is sorted, the combination tuples will be produced in sorted order.

Elements are treated as unique based on their position, not on their value. So if the input elements are unique, there will be no repeat values in each combination.

Parameters:
  • iterable – the iterable containing the the items to combine
  • r – the length of the resulting combinations
adafruit_itertools.adafruit_itertools.combinations_with_replacement(iterable, r)

Return r length subsequences of elements from the input iterable allowing individual elements to be repeated more than once.

Combinations are emitted in lexicographic sort order. So, if the input iterable is sorted, the combination tuples will be produced in sorted order.

Elements are treated as unique based on their position, not on their value. So if the input elements are unique, the generated combinations will also be unique.

Parameters:
  • iterable – the iterable containing the the items to combine
  • r – the length of the resulting combinations
adafruit_itertools.adafruit_itertools.compress(data, selectors)

Make an iterator that filters elements from data returning only those that have a corresponding element in selectors that evaluates to True. Stops when either the data or selectors iterables has been exhausted.

Parameters:
  • data – the source of values
  • selector – the source of selection values
adafruit_itertools.adafruit_itertools.count(start=0, step=1)

Make an iterator that returns evenly spaced values starting with number start. Often used as an argument to map() to generate consecutive data points. Also, used with zip() to add sequence numbers.

Parameters:
  • start – the initial value of the sequence
  • step – how far apart subsequent values are
adafruit_itertools.adafruit_itertools.cycle(p)

Make an iterator returning elements from the iterable and saving a copy of each. When the iterable is exhausted, return elements from the saved copy. Repeats indefinitely.

Parameters:p – the iterable from which to yield elements
adafruit_itertools.adafruit_itertools.dropwhile(predicate, iterable)

Make an iterator that drops elements from the iterable as long as the predicate is true; afterwards, returns every element. Note, the iterator does not produce any output until the predicate first becomes false, so it may have a lengthy start-up time.

Parameters:
  • predicate – used to test each element until it returns False
  • iterable – source of values
adafruit_itertools.adafruit_itertools.filterfalse(predicate, iterable)

Make an iterator that filters elements from iterable returning only those for which the predicate is False. If predicate is None, return the items that are false.

Parameters:
  • predicate – used to test each value
  • iterable – source of values
class adafruit_itertools.adafruit_itertools.groupby(iterable, key=None)

Make an iterator that returns consecutive keys and groups from the

iterable. The key is a function computing a key value for each element. If not specified or is None, key defaults to an identity function and returns the element unchanged. Generally, the iterable needs to already be sorted on the same key function.

The operation of groupby() is similar to the uniq filter in Unix. It generates a break or new group every time the value of the key function changes (which is why it is usually necessary to have sorted the data using the same key function). That behavior differs from SQL’s GROUP BY which aggregates common elements regardless of their input order.

The returned group is itself an iterator that shares the underlying iterable with groupby(). Because the source is shared, when the groupby() object is advanced, the previous group is no longer visible. So, if that data is needed later, it should be stored as a list.

Parameters:
  • iterable – the source of values
  • key – the key computation function (default is None)
adafruit_itertools.adafruit_itertools.islice(p, start, stop=(), step=1)

Make an iterator that returns selected elements from the iterable. If start is non-zero and stop is unspecified, then the value for start is used as end, and start is taken to be 0. Thus the supplied value specifies how many elements are to be generated, starting the the first one.If stop is specified, then elements from iterable are skipped until start is reached. Afterward, elements are returned consecutively unless step is set higher than one which results in items being skipped. If stop is None, then iteration continues until iterable is exhausted, if at all; otherwise, it stops at the specified position. If stop is specified and is not None, and is not greater than start then nothing is returned. Unlike regular slicing, islice() does not support negative values for start, stop, or step. Can be used to extract related fields from data where the internal structure has been flattened (for example, a multi-line report may list a name field on every third line).

Parameters:
  • p – the iterator items come from
  • start – the index of the first item
  • stop – the index one past the final item, None (the default) means no end
  • step – how far to move to subsequent items (default is 1)
adafruit_itertools.adafruit_itertools.permutations(iterable, r=None)

Return successive r length permutations of elements in the iterable.

If r is not specified or is None, then r defaults to the length of the iterable and all possible full-length permutations are generated.

Permutations are emitted in lexicographic sort order. So, if the input iterable is sorted, the permutation tuples will be produced in sorted order.

Elements are treated as unique based on their position, not on their value. So if the input elements are unique, there will be no repeat values in each permutation.

Parameters:
  • iterable – the source of values
  • r – the permutation length
adafruit_itertools.adafruit_itertools.product(*args, r=1)

Cartesian product of input iterables.

Roughly equivalent to nested for-loops in a generator expression. For example, product(A, B) returns the same as ((x,y) for x in A for y in B).

The nested loops cycle like an odometer with the rightmost element advancing on every iteration. This pattern creates a lexicographic ordering so that if the input’s iterables are sorted, the product tuples are emitted in sorted order.

To compute the product of an iterable with itself, specify the number of repetitions with the optional repeat keyword argument. For example, product(A, repeat=4) means the same as product(A, A, A, A).

Parameters:
  • args – sources of values
  • r – number of times to duplicate the (single) arg for taking a product with itself (default is 1)
adafruit_itertools.adafruit_itertools.repeat(el, n=None)

Make an iterator that returns object over and over again. Runs indefinitely unless the times argument is specified. Used as argument to map() for invariant parameters to the called function. Also used with zip() to create an invariant part of a tuple record.

Parameters:
  • el – the object to yield
  • n – the number of time to yield, None (the default) means infinitely.
adafruit_itertools.adafruit_itertools.starmap(function, iterable)

Make an iterator that computes the function using arguments obtained from the iterable. Used instead of map() when argument parameters are already grouped in tuples from a single iterable (the data has been “pre-zipped”). The difference between map() and starmap() parallels the distinction between function(a,b) and function(*c).

Parameters:
  • function – the function to apply
  • iterable – where groups of arguments come from
adafruit_itertools.adafruit_itertools.takewhile(predicate, iterable)

Make an iterator that returns elements from the iterable as long as the predicate is true.

Parameters:
  • predicate – used to test values
  • iterable – source of values
adafruit_itertools.adafruit_itertools.tee(iterable, n=2)

Return n independent iterators from a single iterable.

Parameters:
  • iterable – the iterator from which to make iterators.
  • n – the number of iterators to make (default is 2)
adafruit_itertools.adafruit_itertools.zip_longest(*args, fillvalue=None)

Make an iterator that aggregates elements from each of the iterables. If the iterables are of uneven length, missing values are filled-in with fillvalue. Iteration continues until the longest iterable is exhausted.

Parameters:
  • args – the iterables to combine
  • fillvalue – value to fill in those missing from shorter iterables

adafruit_itertools_extras

Extras for Python itertools adapted for CircuitPython by Dave Astels

This module contains an extended toolset using the existing itertools as building blocks.

The extended tools offer the same performance as the underlying toolset. The superior memory performance is kept by processing elements one at a time rather than bringing the whole iterable into memory all at once. Code volume is kept small by linking the tools together in a functional style which helps eliminate temporary variables. High speed is retained by preferring “vectorized” building blocks over the use of for-loops and generators which incur interpreter overhead.

Copyright 2001-2019 Python Software Foundation; All Rights Reserved

  • Author(s): The PSF and Dave Astels

Implementation Notes

Based on code from the offical Python documentation.

Hardware:

Software and Dependencies:

adafruit_itertools.adafruit_itertools_extras.all_equal(iterable)

Returns True if all the elements are equal to each other.

Parameters:iterable – source of values
adafruit_itertools.adafruit_itertools_extras.dotproduct(vec1, vec2)

Compute the dot product of two vectors.

Parameters:
  • vec1 – the first vector
  • vec2 – the second vector
adafruit_itertools.adafruit_itertools_extras.first_true(iterable, default=False, pred=None)

Returns the first true value in the iterable.

If no true value is found, returns default

If pred is not None, returns the first item for which pred(item) is true.

Parameters:
  • iterable – source of values
  • default – the value to return if no true value is found (default is False)
  • pred – if not None test the result of applying pred to each value instead of the values themselves (default is None)
adafruit_itertools.adafruit_itertools_extras.flatten(iterable_of_iterables)

Flatten one level of nesting.

Parameters:iterable_of_iterables – a sequence of iterables to flatten
adafruit_itertools.adafruit_itertools_extras.grouper(iterable, n, fillvalue=None)

Collect data into fixed-length chunks or blocks.

Parameters:
  • iterable – source of values
  • n – chunk size
  • fillvalue – value to use for filling out the final chunk. Defaults to None.
adafruit_itertools.adafruit_itertools_extras.iter_except(func, exception)

Call a function repeatedly, yielding the results, until exception is raised.

Converts a call-until-exception interface to an iterator interface. Like builtins.iter(func, sentinel) but uses an exception instead of a sentinel to end the loop.

Examples

iter_except(functools.partial(heappop, h), IndexError) # priority queue iterator iter_except(d.popitem, KeyError) # non-blocking dict iterator iter_except(d.popleft, IndexError) # non-blocking deque iterator iter_except(q.get_nowait, Queue.Empty) # loop over a producer Queue iter_except(s.pop, KeyError) # non-blocking set iterator

Parameters:
  • func – the function to call repeatedly
  • exception – the exception upon which to stop
adafruit_itertools.adafruit_itertools_extras.ncycles(iterable, n)

Returns the sequence elements a number of times.

Parameters:
  • iterable – the source of values
  • n – how many time to repeal the values
adafruit_itertools.adafruit_itertools_extras.nth(iterable, n, default=None)

Returns the nth item or a default value.

Parameters:
  • iterable – the source of values
  • n – the index of the item to fetch, starts at 0
adafruit_itertools.adafruit_itertools_extras.padnone(iterable)

Returns the sequence elements and then returns None indefinitely.

Useful for emulating the behavior of the built-in map() function.

Parameters:iterable – the source of initial values
adafruit_itertools.adafruit_itertools_extras.pairwise(iterable)

Pair up valuesin the iterable.

Parameters:iterable – source of values
adafruit_itertools.adafruit_itertools_extras.partition(pred, iterable)

Use a predicate to partition entries into false entries and true entries.

Parameters:
  • pred – the predicate that divides the values
  • iterable – source of values
adafruit_itertools.adafruit_itertools_extras.prepend(value, iterator)

Prepend a single value in front of an iterator

Parameters:
  • value – the value to prepend
  • iterator – the iterator to which to prepend
adafruit_itertools.adafruit_itertools_extras.quantify(iterable, pred=<class 'bool'>)

Count how many times the predicate is true.

Parameters:
  • iterable – source of values
  • pred – the predicate whose result is to be quantified when applied to all values in iterable. Defaults to bool()
adafruit_itertools.adafruit_itertools_extras.repeatfunc(func, times=None, *args)

Repeat calls to func with specified arguments.

Example: repeatfunc(random.random)

Parameters:
  • func – the function to be called
  • times – the number of times to call it: size of the resulting iterable None means infinitely. Default is None.
adafruit_itertools.adafruit_itertools_extras.roundrobin(*iterables)

Return an iterable created by repeatedly picking value from each argument in order.

Parameters:args – the iterables to pick from
adafruit_itertools.adafruit_itertools_extras.tabulate(function, start=0)

Apply a function to a sequence of consecutive integers.

Parameters:
  • function – the function of one integer argument
  • start – optional value to start at (default is 0)
adafruit_itertools.adafruit_itertools_extras.tail(n, iterable)

Return an iterator over the last n items

Parameters:
  • n – how many values to return
  • iterable – the source of values
adafruit_itertools.adafruit_itertools_extras.take(n, iterable)

Return first n items of the iterable as a list

Parameters:
  • n – how many values to take
  • iterable – the source of values