pythonic-fp.iterables 5.1.3__tar.gz → 5.2.0__tar.gz

{pythonic_fp_iterables-5.1.3 → pythonic_fp_iterables-5.2.0}/PKG-INFO

@@ -1,62 +1,53 @@
 Metadata-Version: 2.4
 Name: pythonic-fp-iterables
-Version: 5.1.3
-Summary: Tools for iterables
+Version: 5.2.0
+Summary: Composing and iterating iterables.
 Keywords: iterables,iterators
 Author-email: "Geoffrey R. Scheller" <geoffrey@scheller.com>
-Requires-Python: >=3.13
-Description-Content-Type: text/x-rst
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
 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: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Typing :: Typed
 License-File: LICENSE
-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/
-Project-URL: Homepage, https://grscheller.github.io/pythonic-fp/homepage/build/html/
+Requires-Dist: pythonic-fp-fptools>=6,<6.2
+Requires-Dist: pythonic-fp-gadgets>=4.5,<6
+Project-URL: Changelog, https://github.com/grscheller/pythonic-fp-iterables/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://grscheller.github.io/pythonic-fp-iterables/release/html/
+Project-URL: Homepage, https://grscheller.github.io/pythonic-fp/
 Project-URL: Source, https://github.com/grscheller/pythonic-fp-iterables
-Provides-Extra: test
 
-Pythonic FP - Tools for iterables
-=================================
+# Pythonic FP - Tools for iterables
+
+Library of functions for iterating iterables.
 
 PyPI project
-`pythonic-fp.iterators <https://pypi.org/project/pythonic-fp.iterables>`_.
+[pythonic-fp-iterators](https://pypi.org/project/pythonic-fp-iterables).
+Part of the
+[pythonic-fp](https://grscheller.github.io/pythonic-fp/)
+PyPI projects.
 
-Library of functions for iterating iterables.
+## Documentation
+
+Documentation and other links for this project are hosted on
+[GitHub Pages](https://grscheller.github.io/pythonic-fp/projects/iterables.html).
 
 - 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``
 
-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>`_.
-
-Copyright and License
----------------------
+## Copyright and License
 
-Copyright (c) 2023-2025 Geoffrey R. Scheller. Licensed under the Apache
+Copyright (c) 2023-2026 Geoffrey R. Scheller. Licensed under the Apache
 License, Version 2.0. See the LICENSE file for details.
 

pythonic_fp_iterables-5.1.3/README.rst → pythonic_fp_iterables-5.2.0/README.md

@@ -1,36 +1,28 @@
-Pythonic FP - Tools for iterables
-=================================
+# Pythonic FP - Tools for iterables
+
+Library of functions for iterating iterables.
 
 PyPI project
-`pythonic-fp.iterators <https://pypi.org/project/pythonic-fp.iterables>`_.
+[pythonic-fp-iterators](https://pypi.org/project/pythonic-fp-iterables).
+Part of the
+[pythonic-fp](https://grscheller.github.io/pythonic-fp/)
+PyPI projects.
 
-Library of functions for iterating iterables.
+## Documentation
+
+Documentation and other links for this project are hosted on
+[GitHub Pages](https://grscheller.github.io/pythonic-fp/projects/iterables.html).
 
 - 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``
 
-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>`_.
-
-Copyright and License
----------------------
+## Copyright and License
 
-Copyright (c) 2023-2025 Geoffrey R. Scheller. Licensed under the Apache
+Copyright (c) 2023-2026 Geoffrey R. Scheller. Licensed under the Apache
 License, Version 2.0. See the LICENSE file for details.

{pythonic_fp_iterables-5.1.3 → pythonic_fp_iterables-5.2.0}/pyproject.toml

@@ -1,75 +1,86 @@
+[build-system]
+requires = ["flit_core>=3.12,<4"]
+build-backend = "flit_core.buildapi"
+
 [project]
 name = "pythonic-fp-iterables"
-version = "5.1.3"
-readme = "README.rst"
-requires-python = ">=3.13"
-license = { file = "LICENSE" }
-authors = [{ name = "Geoffrey R. Scheller", email = "geoffrey@scheller.com" }]
-keywords = ["iterables", "iterators"]
+version = "5.2.0"
+description = "Composing and iterating iterables."
+readme = "README.md"
+requires-python = ">=3.14"  # floor: PEP 649/749 deferred annotations — class-level self-reference
+authors = [
+  { name = "Geoffrey R. Scheller", email = "geoffrey@scheller.com" },
+]
+keywords = [
+  "iterables",
+  "iterators",
+]
 classifiers = [
   "Development Status :: 5 - Production/Stable",
   "Framework :: Pytest",
   "Intended Audience :: Developers",
   "License :: OSI Approved :: Apache Software License",
   "Operating System :: OS Independent",
-  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: 3.15",
   "Typing :: Typed",
 ]
 dependencies = [
-  "pythonic-fp-fptools>=5.2.0",
-  "pythonic-fp-gadgets>=4.0.2",
+  "pythonic-fp-fptools>=6,<6.2",
+  "pythonic-fp-gadgets>=4.5,<6",
 ]
-dynamic = ["description"]
 
 [project.urls]
-Changelog = "https://github.com/grscheller/pythonic-fp-iterables/blob/main/CHANGELOG.rst"
-Documentation = "https://grscheller.github.io/pythonic-fp/iterables/development/build/html/"
-Homepage = "https://grscheller.github.io/pythonic-fp/homepage/build/html/"
+Changelog = "https://github.com/grscheller/pythonic-fp-iterables/blob/main/CHANGELOG.md"
+Documentation ="https://grscheller.github.io/pythonic-fp-iterables/release/html/"
+Homepage = "https://grscheller.github.io/pythonic-fp/"
 Source = "https://github.com/grscheller/pythonic-fp-iterables"
 
-[project.optional-dependencies]
+[dependency-groups]
+docs = [
+  "furo>=2025.12.19",
+  "sphinx>=9.1",
+]
 test = [
   "pytest>=8.4.1",
 ]
 
-[build-system]
-requires = ["flit_core>=3.12,<4"]
-build-backend = "flit_core.buildapi"
-
 [tool.flit.module]
 name = "pythonic_fp.iterables"
 
+[tool.flit.sdist]
+exclude = [
+  "docs/",
+  "tests/",
+]
+
+[tool.pytest]
+addopts = ["-ra"]
+consider_namespace_packages = true
+testpaths = ["tests/"]
+
 [tool.mypy]
-enable_incomplete_feature = "NewGenericSyntax"
 explicit_package_bases = true
-implicit_reexport = false
 local_partial_types = true
 namespace_packages = true
 warn_redundant_casts = true
 warn_return_any = true
 warn_unused_configs = true
 
-[tool.pylsp-mypy]
-enabled = true
-live-mode = true
-dmypy = false
-strict = true
-report_progress = true
-
-[tool.pytest.ini_options]
-addopts = "-ra"
-consider_namespace_packages = true
-testpaths = ["tests/"]
-
 [tool.ruff]
-target-version = "py313"
+target-version = "py314"
+
+[tool.ruff.lint]
+ignore = ["RUF022", "E741"]
 
 [tool.ruff.lint.flake8-quotes]
 docstring-quotes = "double"
 
 [tool.ruff.lint.per-file-ignores]
-"tests/*" = ["C901"]
-"**/*.py" = ["E741"]
+"tests/**/*.py" = [
+  "E731",
+  "C901",
+]
 
 [tool.ruff.format]
 quote-style = "single"

{pythonic_fp_iterables-5.1.3 → pythonic_fp_iterables-5.2.0}/src/pythonic_fp/iterables/__init__.py

@@ -13,20 +13,11 @@
 # limitations under the License.
 
 """
-Tools for iterables
--------------------
+.. admonition:: Composing and iterating iterables
 
-.. admonition:: 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       |
-    +-----------+-------------------------------------------+
+    - module **merging:** Concatenating and merging iterables.
+    - module **drop_take:** Dropping and taking values from iterables.
+    - module **folding:**  Reducing and accumulating iterables.
 
 .. important::
 
@@ -35,8 +26,8 @@ Tools for iterables
     - 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``
+      - all iterators are assumed to be iterable
+      - for all iterators ``foo`` we assume ``iter(foo) is foo``
 
 """
 

pythonic_fp_iterables-5.2.0/src/pythonic_fp/iterables/drop_take.py

@@ -0,0 +1,202 @@
+# 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.
+# 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.
+
+"""
+.. admonition:: Drop and Take
+
+    Functions which drop or take items from an iterable.
+
+    .. important::
+
+        If iterable is a multiply referenced iterator, items
+        dropped or taken need not be the next consecutive items.
+
+    .. important::
+
+        If iterable is mutable, iterator may be affected by the
+        current state of the original iterable.
+
+        .. tip::
+
+            Prefer immutable iterables over mutable ones.
+
+"""
+
+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',
+]
+
+
+def drop[D](iterable: Iterable[D], n: int) -> Iterator[D]:
+    """
+    .. admonition:: drop
+
+        Drop the next n items from iterable.
+
+        :param iterable: Iterable whose items are to be dropped.
+        :param n: Number of items to be dropped.
+        :yields: The remaining items.
+
+    """
+    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]:
+    """
+    .. admonition:: drop while
+
+        Drop initial items from iterable while predicate is true.
+
+        :param iterable: Iterable whose items are to be dropped.
+        :param pred: Single argument Boolean valued function.
+        :yields: items starting when ``pred`` returns ``False``.
+
+    """
+    iterator = iter(iterable)
+    while True:
+        try:
+            item = next(iterator)
+            if not pred(item):
+                iterator = concat((item,), iterator)
+                break
+        except StopIteration:
+            break
+    return iterator
+
+
+def take[D](iterable: Iterable[D], n: int) -> Iterator[D]:
+    """
+    .. admonition:: take
+
+        Return an iterator yielding up to n items from an iterable.
+
+        :param Iterable: Iterable providing the items to be taken.
+        :param n: Number of items to be taken.
+        :yields: Up to n items from iterable.
+
+    """
+    iterator = iter(iterable)
+    for _ in range(n):
+        try:
+            item = next(iterator)
+            yield item
+        except StopIteration:
+            break
+
+
+def take_while[D](iterable: Iterable[D], pred: Callable[[D], bool]) -> Iterator[D]:
+    """
+    .. admonition:: take while
+
+        Return an iterator of items until predicate false.
+
+        :param iterable: Iterable providing the items to be taken.
+        :param pred: Single argument Boolean valued function.
+        :yields: Items from iterable while predicate is true.
+
+        .. warning::
+
+            Risk of data loss if iterable is multiple referenced iterator.
+
+    """
+    iterator = iter(iterable)
+    while True:
+        try:
+            item = next(iterator)
+            if pred(item):
+                yield item
+            else:
+                break
+        except StopIteration:
+            break
+
+
+def take_split[D](iterable: Iterable[D], n: int) -> tuple[Iterator[D], Iterator[D]]:
+    """
+    .. admonition:: take split
+
+        Same as take except also return an iterator of
+        the remaining items.
+
+        .. admonition:: CONTRACT
+
+            **IMPORTANT:** Do not access the second iterator until
+            the first one is completely exhausted.
+
+        :param iterable: Iterable providing the items to be taken.
+        :param n: maximum Number of items to be taken.
+        :returns: A tuple containing an iterator of items taken
+                  and an iterator of remaining items.
+
+    """
+    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]]:
+    """
+    .. admonition:: take while
+
+        Same as take_while except also return an iterator of
+        the remaining items.
+
+        .. admonition:: CONTRACT
+
+            **IMPORTANT:** Do not access the second iterator until
+            the first one is completely exhausted.
+
+        :param iterable: Iterable providing the items to be taken.
+        :param pred: Single argument Boolean valued function.
+        :returns: A tuple containing an iterator of items taken while
+                  ``pred`` truthy and an iterator of remaining items.
+
+    """
+
+    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)
+    item: Box[D] = Box()
+    it_pred = _take_while(iterator, pred, item)
+
+    return it_pred, concat(item, iterator)