py_itertools

shortfx.fxPython.py_itertools

shortfx - fxPython: Itertools Recipes Module

This module provides advanced iterator utility functions based on Python's itertools documentation recipes. It includes functions for: - Iterator manipulation (take, prepend, flatten, sliding_window) - Sequence generation (tabulate, repeatfunc, ncycles) - Unique element filtering (unique_justseen, unique_everseen) - Grouping and batching (grouper, roundrobin, batched) - Mathematical operations (polynomial_eval, matmul, convolve) - Prime number utilities (sieve, factor, is_prime, totient)

All functions are optimized for memory efficiency using lazy evaluation where possible. Based on: https://docs.python.org/3/library/itertools.html

Functions

all_equal(iterable, key=None)

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

Parameters:

Name	Type	Description	Default
iterable		The iterable.	required
key		Key function for comparison.	None

Returns:

Name	Type	Description
bool		True if all equal.

Usage Example

all_equal([1,1,1]) -> True

Source code in shortfx/fxPython/py_itertools.py

def all_equal(iterable, key=None):
    """
    Description: Returns True if all the elements are equal to each other.

    Args:
        iterable: The iterable.
        key: Key function for comparison.

    Returns:
        bool: True if all equal.

    Raises:
        (none)

    Usage Example:
        all_equal([1,1,1]) -> True
    """
    return len(take(2, groupby(iterable, key))) <= 1

consume(iterator, n=None)

Description: Advance the iterator n-steps ahead. If n is None, consume entirely.

Parameters:

Name	Type	Description	Default
iterator		The iterator to consume.	required
n	int or None	Number of steps or None.	None

Returns:

Type	Description
	None

Usage Example

consume(iter([1,2,3]), 2) # advances by 2

Source code in shortfx/fxPython/py_itertools.py

def consume(iterator, n=None):
    """
    Description: Advance the iterator n-steps ahead. If n is None, consume entirely.

    Args:
        iterator: The iterator to consume.
        n (int or None): Number of steps or None.

    Returns:
        None

    Raises:
        (none)

    Usage Example:
        consume(iter([1,2,3]), 2)  # advances by 2
    """
    if n is None:
        deque(iterator, maxlen=0)
    else:
        next(islice(iterator, n, n), None)

convolve(signal, kernel)

Description: Discrete linear convolution of two iterables. Equivalent to polynomial multiplication.

Parameters:

Name	Type	Description	Default
signal		The signal iterable.	required
kernel		The kernel iterable.	required

Returns:

Name	Type	Description
iterator		Convolution result.

Usage Example

list(convolve([1, -1, -20], [1, -3])) -> [1, -4, -17, 60]

Source code in shortfx/fxPython/py_itertools.py

def convolve(signal, kernel):
    """
    Description: Discrete linear convolution of two iterables. Equivalent to polynomial multiplication.

    Args:
        signal: The signal iterable.
        kernel: The kernel iterable.

    Returns:
        iterator: Convolution result.

    Raises:
        (none)

    Usage Example:
        list(convolve([1, -1, -20], [1, -3])) -> [1, -4, -17, 60]
    """
    kernel = tuple(kernel)[::-1]
    n = len(kernel)
    padded_signal = chain(repeat(0, n-1), signal, repeat(0, n-1))
    windowed_signal = sliding_window(padded_signal, n)
    return map(sumprod, repeat(kernel), windowed_signal)

factor(n)

Description: Prime factors of n.

Parameters:

Name	Type	Description	Default
n	int	Number to factor.	required

Returns:

Name	Type	Description
iterator		Iterator of prime factors.

Usage Example

list(factor(99)) -> [3, 3, 11]

Source code in shortfx/fxPython/py_itertools.py

def factor(n):
    """
    Description: Prime factors of n.

    Args:
        n (int): Number to factor.

    Returns:
        iterator: Iterator of prime factors.

    Raises:
        (none)

    Usage Example:
        list(factor(99)) -> [3, 3, 11]
    """
    for prime in sieve(isqrt(n) + 1):
        while not n % prime:
            yield prime
            n //= prime
            if n == 1:
                return
    if n > 1:
        yield n

first_true(iterable, default=False, predicate=None)

Description: Returns the first true value or the default if there is no true value.

Parameters:

Name	Type	Description	Default
iterable		The iterable.	required
default		Default value.	False
predicate		Function to check truthiness.	None

Returns:

Type	Description
	First true value or default.

Usage Example

first_true([0,1,2], predicate=bool) -> 1

Source code in shortfx/fxPython/py_itertools.py

def first_true(iterable, default=False, predicate=None):
    """
    Description: Returns the first true value or the default if there is no true value.

    Args:
        iterable: The iterable.
        default: Default value.
        predicate: Function to check truthiness.

    Returns:
        First true value or default.

    Raises:
        (none)

    Usage Example:
        first_true([0,1,2], predicate=bool) -> 1
    """
    return next(filter(predicate, iterable), default)

flatten(list_of_lists)

Description: Flatten one level of nesting.

Parameters:

Name	Type	Description	Default
list_of_lists		Iterable of iterables to flatten.	required

Returns:

Name	Type	Description
iterator		Flattened iterator.

Usage Example

list(flatten([[1,2], [3,4]])) -> [1,2,3,4]

Source code in shortfx/fxPython/py_itertools.py

def flatten(list_of_lists):
    """
    Description: Flatten one level of nesting.

    Args:
        list_of_lists: Iterable of iterables to flatten.

    Returns:
        iterator: Flattened iterator.

    Raises:
        (none)

    Usage Example:
        list(flatten([[1,2], [3,4]])) -> [1,2,3,4]
    """
    return chain.from_iterable(list_of_lists)

grouper(iterable, n, *, incomplete='fill', fillvalue=None)

Description: Collect data into non-overlapping fixed-length chunks or blocks.

Parameters:

Name	Type	Description	Default
iterable		The iterable.	required
n	int	Group size.	required
incomplete		How to handle incomplete groups ('fill', 'strict', 'ignore').	'fill'
fillvalue		Value to fill with.	None

Returns:

Name	Type	Description
iterator		Iterator of tuples.

Raises:

Type	Description
ValueError	If incomplete is not 'fill', 'strict', or 'ignore'.

Usage Example

list(grouper('ABCDEFG', 3, fillvalue='x')) -> [('A','B','C'), ('D','E','F'), ('G','x','x')]

Source code in shortfx/fxPython/py_itertools.py

def grouper(iterable, n, *, incomplete='fill', fillvalue=None):
    """
    Description: Collect data into non-overlapping fixed-length chunks or blocks.

    Args:
        iterable: The iterable.
        n (int): Group size.
        incomplete: How to handle incomplete groups ('fill', 'strict', 'ignore').
        fillvalue: Value to fill with.

    Returns:
        iterator: Iterator of tuples.

    Raises:
        ValueError: If incomplete is not 'fill', 'strict', or 'ignore'.

    Usage Example:
        list(grouper('ABCDEFG', 3, fillvalue='x')) -> [('A','B','C'), ('D','E','F'), ('G','x','x')]
    """
    iterators = [iter(iterable)] * n
    match incomplete:
        case 'fill':
            return zip_longest(*iterators, fillvalue=fillvalue)
        case 'strict':
            return zip(*iterators, strict=True)
        case 'ignore':
            return zip(*iterators)
        case _:
            raise ValueError('Expected fill, strict, or ignore')

iter_except(function, exception, first=None)

Description: Convert a call-until-exception interface to an iterator interface.

Parameters:

Name	Type	Description	Default
function		Function to call.	required
exception		Exception to catch.	required
first		Initial value.	None

Returns:

Name	Type	Description
iterator		Iterator from function calls.

Usage Example

list(iter_except(dict.popitem, KeyError)) # from a dict

Source code in shortfx/fxPython/py_itertools.py

def iter_except(function, exception, first=None):
    """
    Description: Convert a call-until-exception interface to an iterator interface.

    Args:
        function: Function to call.
        exception: Exception to catch.
        first: Initial value.

    Returns:
        iterator: Iterator from function calls.

    Raises:
        (none)

    Usage Example:
        list(iter_except(dict.popitem, KeyError))  # from a dict
    """
    with suppress(exception):
        if first is not None:
            yield first()
        while True:
            yield function()

iter_index(iterable, value, start=0, stop=None)

Description: Return indices where a value occurs in a sequence or iterable.

Parameters:

Name	Type	Description	Default
iterable		The iterable.	required
value		Value to find.	required
start	int	Start index.	0
stop	int or None	Stop index.	None

Returns:

Name	Type	Description
iterator		Iterator of indices.

Usage Example

list(iter_index('AABCADEAF', 'A')) -> [0, 1, 4, 7]

Source code in shortfx/fxPython/py_itertools.py

def iter_index(iterable, value, start=0, stop=None):
    """
    Description: Return indices where a value occurs in a sequence or iterable.

    Args:
        iterable: The iterable.
        value: Value to find.
        start (int): Start index.
        stop (int or None): Stop index.

    Returns:
        iterator: Iterator of indices.

    Raises:
        (none)

    Usage Example:
        list(iter_index('AABCADEAF', 'A')) -> [0, 1, 4, 7]
    """
    seq_index = getattr(iterable, 'index', None)
    if seq_index is None:
        iterator = islice(iterable, start, stop)
        for i, element in enumerate(iterator, start):
            if element is value or element == value:
                yield i
    else:
        stop = len(iterable) if stop is None else stop
        i = start
        with suppress(ValueError):
            while True:
                yield (i := seq_index(value, i, stop))
                i += 1

loops(n)

Description: Loop n times. Like range(n) but without creating integers.

Parameters:

Name	Type	Description	Default
n	int	Number of loops.	required

Returns:

Name	Type	Description
iterator		Iterator of None values.

Usage Example

for _ in loops(5): print("loop")

Source code in shortfx/fxPython/py_itertools.py

def loops(n):
    """
    Description: Loop n times. Like range(n) but without creating integers.

    Args:
        n (int): Number of loops.

    Returns:
        iterator: Iterator of None values.

    Raises:
        (none)

    Usage Example:
        for _ in loops(5): print("loop")
    """
    return repeat(None, n)

matmul(m1, m2)

Description: Multiply two matrices.

Parameters:

Name	Type	Description	Default
m1		First matrix.	required
m2		Second matrix.	required

Returns:

Name	Type	Description
iterator		Result matrix.

Usage Example

list(matmul([(7, 5), (3, 5)], [(2, 5), (7, 9)])) -> [(49, 80), (41, 60)]

Source code in shortfx/fxPython/py_itertools.py

def matmul(m1, m2):
    """
    Description: Multiply two matrices.

    Args:
        m1: First matrix.
        m2: Second matrix.

    Returns:
        iterator: Result matrix.

    Raises:
        (none)

    Usage Example:
        list(matmul([(7, 5), (3, 5)], [(2, 5), (7, 9)])) -> [(49, 80), (41, 60)]
    """
    n = len(m2[0])
    return batched(starmap(sumprod, product(m1, transpose(m2))), n)

multinomial(*counts)

Description: Number of distinct arrangements of a multiset.

Parameters:

Name	Type	Description	Default
*counts		Counts of each item.	()

Returns:

Name	Type	Description
int		Multinomial coefficient.

Usage Example

multinomial(5, 2, 2, 1, 1) -> 83160

Source code in shortfx/fxPython/py_itertools.py

def multinomial(*counts):
    """
    Description: Number of distinct arrangements of a multiset.

    Args:
        *counts: Counts of each item.

    Returns:
        int: Multinomial coefficient.

    Raises:
        (none)

    Usage Example:
        multinomial(5, 2, 2, 1, 1) -> 83160
    """
    return prod(map(comb, accumulate(counts), counts))

ncycles(iterable, n)

Description: Returns the sequence elements n times.

Parameters:

Name	Type	Description	Default
iterable		The iterable to cycle.	required
n	int	Number of cycles.	required

Returns:

Name	Type	Description
iterator		Iterator repeating the sequence n times.

Usage Example

list(ncycles([1,2], 3)) -> [1,2,1,2,1,2]

Source code in shortfx/fxPython/py_itertools.py

def ncycles(iterable, n):
    """
    Description: Returns the sequence elements n times.

    Args:
        iterable: The iterable to cycle.
        n (int): Number of cycles.

    Returns:
        iterator: Iterator repeating the sequence n times.

    Raises:
        (none)

    Usage Example:
        list(ncycles([1,2], 3)) -> [1,2,1,2,1,2]
    """
    return chain.from_iterable(repeat(tuple(iterable), n))

nth(iterable, n, default=None)

Description: Returns the nth item or a default value.

Parameters:

Name	Type	Description	Default
iterable		The iterable.	required
n	int	Index of item.	required
default		Default value if not found.	None

Returns:

Type	Description
	The nth item or default.

Usage Example

nth([1,2,3], 1) -> 2

Source code in shortfx/fxPython/py_itertools.py

def nth(iterable, n, default=None):
    """
    Description: Returns the nth item or a default value.

    Args:
        iterable: The iterable.
        n (int): Index of item.
        default: Default value if not found.

    Returns:
        The nth item or default.

    Raises:
        (none)

    Usage Example:
        nth([1,2,3], 1) -> 2
    """
    return next(islice(iterable, n, None), default)

polynomial_derivative(coefficients)

Description: Compute the first derivative of a polynomial.

Parameters:

Name	Type	Description	Default
coefficients		List of coefficients.	required

Returns:

Name	Type	Description
list		Derivative coefficients.

Usage Example

polynomial_derivative([1, -4, -17, 60]) -> [3, -8, -17]

Source code in shortfx/fxPython/py_itertools.py

def polynomial_derivative(coefficients):
    """
    Description: Compute the first derivative of a polynomial.

    Args:
        coefficients: List of coefficients.

    Returns:
        list: Derivative coefficients.

    Raises:
        (none)

    Usage Example:
        polynomial_derivative([1, -4, -17, 60]) -> [3, -8, -17]
    """
    n = len(coefficients)
    powers = reversed(range(1, n))
    return list(map(mul, coefficients, powers))

polynomial_eval(coefficients, x)

Description: Evaluate a polynomial at a specific value.

Parameters:

Name	Type	Description	Default
coefficients		List of coefficients.	required
x		Value to evaluate at.	required

Returns:

Type	Description
	float or int: Result.

Usage Example

polynomial_eval([1, -4, -17, 60], x=5) -> 0

Source code in shortfx/fxPython/py_itertools.py

def polynomial_eval(coefficients, x):
    """
    Description: Evaluate a polynomial at a specific value.

    Args:
        coefficients: List of coefficients.
        x: Value to evaluate at.

    Returns:
        float or int: Result.

    Raises:
        (none)

    Usage Example:
        polynomial_eval([1, -4, -17, 60], x=5) -> 0
    """
    n = len(coefficients)
    if not n:
        return type(x)(0)
    powers = map(pow, repeat(x), reversed(range(n)))
    return sumprod(coefficients, powers)

polynomial_from_roots(roots)

Description: Compute a polynomial's coefficients from its roots.

Parameters:

Name	Type	Description	Default
roots		List of roots.	required

Returns:

Name	Type	Description
list		Coefficients.

Usage Example

polynomial_from_roots([5, -4, 3]) -> [1, -4, -17, 60]

Source code in shortfx/fxPython/py_itertools.py

def polynomial_from_roots(roots):
    """
    Description: Compute a polynomial's coefficients from its roots.

    Args:
        roots: List of roots.

    Returns:
        list: Coefficients.

    Raises:
        (none)

    Usage Example:
        polynomial_from_roots([5, -4, 3]) -> [1, -4, -17, 60]
    """
    factors = zip(repeat(1), map(neg, roots))
    return list(reduce(convolve, factors, [1]))

powerset(iterable)

Description: Subsequences of the iterable from shortest to longest.

Parameters:

Name	Type	Description	Default
iterable		The iterable.	required

Returns:

Name	Type	Description
iterator		Iterator of tuples.

Usage Example

list(powerset([1,2,3])) -> [(), (1,), (2,), (3,), (1,2), (1,3), (2,3), (1,2,3)]

Source code in shortfx/fxPython/py_itertools.py

def powerset(iterable):
    """
    Description: Subsequences of the iterable from shortest to longest.

    Args:
        iterable: The iterable.

    Returns:
        iterator: Iterator of tuples.

    Raises:
        (none)

    Usage Example:
        list(powerset([1,2,3])) -> [(), (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))

prepend(value, iterable)

Description: Prepend a single value in front of an iterable.

Parameters:

Name	Type	Description	Default
value		The value to prepend.	required
iterable		The iterable to prepend to.	required

Returns:

Name	Type	Description
iterator		Iterator with value prepended.

Usage Example

list(prepend(1, [2, 3, 4])) -> [1, 2, 3, 4]

Cost: O(1) for creation, O(n) when consumed.

Source code in shortfx/fxPython/py_itertools.py

def prepend(value, iterable):
    """
    Description: Prepend a single value in front of an iterable.

    Args:
        value: The value to prepend.
        iterable: The iterable to prepend to.

    Returns:
        iterator: Iterator with value prepended.

    Raises:
        (none)

    Usage Example:
        list(prepend(1, [2, 3, 4])) -> [1, 2, 3, 4]

    **Cost:** O(1) for creation, O(n) when consumed.
    """
    return chain([value], iterable)

quantify(iterable, predicate=bool)

Description: Given a predicate that returns True or False, count the True results.

Parameters:

Name	Type	Description	Default
iterable		The iterable to check.	required
predicate		Function to apply.	bool

Returns:

Name	Type	Description
int		Count of True results.

Usage Example

quantify([1,2,3,4], lambda x: x > 2) -> 2

Source code in shortfx/fxPython/py_itertools.py

def quantify(iterable, predicate=bool):
    """
    Description: Given a predicate that returns True or False, count the True results.

    Args:
        iterable: The iterable to check.
        predicate: Function to apply.

    Returns:
        int: Count of True results.

    Raises:
        (none)

    Usage Example:
        quantify([1,2,3,4], lambda x: x > 2) -> 2
    """
    return sum(map(predicate, iterable))

repeatfunc(function, times=None, *args)

Description: Repeat calls to a function with specified arguments.

Parameters:

Name	Type	Description	Default
function		The function to call.	required
times	int or None	Number of times to repeat, or None for infinite.	None
*args		Arguments to pass to the function.	()

Returns:

Name	Type	Description
iterator		Iterator of function results.

Usage Example

list(repeatfunc(lambda: random.random(), 3))

Cost: O(1) per function call.

Source code in shortfx/fxPython/py_itertools.py

def repeatfunc(function, times=None, *args):
    """
    Description: Repeat calls to a function with specified arguments.

    Args:
        function: The function to call.
        times (int or None): Number of times to repeat, or None for infinite.
        *args: Arguments to pass to the function.

    Returns:
        iterator: Iterator of function results.

    Raises:
        (none)

    Usage Example:
        list(repeatfunc(lambda: random.random(), 3))

    **Cost:** O(1) per function call.
    """
    if times is None:
        return starmap(function, repeat(args))
    return starmap(function, repeat(args, times))

reshape(matrix, columns)

Description: Reshape a 2-D matrix to have a given number of columns.

Parameters:

Name	Type	Description	Default
matrix		2D matrix.	required
columns	int	Number of columns.	required

Returns:

Name	Type	Description
iterator		Reshaped matrix.

Usage Example

list(reshape([(0, 1), (2, 3), (4, 5)], 3)) -> [(0, 1, 2), (3, 4, 5)]

Source code in shortfx/fxPython/py_itertools.py

def reshape(matrix, columns):
    """
    Description: Reshape a 2-D matrix to have a given number of columns.

    Args:
        matrix: 2D matrix.
        columns (int): Number of columns.

    Returns:
        iterator: Reshaped matrix.

    Raises:
        (none)

    Usage Example:
        list(reshape([(0, 1), (2, 3), (4, 5)], 3)) -> [(0, 1, 2), (3, 4, 5)]
    """
    return batched(chain.from_iterable(matrix), columns, strict=True)

roundrobin(*iterables)

Description: Visit input iterables in a cycle until each is exhausted.

Parameters:

Name	Type	Description	Default
*iterables		The iterables.	()

Returns:

Name	Type	Description
iterator		Round-robin iterator.

Usage Example

list(roundrobin('ABC', 'D', 'EF')) -> ['A', 'D', 'E', 'B', 'F', 'C']

Source code in shortfx/fxPython/py_itertools.py

def roundrobin(*iterables):
    """
    Description: Visit input iterables in a cycle until each is exhausted.

    Args:
        *iterables: The iterables.

    Returns:
        iterator: Round-robin iterator.

    Raises:
        (none)

    Usage Example:
        list(roundrobin('ABC', 'D', 'EF')) -> ['A', 'D', 'E', 'B', 'F', 'C']
    """
    iterators = map(iter, iterables)
    for num_active in range(len(iterables), 0, -1):
        iterators = cycle(islice(iterators, num_active))
        yield from map(next, iterators)

sieve(n)

Description: Primes less than n.

Parameters:

Name	Type	Description	Default
n	int	Upper limit.	required

Returns:

Name	Type	Description
iterator		Iterator of primes.

Usage Example

list(sieve(30)) -> [2, 3, 5, 7, 11, 13, 17, 19, 23, 29]

Source code in shortfx/fxPython/py_itertools.py

def sieve(n):
    """
    Description: Primes less than n.

    Args:
        n (int): Upper limit.

    Returns:
        iterator: Iterator of primes.

    Raises:
        (none)

    Usage Example:
        list(sieve(30)) -> [2, 3, 5, 7, 11, 13, 17, 19, 23, 29]
    """
    if n > 2:
        yield 2
    data = bytearray((0, 1)) * (n // 2)
    for p in iter_index(data, 1, start=3, stop=isqrt(n) + 1):
        data[p*p : n : p+p] = bytes(len(range(p*p, n, p+p)))
    yield from iter_index(data, 1, start=3)

sliding_window(iterable, n)

Description: Collect data into overlapping fixed-length chunks or blocks.

Parameters:

Name	Type	Description	Default
iterable		The iterable.	required
n	int	Window size.	required

Returns:

Name	Type	Description
iterator		Iterator of tuples.

Usage Example

list(sliding_window('ABCDEFG', 4)) -> [('A','B','C','D'), ('B','C','D','E'), ...]

Source code in shortfx/fxPython/py_itertools.py

def sliding_window(iterable, n):
    """
    Description: Collect data into overlapping fixed-length chunks or blocks.

    Args:
        iterable: The iterable.
        n (int): Window size.

    Returns:
        iterator: Iterator of tuples.

    Raises:
        (none)

    Usage Example:
        list(sliding_window('ABCDEFG', 4)) -> [('A','B','C','D'), ('B','C','D','E'), ...]
    """
    iterator = iter(iterable)
    window = deque(islice(iterator, n - 1), maxlen=n)
    for x in iterator:
        window.append(x)
        yield tuple(window)

subslices(seq)

Description: Return all contiguous non-empty subslices of a sequence.

Parameters:

Name	Type	Description	Default
seq		The sequence.	required

Returns:

Name	Type	Description
iterator		Iterator of slices.

Usage Example

list(subslices('ABCD')) -> ['A', 'AB', 'ABC', 'ABCD', 'B', 'BC', 'BCD', 'C', 'CD', 'D']

Source code in shortfx/fxPython/py_itertools.py

def subslices(seq):
    """
    Description: Return all contiguous non-empty subslices of a sequence.

    Args:
        seq: The sequence.

    Returns:
        iterator: Iterator of slices.

    Raises:
        (none)

    Usage Example:
        list(subslices('ABCD')) -> ['A', 'AB', 'ABC', 'ABCD', 'B', 'BC', 'BCD', 'C', 'CD', 'D']
    """
    slices = starmap(slice, combinations(range(len(seq) + 1), 2))
    return map(getitem, repeat(seq), slices)

tabulate(function, start=0)

Description: Return function(0), function(1), ...

Parameters:

Name	Type	Description	Default
function		The function to apply.	required
start	int	Starting index.	0

Returns:

Name	Type	Description
iterator		Iterator of function applied to consecutive integers.

Usage Example

list(tabulate(lambda x: x**2, 3)) -> [9, 16, 25, ...]

Cost: O(1) per element generated.

Source code in shortfx/fxPython/py_itertools.py

def tabulate(function, start=0):
    """
    Description: Return function(0), function(1), ...

    Args:
        function: The function to apply.
        start (int): Starting index.

    Returns:
        iterator: Iterator of function applied to consecutive integers.

    Raises:
        (none)

    Usage Example:
        list(tabulate(lambda x: x**2, 3)) -> [9, 16, 25, ...]

    **Cost:** O(1) per element generated.
    """
    return map(function, count(start))

tail(n, iterable)

Description: Return an iterator over the last n items.

Parameters:

Name	Type	Description	Default
n	int	Number of last items.	required
iterable		The iterable.	required

Returns:

Name	Type	Description
iterator		Iterator of last n items.

Usage Example

list(tail(3, 'ABCDEFG')) -> ['E', 'F', 'G']

Source code in shortfx/fxPython/py_itertools.py

def tail(n, iterable):
    """
    Description: Return an iterator over the last n items.

    Args:
        n (int): Number of last items.
        iterable: The iterable.

    Returns:
        iterator: Iterator of last n items.

    Raises:
        (none)

    Usage Example:
        list(tail(3, 'ABCDEFG')) -> ['E', 'F', 'G']
    """
    return iter(deque(iterable, maxlen=n))

take(n, iterable)

Description: Return first n items of the iterable as a list.

Parameters:

Name	Type	Description	Default
n	int	Number of items to take.	required
iterable		The iterable to take from.	required

Returns:

Name	Type	Description
list		List of first n items.

Usage Example

take(3, [1,2,3,4,5]) -> [1,2,3]

Cost: O(n), where n is the number of items to take.

Source code in shortfx/fxPython/py_itertools.py

def take(n, iterable):
    """
    Description: Return first n items of the iterable as a list.

    Args:
        n (int): Number of items to take.
        iterable: The iterable to take from.

    Returns:
        list: List of first n items.

    Raises:
        (none)

    Usage Example:
        take(3, [1,2,3,4,5]) -> [1,2,3]

    **Cost:** O(n), where n is the number of items to take.
    """
    return list(islice(iterable, n))

totient(n)

Description: Count of natural numbers up to n that are coprime to n.

Parameters:

Name	Type	Description	Default
n	int	Number.	required

Returns:

Name	Type	Description
int		Totient value.

Usage Example

totient(12) -> 4

Source code in shortfx/fxPython/py_itertools.py

def totient(n):
    """
    Description: Count of natural numbers up to n that are coprime to n.

    Args:
        n (int): Number.

    Returns:
        int: Totient value.

    Raises:
        (none)

    Usage Example:
        totient(12) -> 4
    """
    for prime in set(factor(n)):
        n -= n // prime
    return n

transpose(matrix)

Description: Swap the rows and columns of a 2-D matrix.

Parameters:

Name	Type	Description	Default
matrix		2D matrix.	required

Returns:

Name	Type	Description
iterator		Transposed matrix.

Usage Example

list(transpose([(1, 2, 3), (11, 22, 33)])) -> [(1, 11), (2, 22), (3, 33)]

Source code in shortfx/fxPython/py_itertools.py

def transpose(matrix):
    """
    Description: Swap the rows and columns of a 2-D matrix.

    Args:
        matrix: 2D matrix.

    Returns:
        iterator: Transposed matrix.

    Raises:
        (none)

    Usage Example:
        list(transpose([(1, 2, 3), (11, 22, 33)])) -> [(1, 11), (2, 22), (3, 33)]
    """
    return zip(*matrix, strict=True)

unique(iterable, key=None, reverse=False)

Description: Yield unique elements in sorted order. Supports unhashable inputs.

Parameters:

Name	Type	Description	Default
iterable		The iterable.	required
key		Key function.	None
reverse	bool	Sort in reverse.	False

Returns:

Name	Type	Description
iterator		Unique sorted elements.

Usage Example

list(unique([[1, 2], [3, 4], [1, 2]])) -> [[1, 2], [3, 4]]

Source code in shortfx/fxPython/py_itertools.py

def unique(iterable, key=None, reverse=False):
    """
    Description: Yield unique elements in sorted order. Supports unhashable inputs.

    Args:
        iterable: The iterable.
        key: Key function.
        reverse (bool): Sort in reverse.

    Returns:
        iterator: Unique sorted elements.

    Raises:
        (none)

    Usage Example:
        list(unique([[1, 2], [3, 4], [1, 2]])) -> [[1, 2], [3, 4]]
    """
    sequenced = sorted(iterable, key=key, reverse=reverse)
    return unique_justseen(sequenced, key=key)

unique_everseen(iterable, key=None)

Description: Yield unique elements, preserving order. Remember all elements ever seen.

Parameters:

Name	Type	Description	Default
iterable		The iterable.	required
key		Key function.	None

Returns:

Name	Type	Description
iterator		Unique elements.

Usage Example

list(unique_everseen('AAAABBBCCDAABBB')) -> ['A', 'B', 'C', 'D']

Source code in shortfx/fxPython/py_itertools.py

def unique_everseen(iterable, key=None):
    """
    Description: Yield unique elements, preserving order. Remember all elements ever seen.

    Args:
        iterable: The iterable.
        key: Key function.

    Returns:
        iterator: Unique elements.

    Raises:
        (none)

    Usage Example:
        list(unique_everseen('AAAABBBCCDAABBB')) -> ['A', 'B', 'C', 'D']
    """
    seen = set()
    if key is None:
        for element in filterfalse(seen.__contains__, iterable):
            seen.add(element)
            yield element
    else:
        for element in iterable:
            k = key(element)
            if k not in seen:
                seen.add(k)
                yield element

unique_justseen(iterable, key=None)

Description: Yield unique elements, preserving order. Remember only the element just seen.

Parameters:

Name	Type	Description	Default
iterable		The iterable.	required
key		Key function.	None

Returns:

Name	Type	Description
iterator		Unique elements.

Usage Example

list(unique_justseen('AAAABBBCCDAABBB')) -> ['A', 'B', 'C', 'D', 'A', 'B']

Source code in shortfx/fxPython/py_itertools.py

def unique_justseen(iterable, key=None):
    """
    Description: Yield unique elements, preserving order. Remember only the element just seen.

    Args:
        iterable: The iterable.
        key: Key function.

    Returns:
        iterator: Unique elements.

    Raises:
        (none)

    Usage Example:
        list(unique_justseen('AAAABBBCCDAABBB')) -> ['A', 'B', 'C', 'D', 'A', 'B']
    """
    if key is None:
        return map(itemgetter(0), groupby(iterable))
    return map(next, map(itemgetter(1), groupby(iterable, key)))