pythonic-fp.iterables 4.0.0__py3-none-any.whl → 5.0.0__py3-none-any.whl

pythonic_fp/iterables/__init__.py

@@ -0,0 +1,39 @@
+# Copyright 2023-2024 Geoffrey R. Scheller
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Library of functions for iterating iterables.
+
++-----------+-------------------------------------------+
+| Module    | Description                               |
++===========+===========================================+
+| merging   | Concatenating and merging iterables       |
++-----------+-------------------------------------------+
+| drop_take | Dropping and taking values from iterables |
++-----------+-------------------------------------------+
+| folding   | 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 ``foobar`` we assume ``iter(foobar) is foobar``
+
+"""
+
+__author__ = 'Geoffrey R. Scheller'
+__copyright__ = 'Copyright (c) 2023-2025 Geoffrey R. Scheller'
+__license__ = 'Apache License 2.0'

pythonic_fp/iterables/drop_take.py

@@ -0,0 +1,177 @@
+# Copyright 2023-2025 Geoffrey R. Scheller
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Module pythonic_fp.iterables.drop_take"""
+
+from __future__ import annotations
+
+__author__ = 'Geoffrey R. Scheller'
+__copyright__ = 'Copyright (c) 2023-2025 Geoffrey R. Scheller'
+__license__ = 'Apache License 2.0'
+
+from collections.abc import Callable, Iterable, Iterator
+from pythonic_fp.gadgets.box import Box
+from .merging import concat
+
+__all__ = [
+    'drop',
+    'drop_while',
+    'take',
+    'take_while',
+    'take_split',
+    'take_while_split',
+]
+
+
+## dropping and taking
+
+
+def drop[D](iterable: Iterable[D], n: int) -> Iterator[D]:
+    """Drop the next n values from iterable.
+
+    :param iterable: iterable whose values are to be dropped
+    :param n: number of values to be dropped
+    :return: an iterator of the remaining values
+
+    """
+    iterator = iter(iterable)
+    for _ in range(n):
+        try:
+            next(iterator)
+        except StopIteration:
+            break
+    return iterator
+
+
+def drop_while[D](
+        iterable: Iterable[D],
+        pred: Callable[[D], bool]
+    ) -> Iterator[D]:
+    """Drop initial values from iterable while predicate is true.
+
+    :param iterable: iterable whose values are to be dropped
+    :param pred: Boolean valued function, the "predicate"
+    :return: an iterator beginning where pred returned false
+
+    """
+    iterator = iter(iterable)
+    while True:
+        try:
+            value = next(iterator)
+            if not pred(value):
+                iterator = concat((value,), iterator)
+                break
+        except StopIteration:
+            break
+    return iterator
+
+
+def take[D](iterable: Iterable[D], n: int) -> Iterator[D]:
+    """Return an iterator of up to n initial values of an iterable.
+
+    :param iterable: iterable providing the values to be taken
+    :param n: number of values to be dropped
+    :return: an iterator of up to n initial values from iterable
+
+    """
+    iterator = iter(iterable)
+    for _ in range(n):
+        try:
+            value = next(iterator)
+            yield value
+        except StopIteration:
+            break
+
+
+def take_while[D](
+        iterable: Iterable[D],
+        pred: Callable[[D], bool]
+    ) -> Iterator[D]:
+    """Yield values from iterable while predicate is true.
+
+    .. warning::
+        Risk of value loss if iterable is multiple referenced iterator.
+
+    :param iterable: iterable providing the values to be taken
+    :param pred: Boolean valued function, the "predicate"
+    :return: an Iterator of of values from iterable until predicate false
+
+    """
+    iterator = iter(iterable)
+    while True:
+        try:
+            value = next(iterator)
+            if pred(value):
+                yield value
+            else:
+                break
+        except StopIteration:
+            break
+
+
+def take_split[D](
+        iterable: Iterable[D],
+        n: int
+    ) -> tuple[Iterator[D], Iterator[D]]:
+    """Same as take except also return iterator of remaining values.
+
+    .. Warning::
+
+       **CONTRACT:** Do not access the second returned iterator until the
+       first one is exhausted.
+
+    :param iterable: iterable providing the values to be taken
+    :param n: maximum number of values to be taken
+    :return: an iterator of values taken and an iterator of remaining values
+
+    """
+    iterator = iter(iterable)
+    itn = take(iterator, n)
+
+    return itn, iterator
+
+
+def take_while_split[D](
+    iterable: Iterable[D], pred: Callable[[D], bool]
+) -> tuple[Iterator[D], Iterator[D]]:
+    """Yield values from iterable while predicate is true.
+
+    .. Warning::
+
+       **CONTRACT:** Do not access the second returned iterator until
+       the first one is exhausted.
+
+    :param iterable: iterable providing the values to be taken
+    :param pred: Boolean valued function
+    :return: tuple containing an iterator of values taken and an iterator of remaining values
+
+    """
+    def _take_while(
+        iterator: Iterator[D], pred: Callable[[D], bool], val: Box[D]
+    ) -> Iterator[D]:
+        while True:
+            try:
+                val.put(next(iterator))
+                if pred(val.get()):
+                    yield val.pop()
+                else:
+                    break
+            except StopIteration:
+                break
+
+    iterator = iter(iterable)
+    value: Box[D] = Box()
+    it_pred = _take_while(iterator, pred, value)
+
+    return (it_pred, concat(value, iterator))

pythonic_fp/iterables/folding.py

@@ -0,0 +1,294 @@
+# Copyright 2023-2025 Geoffrey R. Scheller
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Module pythonic_fp.iterables.folding"""
+
+from __future__ import annotations
+
+__author__ = 'Geoffrey R. Scheller'
+__copyright__ = 'Copyright (c) 2023-2025 Geoffrey R. Scheller'
+__license__ = 'Apache License 2.0'
+
+from collections.abc import Callable, Iterable, Iterator
+from typing import cast, Never
+from pythonic_fp.fptools.function import negate, swap
+from pythonic_fp.fptools.maybe import MayBe
+from pythonic_fp.singletons.novalue import NoValue
+from .drop_take import drop_while, take_while_split
+
+__all__ = [
+    'accumulate',
+    'reduce_left',
+    'fold_left',
+    'maybe_fold_left',
+    'sc_reduce_left',
+    'sc_reduce_right',
+]
+
+def accumulate[D, L](
+        iterable: Iterable[D],
+        f: Callable[[L, D], L],
+        initial: L | NoValue = NoValue()
+    ) -> Iterator[L]:
+    """Returns an iterator of partial fold values.
+
+    A 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
+
+    :param iterable: iterable to be folded
+    :param f: two parameter function, first parameter for accumulated value
+    :param initial: "optional" initial value to start fold
+    :return: an iterator of the intermediate fold values
+
+    """
+    it = iter(iterable)
+    try:
+        it0 = next(it)
+    except StopIteration:
+        if initial is NoValue():
+            return
+        yield cast(L, initial)
+    else:
+        if initial is not NoValue():
+            init = cast(L, initial)
+            yield init
+            acc = f(init, it0)
+            for ii in it:
+                yield acc
+                acc = f(acc, ii)
+            yield acc
+        else:
+            acc = cast(L, it0)  # in this case L = D
+            for ii in it:
+                yield acc
+                acc = f(acc, ii)
+            yield acc
+
+
+def reduce_left[D](
+        iterable: Iterable[D],
+        f: Callable[[D, D], D]
+    ) -> D | Never:
+    """Fold an iterable left with a function.
+
+    .. Warning::
+
+       This function never return if given an infinite iterable.
+
+    .. Warning::
+
+       This function does not catch or re-raises exceptions from ``f``.
+
+    :param iterable: iterable to be reduced (folded)
+    :param f: two parameter function, first parameter for accumulated value
+    :return: reduced value from the iterable
+    :raises StopIteration: when called on an empty iterable
+    :raises Exception: does not catch any exceptions from ``f``
+
+    """
+    it = iter(iterable)
+    try:
+        acc = next(it)
+    except StopIteration as exc:
+        msg = 'Attempt to reduce an empty iterable?'
+        raise StopIteration(msg) from exc
+
+    for v in it:
+        acc = f(acc, v)
+
+    return acc
+
+
+def fold_left[D, L](
+        iterable: Iterable[D],
+        f: Callable[[L, D], L],
+        initial: L
+    ) -> L | Never:
+    """Fold an iterable left with a function and initial value.
+
+    - 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
+
+    .. Warning::
+
+       This function never return if given an infinite iterable.
+
+    .. Warning::
+
+       This function does not catch any exceptions ``f`` may raise.
+
+    :param iterable: iterable to be folded
+    :param f: two parameter function, first parameter for accumulated value
+    :param initial: mandatory initial value to start fold
+    :return: the folded value
+
+    """
+    acc = initial
+    for v in iterable:
+        acc = f(acc, v)
+    return acc
+
+
+def maybe_fold_left[D, L](
+        iterable: Iterable[D],
+        f: Callable[[L, D], L],
+        initial: L | NoValue = NoValue()
+    ) -> MayBe[L] | Never:
+    """Folds an iterable left with an "optional" initial value..
+
+    - when an initial value is not given then ``L = D``
+    - if iterable empty and no ``initial`` value given, return ``MayBe()``
+
+    .. Warning::
+
+       This function never return if given an infinite iterable.
+
+    .. Warning::
+
+        This function returns a ``MayBe()`` when ``f`` raises any
+        exception what-so-ever. The exception is thrown away.
+
+    :param iterable: The iterable to be folded.
+    :param f: First argument is for the accumulated value.
+    :param initial: Mandatory initial value to start fold.
+    :return: MayBe of a successfully folded value, otherwise MayBe()
+
+    """
+    acc: L
+    it = iter(iterable)
+    if initial is NoValue():
+        try:
+            acc = cast(L, next(it))  # in this case L = D
+        except StopIteration:
+            return MayBe()
+    else:
+        acc = cast(L, initial)
+
+    for v in it:
+        try:
+            acc = f(acc, v)
+        except Exception:
+            return MayBe()
+
+    return MayBe(acc)
+
+
+def sc_reduce_left[D](
+        iterable: Iterable[D],
+        f: Callable[[D, D], D],
+        start: Callable[[D], bool] = (lambda d: True),
+        stop: Callable[[D], bool] = (lambda d: False),
+        include_start: bool = True,
+        include_stop: bool = True,
+    ) -> tuple[MayBe[D], Iterator[D]]:
+    """Short circuit version of a left reduce.
+
+    Useful for infinite iterables.
+
+    Behavior for default arguments will
+
+    - left reduce finite iterable
+    - start folding immediately
+    - continue folding until end (of a possibly infinite iterable)
+
+    :param iterable: iterable to be reduced from the left
+    :param f: two parameter function, first parameter for accumulated value
+    :param start: delay starting the fold until it returns true
+    :param stop: prematurely stop the fold when it returns true
+    :param include_start: if true, include fold starting value in fold
+    :param include_stop: if true, include stopping value in fold
+    :return: tuple of a MayBe of the folded value and iterator of remaining iterables
+
+    """
+    it_start = drop_while(iterable, negate(start))
+    if not include_start:
+        try:
+            next(it_start)
+        except StopIteration:
+            pass
+    it_reduce, it_rest = take_while_split(it_start, negate(stop))
+    mb_reduced = maybe_fold_left(it_reduce, f)
+    if include_stop:
+        if mb_reduced:
+            try:
+                last = next(it_rest)
+                mb_reduced = MayBe(f(mb_reduced.get(), last))
+            except StopIteration:
+                pass
+        else:
+            try:
+                last = next(it_rest)
+                mb_reduced = MayBe(last)
+            except StopIteration:
+                pass
+
+    return (mb_reduced, it_rest)
+
+
+def sc_reduce_right[D](
+        iterable: Iterable[D],
+        f: Callable[[D, D], D],
+        start: Callable[[D], bool] = (lambda d: False),
+        stop: Callable[[D], bool] = (lambda d: False),
+        include_start: bool = True,
+        include_stop: bool = True,
+    ) -> tuple[MayBe[D], Iterator[D]]:
+    """Short circuit version of a right reduce.
+
+    Useful for infinite and non-reversible iterables.
+
+    Behavior for default arguments will
+
+    - right reduce finite iterable
+    - start folding at end (of a possibly infinite iterable)
+    - continue reducing right until beginning
+
+    :param iterable: iterable to be reduced from the right
+    :param f: two parameter function, second parameter for accumulated value
+    :param start: delay starting the fold until it returns true
+    :param stop: prematurely stop the fold when it returns true
+    :param include_start: if true, include fold starting value in fold
+    :param include_stop: if true, include stopping value in fold
+    :return: tuple of a MayBe of the folded value and iterator of remaining iterables
+
+    """
+    it_start, it_rest = take_while_split(iterable, negate(start))
+    list1 = list(it_start)
+    if include_start:
+        try:
+            begin = next(it_rest)
+        except StopIteration:
+            pass
+        else:
+            list1.append(begin)
+
+    list1.reverse()
+    it_reduce, it_stop = take_while_split(list1, negate(stop))
+
+    mb_reduced = maybe_fold_left(it_reduce, swap(f))
+    if include_stop:
+        try:
+            end = next(it_stop)
+        except StopIteration:
+            pass
+        else:
+            if mb_reduced:
+                mb_reduced = MayBe(f(end, mb_reduced.get()))
+            else:
+                mb_reduced = MayBe(end)
+
+    return (mb_reduced, it_rest)

pythonic_fp/iterables/merging.py

@@ -0,0 +1,148 @@
+# Copyright 2023-2025 Geoffrey R. Scheller
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Module pythonic_fp.iterables.merging"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator
+from enum import auto, Enum
+
+__all__ = [
+    'MergeEnum',
+    'concat',
+    'merge',
+    'exhaust',
+    'blend',
+]
+
+class MergeEnum(Enum):
+    """Iterable Blending Enums.
+
+    - **MergeEnum.Concat:** Concatenate first to last
+    - **MergeEnum.Merge:** Merge until one is exhausted
+    - **MergeEnum.Exhaust:** Merge until all are exhausted
+
+    """
+    Concat = auto()
+    Merge = auto()
+    Exhaust = auto()
+
+
+def concat[D](*iterables: Iterable[D]) -> Iterator[D]:
+    """Sequentially concatenate multiple iterables together.
+
+    .. warning::
+        An infinite iterable will prevent subsequent iterables from
+        yielding any values.
+    
+    .. note::
+
+        Performant to the standard library's ``itertools.chain``.
+
+    :param iterables: iterables to concatenate
+    :return: iterator of concatenated values from the iterables
+
+    """
+    for iterator in map(lambda x: iter(x), iterables):
+        while True:
+            try:
+                value = next(iterator)
+                yield value
+            except StopIteration:
+                break
+
+
+def merge[D](
+        *iterables: Iterable[D],
+        yield_partials: bool = False
+    ) -> Iterator[D]:
+    """Merge together ``iterables`` until one is exhausted.
+
+    .. note::
+
+       When ``yield_partials`` is true, then any unmatched values from other iterables
+       already yielded when the first iterable is exhausted are yielded. This prevents
+       data lose if any of the iterables are iterators with external references.
+
+    :param iterables: iterables to merge until one gets exhausted
+    :param yield_partials: yield any unpaired yielded values from other iterables
+    :return: iterator of merged values from the iterables until one is exhausted
+
+    """
+    iter_list = list(map(lambda x: iter(x), iterables))
+    values = []
+    if (num_iters := len(iter_list)) > 0:
+        while True:
+            try:
+                for ii in range(num_iters):
+                    values.append(next(iter_list[ii]))
+                yield from values
+                values.clear()
+            except StopIteration:
+                break
+        if yield_partials:
+            yield from values
+
+
+def exhaust[D](*iterables: Iterable[D]) -> Iterator[D]:
+    """Merge together multiple iterables until all are exhausted.
+
+    :param iterables: iterables to exhaustively merge
+    :return: iterator of merged values from the iterables until all are exhausted
+
+    """
+    iter_list = list(map(lambda x: iter(x), iterables))
+    if (num_iters := len(iter_list)) > 0:
+        ii = 0
+        values = []
+        while True:
+            try:
+                while ii < num_iters:
+                    values.append(next(iter_list[ii]))
+                    ii += 1
+                yield from values
+                ii = 0
+                values.clear()
+            except StopIteration:
+                num_iters -= 1
+                if num_iters < 1:
+                    break
+                del iter_list[ii]
+
+        yield from values
+
+
+def blend[D](*iterables: Iterable[D],
+        merge_enum: MergeEnum = MergeEnum.Concat,
+        yield_partials: bool = False
+    ) -> Iterator[D]:
+    """Base merge behavior on name only parameters.
+
+    :param iterables: iterables to blend together
+    :param merge_enum: MergeEnum to determine merging behavior
+    :param yield_partials: yield yielded unpaired values from other iterables
+    :return: an iterator of type D
+    :raises ValueError: when an unknown MergeEnum is given
+
+    """
+    match merge_enum:
+        case MergeEnum.Concat:
+            return concat(*iterables)
+        case MergeEnum.Merge:
+            return merge(*iterables, yield_partials = yield_partials)
+        case MergeEnum.Exhaust:
+            return exhaust(*iterables)
+
+    raise ValueError('Unknown MergeEnum given')