pythonic-fp.iterables 3.0.0__tar.gz → 5.0.0__tar.gz

pythonic_fp_iterables-5.0.0/.gitignore

@@ -0,0 +1,6 @@
+# Minimal version - only add to when necessary
+**/__pycache__/
+dist/
+**/.mypy_cache/
+**/.pytest_cache/
+**/.ruff_cache

pythonic_fp_iterables-5.0.0/CHANGELOG.rst

@@ -0,0 +1,190 @@
+CHANGELOG
+=========
+
+PyPI pythonic-fp.iterables project.
+
+Semantic Versioning
+-------------------
+
+Strict 3 digit semantic versioning adopted 2025-05-19.
+
+- **MAJOR** version incremented for incompatible API changes
+- **MINOR** version incremented for backward compatible added functionality
+- **PATCH** version incremented for backward compatible bug fixes
+
+See `Semantic Versioning 2.0.0 <https://semver.org>`_.
+
+Releases and Important Milestones
+---------------------------------
+
+4.0.0 - 2025-07-16
+~~~~~~~~~~~~~~~~~~
+
+Primary purpose was to bring Sphinx documentation in alignment
+with other pythonic-fp projects. Ended up making substantial
+Sphinx documentation improvements. Will use this documentation
+for the other pythonic-fp projects.
+
+- API change
+
+  - renamed pythonic_fp.iterables.foldl to pythonic_fp.iterables.fold_left
+
+3.0.0 - 2025-07-06
+~~~~~~~~~~~~~~~~~~
+
+First PyPI release as ``pythonic-fp.iterables``
+
+- dropping dtools namespace name because there is a repo by that name.
+
+2.0.0 - 2025-05-22
+~~~~~~~~~~~~~~~~~~
+
+- Moved dtools.fp.iterables to its own PyPI project
+
+  - dtools.iterables
+
+- Moved dtools.fp.err_handling to the dtools.containers PyPI project
+
+  - Moved class MayBe -> module dtools.containers.maybe
+  - Moved class Xor -> module dtools.containers.xor
+  - dropped lazy methods
+
+    - will import dtools.fp.lazy directly for this functionality
+
+1.7.0 - 2025-04-22
+~~~~~~~~~~~~~~~~~~
+
+Last PyPI release as dtools.fp
+
+- API changes along the lines of dtools.ca 3.12
+- typing improvements
+- docstring changes
+- pyproject.toml standardization
+
+1.6.0 - 2025-04-07
+~~~~~~~~~~~~~~~~~~
+
+- typing improvements
+
+1.4.0 - 2025-03-16
+~~~~~~~~~~~~~~~~~~
+
+- much work dtools.iterables
+
+  - finally implemented scReduceL and scReduceR functions
+  - tweaked API across iterables module
+
+1.3.0 - 2025-01-17
+~~~~~~~~~~~~~~~~~~
+
+First release as dtools.fp
+
+Repo name changes.
+
+- GitHub: fp -> dtools-fp
+- PyPI: grscheller.fp -> dtools.fp
+
+1.0.1 - 2024-10-20
+~~~~~~~~~~~~~~~~~~
+
+- removed docs from repo
+- docs for all grscheller namespace projects maintained here
+ 
+  - https://grscheller.github.io/grscheller-pypi-namespace-docs/
+
+1.0.0 - 2024-10-18
+~~~~~~~~~~~~~~~~~~
+
+Decided to make this release first stable release.
+
+- renamed module fp.woException to fp.err_handling
+- pytest improvements based on pytest documentation
+
+0.4.0 - 2024-10-03
+~~~~~~~~~~~~~~~~~~
+
+Long overdue PyPI release.
+
+0.3.4.0 - 2024-09-30
+~~~~~~~~~~~~~~~~~~~~
+
+Development environment only.
+
+- API change for fp.iterables
+
+  - function name changes
+
+    - ``foldL``, ``foldR``, ``foldLsc``, ``foldRsc``
+    - ``sc`` stands for "short circuit"
+
+  - all now return class woException.MB
+
+0.3.3.7 - 2024-09-22
+~~~~~~~~~~~~~~~~~~~~
+
+Development environment only.
+
+- added more functions to fp.iterables module
+
+  - take(it: Iterable[D], n: int) -> Iterator[D]
+  - takeWhile(it: Iterable[D], pred: Callable\[[D], bool\]) -> Iterator[D]
+  - drop(it: Iterable[D], n: int) -> Iterator[D]
+  - dropWhile(it: Iterable[D], pred: Callable\[[D], bool\]) -> Iterator[D]
+
+0.3.3.4 - 2024-09-16
+~~~~~~~~~~~~~~~~~~~~
+
+Development environment only.
+
+- fp.iterables ``foldL_sc`` & ``foldR_sc`` now have
+
+  - common paradigm
+  - similar signatures
+
+0.3.3.3 - 2024-09-15
+~~~~~~~~~~~~~~~~~~~~
+
+Development environment only.
+
+- added fp.iterables function ``foldR_sc``
+
+  - shortcut version of ``foldR``
+  - not fully tested
+  - docstring not updated
+
+0.3.3.2 - 2024-09-14
+~~~~~~~~~~~~~~~~~~~~
+
+Development environment only.
+
+- added fp.iterables function ``foldL_sc``
+
+  - shortcut version of foldL
+
+0.3.1 - 2024-08-20
+~~~~~~~~~~~~~~~~~~
+
+Now fp.iterables no longer exports ``CONCAT``, ``MERGE``, ``EXHAUST``.
+
+- for grscheller.datastructures
+
+  - grscheller.datastructures.ftuple
+  - grscheller.datastructures.split_ends
+
+0.2.0 - 2024-07-26
+~~~~~~~~~~~~~~~~~~
+
+- from last PyPI release
+
+  - added accumulate function to fp.iterators
+
+- overall much better docstrings
+
+0.1.0 - 2024-07-11
+~~~~~~~~~~~~~~~~~~
+
+Initial PyPI release as grscheller.fp
+
+Replicated functionality from grscheller.datastructures.
+
+- ``grscheller.core.iterlib -> grscheller.fp.iterators``

{pythonic_fp_iterables-3.0.0 → pythonic_fp_iterables-5.0.0}/PKG-INFO

@@ -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/README.rst

@@ -0,0 +1,34 @@
+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-3.0.0 → pythonic_fp_iterables-5.0.0}/pyproject.toml

@@ -1,7 +1,11 @@
+[build-system]
+requires = ["flit_core>=3.12,<4"]
+build-backend = "flit_core.buildapi"
+
 [project]
-name = "pythonic-fp.iterables"
-version = "3.0.0"
-readme = "README.md"
+name = "pythonic-fp-iterables"
+version = "5.0.0"
+readme = "README.rst"
 requires-python = ">=3.12"
 license = { file = "LICENSE" }
 authors = [{ name = "Geoffrey R. Scheller", email = "geoffrey@scheller.com" }]
@@ -16,24 +20,25 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-  "pythonic-fp.circulararray>=5.0.0",
-  "pythonic-fp.containers >=2.0.0",
-  "pythonic-fp.fptools >=3.0.0",
+  "pythonic-fp-fptools>=5.0.0",
+  "pythonic-fp>=1.1.0",
+  "pythonic-fp-singletons>=1.0.0",
 ]
 dynamic = ["description"]
 
+[project.optional-dependencies]
+test = [
+  "pytest>=8.4.1",
+]
+
 [project.urls]
-Changelog = "https://grscheller.github.io/pythonic-fp-iterables/html/changelog.html"
-Documentation = "https://grscheller.github.io/pythonic-fp-iterables/html/"
+Changelog = "https://github.com/grscheller/pythonic-fp-iterables/blob/main/CHANGELOG.rst"
+Documentation = "https://grscheller.github.io/pythonic-fp/iterables/development/build/html/releases.html"
 Homepage = "https://github.com/grscheller/pythonic-fp/blob/main/README.md"
 Source = "https://github.com/grscheller/pythonic-fp-iterables"
 
-[build-system]
-requires = ["flit_core>=3.12,<4"]
-build-backend = "flit_core.buildapi"
-
-[tool.flit.sdist]
-exclude = ["dist", "docs", "tests", ".gitignore", ".mypy_cache", ".pytest_cache"]
+[tool.flit.module]
+name = "pythonic_fp.iterables"
 
 [tool.mypy]
 enable_incomplete_feature = ["NewGenericSyntax"]
@@ -43,31 +48,20 @@ warn_redundant_casts = true
 warn_return_any = true
 warn_unused_configs = true
 
-[tool.pylsp]
-python_path = [
-  "/home/grs/devel/pypi/fptools/pythonic-fp-iterables/src",
-  "/home/grs/devel/pypi/fptools/pythonic-fp-circulararray/src",
-  "/home/grs/devel/pypi/fptools/pythonic-fp-containers/src",
-  "/home/grs/devel/pypi/fptools/pythonic-fp-fptools/src",
-]
-
 [tool.pylsp-mypy]
 enabled = true
 live-mode = true
 strict = true
 report_progress = true
-exclude = ["tests/.*"]
 
 [tool.pytest.ini_options]
 consider_namespace_packages = true
-testpaths = ["tests"]
+testpaths = ["tests/"]
 addopts = "-ra"
 
 [tool.ruff]
 target-version = "py313"
-
-[tool.ruff.lint.per-file-ignores]
-"__init__.py" = ["F401"]
+ignore = ["E741"]
 
 [tool.ruff.lint.flake8-quotes]
 docstring-quotes = "double"

pythonic_fp_iterables-5.0.0/src/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-5.0.0/src/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))