pythonic-fp.iterables 3.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')

{pythonic_fp_iterables-3.0.0.dist-info → pythonic_fp_iterables-5.0.0.dist-info}/METADATA

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
-Name: pythonic-fp.iterables
-Version: 3.0.0
-Summary: Module fp.iterables - Iterator related tools
+Name: pythonic-fp-iterables
+Version: 5.0.0
+Summary: Library of functions for iterating iterables.
 Keywords: iterables,iterators
 Author-email: "Geoffrey R. Scheller" <geoffrey@scheller.com>
 Requires-Python: >=3.12
-Description-Content-Type: text/markdown
+Description-Content-Type: text/x-rst
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Framework :: Pytest
 Classifier: Intended Audience :: Developers
@@ -14,38 +14,47 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Typing :: Typed
 License-File: LICENSE
-Requires-Dist: pythonic-fp.circulararray>=5.0.0
-Requires-Dist: pythonic-fp.containers >=2.0.0
-Requires-Dist: pythonic-fp.fptools >=3.0.0
-Project-URL: Changelog, https://grscheller.github.io/pythonic-fp-iterables/html/changelog.html
-Project-URL: Documentation, https://grscheller.github.io/pythonic-fp-iterables/html/
+Requires-Dist: pythonic-fp-fptools>=5.0.0
+Requires-Dist: pythonic-fp>=1.1.0
+Requires-Dist: pythonic-fp-singletons>=1.0.0
+Requires-Dist: pytest>=8.4.1 ; extra == "test"
+Project-URL: Changelog, https://github.com/grscheller/pythonic-fp-iterables/blob/main/CHANGELOG.rst
+Project-URL: Documentation, https://grscheller.github.io/pythonic-fp/iterables/development/build/html/releases.html
 Project-URL: Homepage, https://github.com/grscheller/pythonic-fp/blob/main/README.md
 Project-URL: Source, https://github.com/grscheller/pythonic-fp-iterables
+Provides-Extra: test
 
-# Pythonic FP - Tools for iterables
+Pythonic FP - Tools for iterables
+=================================
 
 PyPI project
-[pythonic-fp.iterators](https://pypi.org/project/pythonic-fp.iterables/)
-implementing a Python package of tools for iterables and iterators.
+`pythonic-fp.iterators <https://pypi.org/project/pythonic-fp.iterables>`_.
+
+Library of functions for iterating iterables.
 
 - 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 `my_iter` we assume `iter(my_iter) is my_iter`
+    - for all iterators ``foo`` we assume ``iter(foo) is foo``
 
-This PyPI project is part of of the grscheller
-[pythonic-fp namespace projects](https://github.com/grscheller/pythonic-fp/blob/main/README.md).
+This PyPI project is part of of the
+`pythonic-fp namespace projects <https://github.com/grscheller/pythonic-fp/blob/main/README.md>`_
 
-## Documentation
+Documentation
+-------------
 
-Documentation hosted on
-[GitHub Pages](https://grscheller.github.io/pythonic-fp-iterables/html).
+Documentation for this project is hosted on
+`GitHub Pages
+<https://grscheller.github.io/pythonic-fp/iterables/development/build/html>`_.
 
-## Copyright and License
+Copyright and License
+---------------------
 
 Copyright (c) 2023-2025 Geoffrey R. Scheller. Licensed under the Apache
 License, Version 2.0. See the LICENSE file for details.

pythonic_fp_iterables-5.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+pythonic_fp/iterables/__init__.py,sha256=gtTAk0cCZ4kjfx54hZcwURNXYg02BNr3nKcOP5gdJEk,1534
+pythonic_fp/iterables/drop_take.py,sha256=70K6q0DGumK0XHFgPCpLK-lLDfNTkBzzjb2P5uttEqM,4940
+pythonic_fp/iterables/folding.py,sha256=o3m7MNCWtlPoUsQUrXJ-xhrGsb3Nxp-iJJ7xJE5bbo0,8925
+pythonic_fp/iterables/merging.py,sha256=mhFgSuIFb64wq9gnNkk63zoh92T7lkWB16VQ2L8t3-4,4530
+pythonic_fp/iterables/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pythonic_fp_iterables-5.0.0.dist-info/licenses/LICENSE,sha256=IJMkVWQUVy-SonK6SMaMotDQ6Zb-lVi2bUTiGp1GUO8,10774
+pythonic_fp_iterables-5.0.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+pythonic_fp_iterables-5.0.0.dist-info/METADATA,sha256=kFDuTmQMieyCjmD-KmXzZy5970iL39BV-QXMEGaDcxA,2212
+pythonic_fp_iterables-5.0.0.dist-info/RECORD,,

pythonic_fp/iterables.py

@@ -1,455 +0,0 @@
-# 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 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``
-"""
-
-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 enum import auto, Enum
-from typing import cast, Never, TypeVar
-from pythonic_fp.containers.box import Box
-from pythonic_fp.containers.maybe import MayBe as MB
-from pythonic_fp.fptools.function import negate, swap
-from pythonic_fp.fptools.singletons import NoValue
-
-__all__ = [
-    'FM',
-    'concat',
-    'merge',
-    'exhaust',
-    'drop',
-    'drop_while',
-    'take',
-    'take_while',
-    'take_split',
-    'take_while_split',
-    'accumulate',
-    'foldl',
-    'mb_fold_left',
-    'reduce_left',
-    'sc_reduce_left',
-    'sc_reduce_right',
-]
-
-D = TypeVar('D')  # Needed only for pdoc documentation generation.
-L = TypeVar('L')  # Otherwise, ignored by both MyPy and Python.
-
-# Iterate over multiple iterables
-
-
-class FM(Enum):
-    """Types of iterable blending,
-
-    - **CONCAT:** Concatenate first to last
-    - **MERGE:** Merge until one is exhausted
-    - **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.
-
-    - 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``
-    """
-    for iterator in map(lambda x: iter(x), iterables):
-        while True:
-            try:
-                value = next(iterator)
-                yield value
-            except StopIteration:
-                break
-
-
-def exhaust[D](*iterables: Iterable[D]) -> Iterator[D]:
-    """Shuffle together multiple iterables until all are exhausted.
-    Iterator yields until all iterables 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 merge[D](*iterables: Iterable[D], yield_partials: bool = False) -> Iterator[D]:
-    """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
-    """
-    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
-
-
-## dropping and taking
-
-
-def drop[D](iterable: Iterable[D], n: int, /) -> Iterator[D]:
-    """Drop the next ``n`` values from ``iterable``."""
-    it = iter(iterable)
-    for _ in range(n):
-        try:
-            next(it)
-        except StopIteration:
-            break
-    return it
-
-
-def drop_while[D](iterable: Iterable[D], pred: Callable[[D], bool], /) -> Iterator[D]:
-    """Drop initial values from ``iterable`` while predicate is true."""
-    it = iter(iterable)
-    while True:
-        try:
-            value = next(it)
-            if not pred(value):
-                it = concat((value,), it)
-                break
-        except StopIteration:
-            break
-    return it
-
-
-def take[D](iterable: Iterable[D], n: int, /) -> Iterator[D]:
-    """Return an iterator of up to ``n`` initial values of an iterable"""
-    it = iter(iterable)
-    for _ in range(n):
-        try:
-            value = next(it)
-            yield value
-        except StopIteration:
-            break
-
-
-def take_split[D](iterable: Iterable[D], n: int, /) -> tuple[Iterator[D], Iterator[D]]:
-    """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
-    """
-    it = iter(iterable)
-    itn = take(it, n)
-
-    return itn, it
-
-
-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.
-    """
-    it = iter(iterable)
-    while True:
-        try:
-            value = next(it)
-            if pred(value):
-                yield value
-            else:
-                break
-        except StopIteration:
-            break
-
-
-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.
-
-    - 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
-    """
-
-    def _take_while(
-        it: Iterator[D], pred: Callable[[D], bool], val: Box[D]
-    ) -> Iterator[D]:
-        while True:
-            try:
-                val.put(next(it))
-                if pred(val.get()):
-                    yield val.pop()
-                else:
-                    break
-            except StopIteration:
-                break
-
-    it = iter(iterable)
-    value: Box[D] = Box()
-    it_pred = _take_while(it, pred, value)
-
-    return (it_pred, concat(value, it))
-
-
-## reducing and accumulating
-
-
-def accumulate[D, L](
-    iterable: Iterable[D], f: Callable[[L, D], L], initial: L | NoValue = NoValue(), /
-) -> Iterator[L]:
-    """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
-    """
-    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.
-
-    - 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
-    """
-    it = iter(iterable)
-    try:
-        acc = next(it)
-    except StopIteration as exc:
-        msg = 'Attemped to reduce an empty iterable.'
-        raise StopIteration(msg) from exc
-
-    for v in it:
-        acc = f(acc, v)
-
-    return acc
-
-
-def foldl[D, L](
-    iterable: Iterable[D], f: Callable[[L, D], L], initial: L, /
-) -> L | Never:
-    """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
-    """
-    acc = initial
-    for v in iterable:
-        acc = f(acc, v)
-    return acc
-
-
-def mb_fold_left[L, D](
-    iterable: Iterable[D], f: Callable[[L, D], L], initial: L | NoValue = NoValue()
-) -> MB[L]:
-    """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
-    """
-    acc: L
-    it = iter(iterable)
-    if initial is NoValue():
-        try:
-            acc = cast(L, next(it))  # in this case L = D
-        except StopIteration:
-            return MB()
-    else:
-        acc = cast(L, initial)
-
-    for v in it:
-        try:
-            acc = f(acc, v)
-        except Exception:
-            return MB()
-
-    return MB(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[MB[D], Iterator[D]]:
-    """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
-    """
-    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 = mb_fold_left(it_reduce, f)
-    if include_stop:
-        if mb_reduced:
-            try:
-                last = next(it_rest)
-                mb_reduced = MB(f(mb_reduced.get(), last))
-            except StopIteration:
-                pass
-        else:
-            try:
-                last = next(it_rest)
-                mb_reduced = MB(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[MB[D], Iterator[D]]:
-    """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
-    """
-    it_start, it_rest = take_while_split(iterable, negate(start))
-    l1 = list(it_start)
-    if include_start:
-        try:
-            begin = next(it_rest)
-        except StopIteration:
-            pass
-        else:
-            l1.append(begin)
-
-    l1.reverse()
-    it_reduce, it_stop = take_while_split(l1, negate(stop))
-
-    mb_reduced = mb_fold_left(it_reduce, swap(f))
-    if include_stop:
-        try:
-            end = next(it_stop)
-        except StopIteration:
-            pass
-        else:
-            if mb_reduced:
-                mb_reduced = MB(f(end, mb_reduced.get()))
-            else:
-                mb_reduced = MB(end)
-
-    return (mb_reduced, it_rest)

pythonic_fp_iterables-3.0.0.dist-info/RECORD

@@ -1,5 +0,0 @@
-pythonic_fp/iterables.py,sha256=Si4a4JcJhrStvpxqe8msaqiskcgrb3D8xJP2oN-6VG8,13194
-pythonic_fp_iterables-3.0.0.dist-info/licenses/LICENSE,sha256=IJMkVWQUVy-SonK6SMaMotDQ6Zb-lVi2bUTiGp1GUO8,10774
-pythonic_fp_iterables-3.0.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
-pythonic_fp_iterables-3.0.0.dist-info/METADATA,sha256=9vZd4-jSvYbAXdXXSo6UwZHcLgrSEprn2J6cgyqUkeA,2059
-pythonic_fp_iterables-3.0.0.dist-info/RECORD,,