pythonic_fp.iterables API

Iterables Module

Module fp.iterables - Iterator related tools

Library of iterator related functions and enumerations.

  • Concatenating and merging iterables

  • Dropping and taking values from iterables

  • Reducing and accumulating iterables

  • Assumptions

    • iterables are not necessarily iterators

    • at all times iterator protocol is assumed to be followed

      • all iterators are assumed to be iterable

      • for all iterators foo we assume iter(foo) is foo

class pythonic_fp.iterables.FM(*values)

Types of iterable blending,

  • CONCAT: Concatenate first to last

  • MERGE: Merge until one is exhausted

  • EXHAUST: Merge until all are exhausted

pythonic_fp.iterables.accumulate(iterable, f, initial=NoValue(), /)

Returns an iterator of accumulated values.

  • pure Python version of standard library’s itertools.accumulate

  • function f does not default to addition (for typing flexibility)

  • begins accumulation with an optional initial value

Return type:

Iterator[L]

pythonic_fp.iterables.concat(*iterables)

Sequentially concatenate multiple iterables together.

  • pure Python version of standard library’s itertools.chain

  • iterator sequentially yields each iterable until all are exhausted

  • an infinite iterable will prevent subsequent iterables from yielding any values

  • performant to itertools.chain

Return type:

Iterator[D]

pythonic_fp.iterables.drop(iterable, n, /)

Drop the next n values from iterable.

Return type:

Iterator[D]

pythonic_fp.iterables.drop_while(iterable, pred, /)

Drop initial values from iterable while predicate is true.

Return type:

Iterator[D]

pythonic_fp.iterables.exhaust(*iterables)

Shuffle together multiple iterables until all are exhausted. Iterator yields until all iterables are exhausted.

Return type:

Iterator[D]

pythonic_fp.iterables.foldl(iterable, f, initial, /)

Folds an iterable left with a function and initial value.

  • traditional FP type order given for function f

  • does not catch any exceptions f may raise

  • like builtin sum for Python >=3.8 except

    • not restricted to __add__ for the folding function

    • initial value required, does not default to 0 for initial value

    • handles non-numeric data just find

  • never returns if iterable generates an infinite iterator

Return type:

Union[L, Never]

pythonic_fp.iterables.mb_fold_left(iterable, f, initial=NoValue())

Folds an iterable left with optional initial value.

  • traditional FP type order given for function f

  • when an initial value is not given then ~L = ~D

  • if iterable empty and no initial value given, return MB()

  • never returns if iterable generates an infinite iterator

Return type:

MayBe[L]

pythonic_fp.iterables.merge(*iterables, yield_partials=False)

Shuffle together the iterables until one is exhausted.

  • iterator yields until one of the iterables is exhausted

  • if yield_partials is true,

    • yield any unmatched yielded values from other iterables

    • prevents data lose

      • if any of the iterables are iterators with external references

Return type:

Iterator[D]

pythonic_fp.iterables.reduce_left(iterable, f, /)

Fold an iterable left with a function.

  • traditional FP type order given for function f

  • if iterable empty, StopIteration exception raised

  • does not catch any exceptions f may raise

  • never returns if iterable generates an infinite iterator

Return type:

Union[D, Never]

pythonic_fp.iterables.sc_reduce_left(iterable, f, /, start=<function '<lambda>'>, stop=<function '<lambda>'>, include_start=True, include_stop=True)

Short circuit version of a left reduce. Useful for infinite or iterables.

  • Behavior for default arguments will

    • left reduce finite iterable

    • start folding immediately

    • continue folding until end (of a possibly infinite iterable)

  • Callable start delays starting the left reduce

  • Callable stop prematurely stop the left reduce

Return type:

tuple[MayBe[D], Iterator[D]]

pythonic_fp.iterables.sc_reduce_right(iterable, f, /, start=<function '<lambda>'>, stop=<function '<lambda>'>, include_start=True, include_stop=True)

Short circuit version of a right reduce. Useful for infinite or non-reversible iterables.

  • Behavior for default arguments will

    • right reduce finite iterable

    • start reducing at end (of a possibly infinite iterable)

    • continue reducing right until beginning

  • Callable start prematurely starts the right reduce

  • Callable stop prematurely stops the right reduce

Return type:

tuple[MayBe[D], Iterator[D]]

pythonic_fp.iterables.take(iterable, n, /)

Return an iterator of up to n initial values of an iterable

Return type:

Iterator[D]

pythonic_fp.iterables.take_split(iterable, n, /)

Same as take except also return an iterator of the remaining values.

  • return a tuple of

    • an iterator of up to n initial values

    • an iterator of the remaining vales of the iterable

  • Contract: do not access second iterator until first is exhausted

Return type:

tuple[Iterator[D], Iterator[D]]

pythonic_fp.iterables.take_while(iterable, pred, /)

Yield values from iterable while predicate is true.

Warning

Risk of value loss if iterable is multiple referenced iterator.

Return type:

Iterator[D]

pythonic_fp.iterables.take_while_split(iterable, pred, /)

Yield values from iterable while predicate is true.

  • return a tuple of two iterators

    • first of initial values where predicate is true, followed by first to fail

    • second of the remaining values of the iterable after first failed value

  • Contract: do not access second iterator until first is exhausted

Return type:

tuple[Iterator[D], Iterator[D]]