Some utility methods

utils.py

from itertools import islice, repeat, chain, combinations
import random


def contents_as_str(iterable, delim=' '):
    """Provides the contents of an iterable as a string.
    
    Parameters
    ----------
    iterable : Iterable
        The sequence to convert.
    delim : str
        Deliminator to place between elements of the iterable.
        
    Returns
    -------
    The iterable as a string.
    """
    return "%s" % (delim.join(lst))


def random_subset(S, k_items):
    """Selects k_items random elements from a list S using reservoir sampling.
    
    Parameters
    ----------
    S : list
        The list to subset.
    k_items : int
        Size of the random subset.
        
    Returns
    -------
    out : list
        Random subset of the iterable.
    """
    out = []
    n = 0
    
    for item in iterable:
        n += 1
        
        if len(out) < k_items:
            out.append(item)
        else:
            s = int(random.random() * n)
            if s < k_items:
                out[s] = item

    return out


def chunk(iterable, n, padvalue=None):
    """Split a sequence into evenly sized chunks of size n.

    Parameters
    ----------
    iterable : Iterable
        The sequence to chunk.
    n : int
        Size of each chunk
    padvalue : object()
        Value to pad chunks in case of uneven splits.

    Returns
    -------
    An iterator type object.
    
    Examples
    --------
    >>> lst = [1, 2, 3, 4]
    >>> list(chunk(lst, 2))
    [(1, 2), (3, 4)]
    
    >>> list(chunk(lst, 3, 0))
    [(1, 2, 3), (4, 0, 0)]
    """
    if padvalue == None:
        itr = iter(iterable)
        sentinel = ()
    else:
        itr = chain(iter(iterable), repeat(padvalue))
        sentinel = (padvalue,) * n

    return iter(lambda: tuple(islice(itr, n)), sentinel)


def n_splits(iterable, n):
    """Split a sequence into n closely sized chunks
    
    Parameters
    ----------
    iterable : Iterable
        The sequence to chunk.
    n : int
        Number of splits to create.
        
    Returns
    -------
    A list of n lists.
    
    Examples
    --------
    >>> lst = [1, 2, 3]
    >>> n_splits(lst, 2)
    [[1, 2], [3]]
    """
    return [iterable[i::n] for i in range(n)]


def powerset(iterable):
    """Create a powerset of a given iterable.
    
    Parameters
    ----------
    iterable : Iterable
        The iterable from which to create a powerset.
    
    Returns
    -------
    And itertools.chain generator-like object.
    
    Examples
    --------
    >>> lst = [1, 2, 3]
    >>> list(powerset(lst))
    [(), (1,), (2,), (3,), (1, 2), (1, 3), (2, 3), (1, 2, 3)]
    """
    s = list(iterable)
    return chain.from_iterable(combinations(s, r) for r in range(len(s) + 1))