pythonic-fp.iterables 5.1.1__py3-none-any.whl → 5.1.3__py3-none-any.whl

pythonic_fp/iterables/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2023-2024 Geoffrey R. Scheller
+# Copyright 2023-2026 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.
@@ -13,30 +13,33 @@
 # limitations under the License.
 
 """
-Library of functions for iterating iterables
-============================================
+Tools for iterables
+-------------------
 
-+-----------+-------------------------------------------+
-| Module    | Description                               |
-+===========+===========================================+
-| merging   | Concatenating and merging iterables       |
-+-----------+-------------------------------------------+
-| drop_take | Dropping and taking values from iterables |
-+-----------+-------------------------------------------+
-| folding   | Reducing and accumulating iterables       |
-+-----------+-------------------------------------------+
+.. admonition:: Library of functions for iterating iterables
 
-Assumptions
------------
+    +-----------+-------------------------------------------+
+    | Module    | Description                               |
+    +===========+===========================================+
+    | merging   | Concatenating and merging iterables       |
+    +-----------+-------------------------------------------+
+    | drop_take | Dropping and taking values from iterables |
+    +-----------+-------------------------------------------+
+    | folding   | Reducing and accumulating iterables       |
+    +-----------+-------------------------------------------+
 
-- iterables are not necessarily iterators
-- at all times iterator protocol is assumed to be followed
+.. important::
 
-  - all iterators are assumed to be iterable
-  - for all iterators ``foobar`` we assume ``iter(foobar) is foobar``
+    **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'
+__copyright__ = 'Copyright (c) 2023-2026 Geoffrey R. Scheller'
 __license__ = 'Apache License 2.0'

pythonic_fp/iterables/drop_take.py

@@ -13,7 +13,13 @@
 # limitations under the License.
 
 """
-Module pythonic_fp.iterables.drop_take
+Drop and Take
+-------------
+
+.. admonition:: module pythonic_fp.iterables.drop_take
+
+    Functions to drop or take values from an iterable.
+
 """
 
 from collections.abc import Callable, Iterable, Iterator
@@ -30,15 +36,12 @@ __all__ = [
 ]
 
 
-## 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
-    :returns: an iterator of the remaining values
+    :param iterable: Iterable whose values are to be dropped.
+    :param n: Number of values to be dropped.
+    :returns: An iterator of the remaining values.
 
     """
     iterator = iter(iterable)
@@ -53,9 +56,9 @@ def drop[D](iterable: Iterable[D], n: int) -> Iterator[D]:
 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
+    :param iterable: Iterable whose values are to be dropped.
+    :param pred: Single argument Boolean valued function, the "predicate".
+    :returns: An iterator beginning where pred returned false.
 
     """
     iterator = iter(iterable)
@@ -73,9 +76,9 @@ def drop_while[D](iterable: Iterable[D], pred: Callable[[D], bool]) -> 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
+    :param Iterable: iterable providing the values to be taken.
+    :param n: Number of values to be dropped.
+    :returns: An iterator of up to n initial values from iterable.
 
     """
     iterator = iter(iterable)
@@ -91,11 +94,12 @@ def take_while[D](iterable: Iterable[D], pred: Callable[[D], bool]) -> Iterator[
     """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
+    :param iterable: Iterable providing the values to be taken.
+    :param pred: Single argument Boolean valued function, the "predicate".
+    :returns: An Iterator of of values from iterable until predicate false.
 
     """
     iterator = iter(iterable)
@@ -115,12 +119,12 @@ def take_split[D](iterable: Iterable[D], n: int) -> tuple[Iterator[D], Iterator[
 
     .. Warning::
 
-       **CONTRACT:** Do not access the second returned iterator until the
-       first one is exhausted.
+        **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
+    :param iterable: Iterable providing the values to be taken.
+    :param n: maximum Number of values to be taken.
+    :returns: An iterator of values taken and an iterator of remaining values.
 
     """
     iterator = iter(iterable)
@@ -136,12 +140,12 @@ def take_while_split[D](
 
     .. Warning::
 
-       **CONTRACT:** Do not access the second returned iterator until
-       the first one is exhausted.
+        **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
+    :param iterable: Iterable providing the values to be taken.
+    :param pred: Single argument Boolean valued function.
+    :returns: Tuple of iterator of values taken and an iterator of remaining values.
 
     """
 
@@ -162,4 +166,4 @@ def take_while_split[D](
     value: Box[D] = Box()
     it_pred = _take_while(iterator, pred, value)
 
-    return (it_pred, concat(value, iterator))
+    return it_pred, concat(value, iterator)

pythonic_fp/iterables/drop_take.pyi

@@ -1,33 +1,10 @@
-# 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 Callable, Iterable, Iterator
 
-__all__ = [
-    'drop',
-    'drop_while',
-    'take',
-    'take_while',
-    'take_split',
-    'take_while_split',
-]
+__all__ = ['drop', 'drop_while', 'take', 'take_while', 'take_split', 'take_while_split']
 
 def drop[D](iterable: Iterable[D], n: int) -> Iterator[D]: ...
 def drop_while[D](iterable: Iterable[D], pred: Callable[[D], bool]) -> Iterator[D]: ...
 def take[D](iterable: Iterable[D], n: int) -> Iterator[D]: ...
 def take_while[D](iterable: Iterable[D], pred: Callable[[D], bool]) -> Iterator[D]: ...
 def take_split[D](iterable: Iterable[D], n: int) -> tuple[Iterator[D], Iterator[D]]: ...
-def take_while_split[D](
-    iterable: Iterable[D], pred: Callable[[D], bool]
-) -> tuple[Iterator[D], Iterator[D]]: ...
+def take_while_split[D](iterable: Iterable[D], pred: Callable[[D], bool]) -> tuple[Iterator[D], Iterator[D]]: ...

pythonic_fp/iterables/folding.py

@@ -12,13 +12,21 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Module pythonic_fp.iterables.folding"""
+"""
+Folding
+-------
+
+.. admonition:: module pythonic_fp.iterables.folding
+
+    Functions to reduce and accumulate values from iterables.
+
+"""
 
 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.sentinels.novalue import NoValue
+from pythonic_fp.gadgets.sentinels.novalue import NoValue
 from .drop_take import drop_while, take_while_split
 
 __all__ = [

pythonic_fp/iterables/folding.pyi

@@ -1,56 +1,13 @@
-# 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 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.sentinels.novalue import NoValue
-from .drop_take import drop_while, take_while_split
+from pythonic_fp.gadgets.sentinels.novalue import NoValue
+from typing import Never
 
-__all__ = [
-    'accumulate',
-    'reduce_left',
-    'fold_left',
-    'maybe_fold_left',
-    'sc_reduce_left',
-    'sc_reduce_right',
-]
+__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]: ...
+def accumulate[D, L](iterable: Iterable[D], f: Callable[[L, D], L], initial: L | NoValue = ...) -> Iterator[L]: ...
 def reduce_left[D](iterable: Iterable[D], f: Callable[[D, D], D]) -> D | Never: ...
-def fold_left[D, L](
-    iterable: Iterable[D], f: Callable[[L, D], L], initial: L
-) -> L | Never: ...
-def maybe_fold_left[D, L](
-    iterable: Iterable[D], f: Callable[[L, D], L], initial: L | NoValue = NoValue()
-) -> MayBe[L] | Never: ...
-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]]: ...
-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]]: ...
+def fold_left[D, L](iterable: Iterable[D], f: Callable[[L, D], L], initial: L) -> L | Never: ...
+def maybe_fold_left[D, L](iterable: Iterable[D], f: Callable[[L, D], L], initial: L | NoValue = ...) -> MayBe[L] | Never: ...
+def sc_reduce_left[D](iterable: Iterable[D], f: Callable[[D, D], D], start: Callable[[D], bool] = ..., stop: Callable[[D], bool] = ..., include_start: bool = True, include_stop: bool = True) -> tuple[MayBe[D], Iterator[D]]: ...
+def sc_reduce_right[D](iterable: Iterable[D], f: Callable[[D, D], D], start: Callable[[D], bool] = ..., stop: Callable[[D], bool] = ..., include_start: bool = True, include_stop: bool = True) -> tuple[MayBe[D], Iterator[D]]: ...

pythonic_fp/iterables/merging.py

@@ -12,7 +12,15 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Module pythonic_fp.iterables.merging"""
+"""
+Merging Iterables
+-----------------
+
+.. admonition:: module pythonic_fp.iterables.merging
+
+    Functions to merge multiple iterables together into one.
+
+"""
 
 from collections.abc import Iterable, Iterator
 from enum import auto, Enum
@@ -51,8 +59,8 @@ def concat[D](*iterables: Iterable[D]) -> Iterator[D]:
 
         Performant to the standard library's ``itertools.chain``.
 
-    :param iterables: iterables to concatenate
-    :return: iterator of concatenated values from the iterables
+    :param iterables: Iterables to concatenate.
+    :returns: Iterator of concatenated values from the iterables.
 
     """
     for iterator in map(lambda x: iter(x), iterables):
@@ -69,13 +77,13 @@ def merge[D](*iterables: Iterable[D], yield_partials: bool = False) -> Iterator[
 
     .. 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.
+        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
+    :param iterables: Iterables to merge until one gets exhausted.
+    :param yield_partials: Yield any unpaired yielded values from other iterables.
+    :returns: Iterator of merged values from the iterables until one is exhausted.
 
     """
     iter_list = list(map(lambda x: iter(x), iterables))
@@ -96,8 +104,8 @@ def merge[D](*iterables: Iterable[D], yield_partials: bool = False) -> Iterator[
 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
+    :param iterables: Iterables to exhaustively merge.
+    :returns: Iterator of merged values from the iterables until all are exhausted.
 
     """
     iter_list = list(map(lambda x: iter(x), iterables))
@@ -126,13 +134,13 @@ def blend[D](
     merge_enum: MergeEnum = MergeEnum.Concat,
     yield_partials: bool = False,
 ) -> Iterator[D]:
-    """Base merge behavior on name only parameters.
+    """Merge behavior based on value of merge_enum parameter.
 
-    :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
+    :param iterables: Iterables to blend together.
+    :param merge_enum: ``MergeEnum`` to determine merging behavior.
+    :param yield_partials: Yield unpaired values from other iterables.
+    :returns: An iterator of type ``D``.
+    :raises ValueError: When an unknown ``MergeEnum`` is given.
 
     """
     match merge_enum:

pythonic_fp/iterables/merging.pyi

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

{pythonic_fp_iterables-5.1.1.dist-info → pythonic_fp_iterables-5.1.3.dist-info}/METADATA

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: pythonic-fp-iterables
-Version: 5.1.1
-Summary: Library of functions for iterating iterables
+Version: 5.1.3
+Summary: Tools for iterables
 Keywords: iterables,iterators
 Author-email: "Geoffrey R. Scheller" <geoffrey@scheller.com>
 Requires-Python: >=3.13
@@ -14,13 +14,12 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Typing :: Typed
 License-File: LICENSE
-Requires-Dist: pythonic-fp-fptools>=5.1.1
-Requires-Dist: pythonic-fp-gadgets>=3.0.1
-Requires-Dist: pythonic-fp-sentinels>=2.1.0
+Requires-Dist: pythonic-fp-fptools>=5.2.0
+Requires-Dist: pythonic-fp-gadgets>=4.0.2
 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: Documentation, https://grscheller.github.io/pythonic-fp/iterables/development/build/html/
+Project-URL: Homepage, https://grscheller.github.io/pythonic-fp/homepage/build/html/
 Project-URL: Source, https://github.com/grscheller/pythonic-fp-iterables
 Provides-Extra: test
 
@@ -43,15 +42,17 @@ Library of functions for iterating iterables.
     - 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>`_
+Part of the
+`pythonic-fp
+<https://grscheller.github.io/pythonic-fp>`_
+PyPI projects.
 
 Documentation
 -------------
 
 Documentation for this project is hosted on
 `GitHub Pages
-<https://grscheller.github.io/pythonic-fp/iterables/development/build/html>`_.
+<https://grscheller.github.io/pythonic-fp/iterables>`_.
 
 Copyright and License
 ---------------------

pythonic_fp_iterables-5.1.3.dist-info/RECORD

@@ -0,0 +1,13 @@
+pythonic_fp/iterables/__init__.py,sha256=oAoufgaFeHBH81d-ey738bBsVSximbrp0Rseb3EafnI,1663
+pythonic_fp/iterables/__init__.pyi,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pythonic_fp/iterables/drop_take.py,sha256=Kvj-B_xXD9t4tsIjMRdMXwSDKAeUsfbtLPs6X7wRapg,4847
+pythonic_fp/iterables/drop_take.pyi,sha256=vPyByY4PxCGEuL6trI0aTK8fBr4xCuOgqhaKALwJ5Ys,653
+pythonic_fp/iterables/folding.py,sha256=5-EJT-lp8EhAghMlNghla3rnVL0ywRS3-kGuO13oEVI,8711
+pythonic_fp/iterables/folding.pyi,sha256=ZVrpB-D4kWoVwpCsQ2rc3GJ8iTzavAOQ5YK9LteAukU,1175
+pythonic_fp/iterables/merging.py,sha256=mJ4nmIxSwuoi8LvYTHbU-JEUqkii1BdociRs59Dxq-A,4613
+pythonic_fp/iterables/merging.pyi,sha256=KnuSFREXEpnbtTvMWsvn-KfeSjZ3ybP-6n9hCxjNKVs,533
+pythonic_fp/iterables/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pythonic_fp_iterables-5.1.3.dist-info/licenses/LICENSE,sha256=IJMkVWQUVy-SonK6SMaMotDQ6Zb-lVi2bUTiGp1GUO8,10774
+pythonic_fp_iterables-5.1.3.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+pythonic_fp_iterables-5.1.3.dist-info/METADATA,sha256=Mi8wDsA-nnmMXWfrhS42W1CULGDYOcsSRqTk1nxNJNo,2064
+pythonic_fp_iterables-5.1.3.dist-info/RECORD,,

pythonic_fp_iterables-5.1.1.dist-info/RECORD

@@ -1,12 +0,0 @@
-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.1.dist-info/licenses/LICENSE,sha256=IJMkVWQUVy-SonK6SMaMotDQ6Zb-lVi2bUTiGp1GUO8,10774
-pythonic_fp_iterables-5.1.1.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
-pythonic_fp_iterables-5.1.1.dist-info/METADATA,sha256=v-ZcT1UdI4culcyrlTa2jZTw_ulXRaEhs30CSkAE0Ow,2218
-pythonic_fp_iterables-5.1.1.dist-info/RECORD,,