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

pythonic_fp/iterables/merging.py

@@ -0,0 +1,146 @@
+# 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 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/merging.pyi

@@ -0,0 +1,38 @@
+# 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.
+
+from collections.abc import Iterable, Iterator
+from enum import auto, Enum
+
+__all__ = [
+    'MergeEnum',
+    'concat',
+    'merge',
+    'exhaust',
+    'blend',
+]
+
+class MergeEnum(Enum):
+    Concat = auto()
+    Merge = auto()
+    Exhaust = auto()
+
+def concat[D](*iterables: Iterable[D]) -> Iterator[D]: ...
+def merge[D](*iterables: Iterable[D], yield_partials: bool = False) -> Iterator[D]: ...
+def exhaust[D](*iterables: Iterable[D]) -> Iterator[D]: ...
+def blend[D](
+    *iterables: Iterable[D],
+    merge_enum: MergeEnum = MergeEnum.Concat,
+    yield_partials: bool = False,
+) -> Iterator[D]: ...

pythonic_fp_iterables-5.1.0.dist-info/METADATA

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: pythonic-fp-iterables
+Version: 5.1.0
+Summary: Library of functions for iterating iterables
+Keywords: iterables,iterators
+Author-email: "Geoffrey R. Scheller" <geoffrey@scheller.com>
+Requires-Python: >=3.13
+Description-Content-Type: text/x-rst
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+License-File: LICENSE
+Requires-Dist: pythonic-fp-fptools>=5.1.0
+Requires-Dist: pythonic-fp-gadgets>=3.0.1
+Requires-Dist: pythonic-fp-sentinels>=2.1.1
+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
+=================================
+
+PyPI project
+`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 ``foo`` we assume ``iter(foo) is foo``
+
+This PyPI project is part of of the
+`pythonic-fp namespace projects <https://github.com/grscheller/pythonic-fp/blob/main/README.md>`_
+
+Documentation
+-------------
+
+Documentation for this project is hosted on
+`GitHub Pages
+<https://grscheller.github.io/pythonic-fp/iterables/development/build/html>`_.
+
+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.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+pythonic_fp/iterables/__init__.py,sha256=UTde8stsDVG_5Z7fo37yiYeTu8fhkkv0QsQcQb_ixTU,1590
+pythonic_fp/iterables/drop_take.py,sha256=bHxVTJAY9vof570cFQNXNZZAUAtnWBDZgRu7df2aV9E,4707
+pythonic_fp/iterables/drop_take.pyi,sha256=6BtavkUHIxMJmJfcvDAnds9R29OXrCRkDK12jG575VY,1276
+pythonic_fp/iterables/folding.py,sha256=A4VoU7piryt6Fun6Inn1SJSr1IiN-aTqzeSs-mds5oQ,8604
+pythonic_fp/iterables/folding.pyi,sha256=BUslV-cn9eOxlYAF_3wz09TcHDbMATUL0uqU7IjJyAM,2035
+pythonic_fp/iterables/merging.py,sha256=tPVjw5Fr32gMTd4Uq3SKQPqdV9p5fs3xW-0elt8Yz8U,4462
+pythonic_fp/iterables/merging.pyi,sha256=5QBH0NEoqWQwCvWMPBFVoUOWAwmMYqj2W4s2b1rn9J0,1189
+pythonic_fp/iterables/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pythonic_fp_iterables-5.1.0.dist-info/licenses/LICENSE,sha256=IJMkVWQUVy-SonK6SMaMotDQ6Zb-lVi2bUTiGp1GUO8,10774
+pythonic_fp_iterables-5.1.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+pythonic_fp_iterables-5.1.0.dist-info/METADATA,sha256=FjgztLEfjG2VBYMtg_XUa0gyZTplavSKb523m746npY,2218
+pythonic_fp_iterables-5.1.0.dist-info/RECORD,,