pythonic-fp.splitends 2.0.2__tar.gz → 3.1.0__tar.gz

{pythonic_fp_splitends-2.0.2 → pythonic_fp_splitends-3.1.0}/PKG-INFO

@@ -1,38 +1,44 @@
 Metadata-Version: 2.4
 Name: pythonic-fp-splitends
-Version: 2.0.2
-Summary: Mutable stack objects that can safely share data.
+Version: 3.1.0
+Summary: Mutable stack datastructures that can safely share data.
 Keywords: SplitEnd,lifo,stack
 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 :: 3 - Alpha
 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-iterables>=5.1.3
-Requires-Dist: pythonic-fp-queues>=5.1.1
-Requires-Dist: pytest>=8.4.1 ; extra == "test"
-Project-URL: Changelog, https://github.com/grscheller/pythonic-fp-splitends/blob/main/CHANGELOG.rst
-Project-URL: Documentation, https://grscheller.github.io/pythonic-fp/splitends/development/build/html/
-Project-URL: Homepage, https://grscheller.github.io/pythonic-fp/homepage/build/html/
+Requires-Dist: pythonic-fp-fptools>=6.1,<6.2
+Requires-Dist: pythonic-fp-iterables>=5.1.4,<6
+Requires-Dist: pythonic-fp-queues>=5.1.3,<6
+Project-URL: Changelog, https://github.com/grscheller/pythonic-fp-splitends/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://grscheller.github.io/pythonic-fp-splitends/release/html/
+Project-URL: Homepage, https://grscheller.github.io/pythonic-fp/
 Project-URL: Source, https://github.com/grscheller/pythonic-fp-splitends
-Provides-Extra: test
 
-Pythonic FP - SplitEnds
-=======================
+# Pythonic FP - SplitEnds
+
+Package Implementing a singularly linked LIFO queue called
+a `SplitEnd`. These data structures can safely share data nodes
+between themselves.
 
 PyPI project
-`pythonic-fp.splitends <https://pypi.org/project/pythonic-fp.splitends/>`_.
+[pythonic-fp.splitends](https://pypi.org/project/pythonic-fp-splitends/).
+Part of the
+[pythonic-fp](https://grscheller.github.io/pythonic-fp/)
+PyPI projects.
 
-Python package Implementing a singularly linked LIFO queue called
-a ``SplitEnd``. These data structures can safely share data nodes
-between themselves.
+## Documentation
+
+Documentation and other links for this project are hosted on
+[GitHub Pages](https://grscheller.github.io/pythonic-fp/projects/splitends.html).
 
 - each ``SplitEnd`` is a very simple stateful (mutable) LIFO stack
 - data can be "extended" to or "snipped" off of the end (tip)
@@ -43,21 +49,8 @@ between themselves.
 - the ``SplitEnd`` copy method and ``len`` are O(1)
 - in boolean context returns true if the ``SplitEnd`` is not just a "root"
 
-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/splitends>`_.
-
-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_splitends-2.0.2/README.rst → pythonic_fp_splitends-3.1.0/README.md

@@ -1,12 +1,19 @@
-Pythonic FP - SplitEnds
-=======================
+# Pythonic FP - SplitEnds
+
+Package Implementing a singularly linked LIFO queue called
+a `SplitEnd`. These data structures can safely share data nodes
+between themselves.
 
 PyPI project
-`pythonic-fp.splitends <https://pypi.org/project/pythonic-fp.splitends/>`_.
+[pythonic-fp.splitends](https://pypi.org/project/pythonic-fp-splitends/).
+Part of the
+[pythonic-fp](https://grscheller.github.io/pythonic-fp/)
+PyPI projects.
 
-Python package Implementing a singularly linked LIFO queue called
-a ``SplitEnd``. These data structures can safely share data nodes
-between themselves.
+## Documentation
+
+Documentation and other links for this project are hosted on
+[GitHub Pages](https://grscheller.github.io/pythonic-fp/projects/splitends.html).
 
 - each ``SplitEnd`` is a very simple stateful (mutable) LIFO stack
 - data can be "extended" to or "snipped" off of the end (tip)
@@ -17,20 +24,7 @@ between themselves.
 - the ``SplitEnd`` copy method and ``len`` are O(1)
 - in boolean context returns true if the ``SplitEnd`` is not just a "root"
 
-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/splitends>`_.
-
-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_splitends-3.1.0/pyproject.toml

@@ -0,0 +1,94 @@
+[build-system]
+requires = ["flit_core>=3.12,<4"]
+build-backend = "flit_core.buildapi"
+
+[project]
+name = "pythonic-fp-splitends"
+version = "3.1.0"
+description = "Mutable stack datastructures that can safely share data."
+readme = "README.md"
+requires-python = ">=3.14"  # floor: PEP 649/749 deferred annotations — class-level self-reference possible NameErrors on <3.14
+authors = [
+  { name = "Geoffrey R. Scheller", email = "geoffrey@scheller.com" },
+]
+keywords = [
+  "SplitEnd",
+  "lifo",
+  "stack",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Framework :: Pytest",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: 3.15",
+  "Typing :: Typed",
+]
+dependencies = [
+  "pythonic-fp-fptools>=6.1,<6.2",
+  "pythonic-fp-iterables>=5.1.4,<6",
+  "pythonic-fp-queues>=5.1.3,<6",
+]
+
+[project.urls]
+Changelog = "https://github.com/grscheller/pythonic-fp-splitends/blob/main/CHANGELOG.md"
+Documentation ="https://grscheller.github.io/pythonic-fp-splitends/release/html/"
+Homepage = "https://grscheller.github.io/pythonic-fp/"
+Source = "https://github.com/grscheller/pythonic-fp-splitends"
+
+[dependency-groups]
+docs = [
+  "furo>=2025.12.19",
+  "sphinx>=9.1",
+]
+test = [
+  "pytest>=8.4.1",
+]
+
+[tool.flit.module]
+name = "pythonic_fp.splitends"
+
+[tool.flit.sdist]
+exclude = [
+  "docs/",
+  "tests/",
+  "**/.mypy_cache/",
+  "**/.ruff_cache/",
+  "**/.pytest_cache/",
+  "**/__pycache__/",
+  "**/.dmypy.json",
+]
+
+[tool.pytest]
+addopts = ["-ra"]
+consider_namespace_packages = true
+testpaths = ["tests/"]
+
+[tool.mypy]
+explicit_package_bases = true
+local_partial_types = true
+namespace_packages = true
+warn_redundant_casts = true
+warn_return_any = true
+warn_unused_configs = true
+
+[tool.ruff]
+target-version = "py314"
+
+[tool.ruff.lint]
+ignore = ["RUF022", "E741"]
+
+[tool.ruff.lint.flake8-quotes]
+docstring-quotes = "double"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = [
+  "E731",
+  "C901",
+]
+
+[tool.ruff.format]
+quote-style = "single"
+docstring-code-line-length = 72

pythonic_fp_splitends-3.1.0/src/pythonic_fp/splitends/__init__.py

@@ -0,0 +1,41 @@
+# Copyright 2024-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:: Mutable stack objects that can safely share data
+
+    Python package implementing a singularly linked stack of nodes called a ``SplitEnd``.
+    While mutable, these data structures can safely share immutable data nodes between
+    themselves. These nodes, of type ``SENode``, always contain data. A root node is
+    a node whose previous node is itself. Root nodes mark the bottom of the stack.
+
+    Like one of many "split ends" from shafts of hair, a ``SplitEnd`` can be "snipped"
+    shorter or "extended" further from its "end" node at the top of the stack. Its "root"
+    node is at the bottom of the stack and can not be "snipped" or "cut" off.
+
+    A ``SplitEnd`` can be duplicated onto a compatible root node. By compatible, the
+    new root must contain data that compares as equal to the old root node.
+
+    .. admonition:: Future directions
+
+        A ``scalp`` is a container of root nodes all of whose contained data must
+        be hashable. The ``scalp.add(d)`` method will return the unique root node with data
+        that compares as equal to ``d``, or create a new root node if such a contained node
+        does not exist.
+
+"""
+
+__author__ = 'Geoffrey R. Scheller'
+__copyright__ = 'Copyright (c) 2023-2026 Geoffrey R. Scheller'
+__license__ = 'Apache License 2.0'

{pythonic_fp_splitends-2.0.2 → pythonic_fp_splitends-3.1.0}/src/pythonic_fp/splitends/splitend.py

@@ -19,16 +19,20 @@ Class SplitEnds
 .. admonition:: LIFO stacks safely sharing immutable data.
 
     - each ``SplitEnd`` is a very simple stateful (mutable) LIFO stack
-    - data can be either "extended" to or "snipped" off the "end" 
-    - the "root" of a ``SplitEnd``
+    - data can be either "extended" to or "snipped" off the "end"
+    - "root" of a ``SplitEnd`` is embedded in a ``scalp``
 
-      - it is fixed and cannot be removed from the ``SplitEnd``
+      - the root data is immutable
+      - it cannot be split off
 
     - different mutable split ends can safely share the same "tail"
     - each ``SplitEnd`` sees itself as a singularly linked list
     - bush-like datastructures can be formed using multiple ``SplitEnds``
     - the ``SplitEnd.split`` and ``len`` methods are O(1)
-    - in boolean context returns true if the ``SplitEnd`` is not just its "root"
+    - in a boolean context
+
+      - falsy just a "root"
+      - truthy otherwise
 
 """
 
@@ -52,8 +56,10 @@ class SplitEnd[D]:
 
     def __init__(self, *ds: D, root: SENode[D] | _Sentinel = _sentinel) -> None:
         """
-        :param root_data: Irremovable initial data at bottom of stack.
-        :param data: Removable data to be pushed onto splitend stack.
+        .. admonition:: init
+
+            :param root_data: Irremovable initial data at bottom of stack.
+            :param ds: Removable data to be pushed onto splitend stack.
 
         """
         if root is _sentinel:
@@ -78,28 +84,57 @@ class SplitEnd[D]:
         self._end, self._root, self._count = end, root_node, count
 
     def __iter__(self) -> Iterator[D]:
+        """
+        .. admonition:: iter
+
+            Iterate from end to root.
+
+            :yields: data from end to root
+
+        """
         return iter(self._end)
 
     def __reversed__(self) -> Iterator[D]:
+        """
+        .. admonition:: reverse iter
+
+            Iterate from end to root.
+
+            :yields: data from end to root
+
+        """
         return reversed(list(self))
 
     def __bool__(self) -> bool:
         """
-        :returns: ``True`` is ``SplitEnd`` is not just its root node.
+        .. admonition:: bool
+
+            :returns: ``True`` if ``SplitEnd`` is not just its root node.
 
         """
         return bool(self._end)
 
     def __len__(self) -> int:
-        return self._count
+        """
+        .. admonition:: len
 
-    def __repr__(self) -> str:
-        return 'SplitEend(' + ', '.join(map(repr, reversed(self))) + ')'
+            :returns: The number of nodes on the ``Splitend``.
 
-    def __str__(self) -> str:
-        return '>< ' + ' -> '.join(map(str, self)) + ' ||'
+        """
+        return self._count
 
     def __eq__(self, other: object, /) -> bool:
+        """
+        .. admonition:: equality comparison
+
+            Efficiently compare two ``SplitEnds``.
+
+            :returns: ``True`` only if ``other`` is also a ``Splitend``
+                      whose corresponding data to ``self`` compares as
+                      equal and both share the same root node.
+                      Otherwise ``False``.
+
+        """
         if not isinstance(other, type(self)):
             return False
 
@@ -120,11 +155,54 @@ class SplitEnd[D]:
                 right = right.prev()
         return True
 
+    def __repr__(self) -> str:
+        """
+        .. admonition:: repr string
+
+            Construct string to reproduce the ``SplitEnd``.
+            TODO: Fix, does not include root node.
+
+            :returns: String to reproduce the ``SplitEnd``.
+
+        """
+        return 'SplitEend(' + ', '.join(map(repr, reversed(self))) + ')'
+
+    def __str__(self) -> str:
+        """
+        .. admonition:: user string
+
+            Construct string meaningful to an end user.
+            Does not give root node info.
+
+            :returns: String to reproduce the ``SplitEnd``.
+
+        """
+        return '>< ' + ' -> '.join(map(str, self)) + ' ||'
+
+    def snip(self) -> D:
+        """
+        .. admonition:: cut just tip
+
+            :returns: Data from snipped tip,
+                    just return root data if at root.
+
+        """
+        if self._count > 1:
+            data, self._end, self._count = self._end.both() + (self._count - 1,)
+        else:
+            data = self._end.data()
+
+        return data
+
     def cut(self, num: int | None = None) -> tuple[D, ...]:
-        """Cut data off end of ``SplitEnd``.
+        """
+        .. admonition:: Cut data off end of SplitEnd
+
+            Pop "cut" data off Split, just copy root data.
 
-        :param num: Optional number of nodes to cut, default is entire stack.
-        :returns: Tuple of data cut off from end.
+            :param num: Optional number of nodes to cut,
+                        default is entire stack.
+            :returns: Tuple of data cut off from end towards root.
 
         """
         if num is None or num > self._count:
@@ -147,10 +225,13 @@ class SplitEnd[D]:
         return data
 
     def extend(self, *ds: D) -> None:
-        """Add data onto the tip of the SplitEnd. Like adding a hair
-        extension.
+        """
+        .. admonition:: extend SplitEnd with data
 
-        :param ds: data to extend the splitend
+            Add data onto the tip of the SplitEnd. Like adding
+            a hair extension.
+
+            :param ds: data to extend the splitend
 
         """
         for d in ds:
@@ -158,37 +239,48 @@ class SplitEnd[D]:
             self._end, self._count = node, self._count + 1
 
     def peak(self) -> D:
-        """Return the data at end (top) of SplitEnd without consuming it.
+        """
+        .. admonition:: peak at end
 
-        :returns: The data at the end of the SplitEnd.
+            Return the data at end (top) of the SplitEnd
+            without consuming it.
+
+            :returns: The data at the end (tip) of the SplitEnd.
 
         """
         return self._end.data()
 
     def root(self) -> SENode[D]:
         """
-        :returns: The root SENode node of the SplitEnd.
+        .. admonition:: get root
+
+            :returns: The root SENode node of the SplitEnd.
 
         """
         return self._root
 
     def reroot(self, root: SENode[D]) -> 'SplitEnd[D]':
-        """Create a brand new SplitEnd with the same data but different root.
+        """
+        .. admonition:: re-root SplitEnd
 
-        .. note::
+            Create a brand new SplitEnd with the same data but different root.
 
-            Two nodes are compatible root nodes if and only if
+            :returns: New SplitEnd with the same data
+                      and the new ``root``.
+            :raises ValueError: If new and original root nodes
+                                are not compatible.
 
-            - they are both actually root nodes
+            .. note::
 
-              - which implies that their previous nodes are themselves
+                Two nodes are compatible root nodes if and only if
 
-            - their data compare as equal
+                - they are both actually root nodes
 
-              - comparing by identity is too strong for some use cases
+                - which implies that their previous nodes are themselves
 
-        :returns: New SplitEnd with the same data and the new ``root``.
-        :raises ValueError: If new and original root nodes are not compatible.
+                - their data compare as equal
+
+                - comparing by identity is too strong
 
         """
         if not root:
@@ -205,23 +297,14 @@ class SplitEnd[D]:
 
         return SplitEnd(*lifo, root = root)
 
-    def snip(self) -> D:
-        """Snip data off tip of SplitEnd. Just return data if tip is root.
-
-        :returns: Data snipped off tip, just return root data if at root.
-
+    def split(self, *ds: D) -> 'SplitEnd[D]':
         """
-        if self._count > 1:
-            data, self._end, self._count = self._end.both() + (self._count - 1,)
-        else:
-            data = self._end.data()
+        .. admonition:: split
 
-        return data
-
-    def split(self, *ds: D) -> 'SplitEnd[D]':
-        """Split the end and add more data.
+            Split the end and add more data.
 
-        :returns: New instance, same data nodes plus additional ones on end.
+            :returns: New instance, same data nodes plus
+                      additional ones on end. Same root node.
 
         """
         se: SplitEnd[D] = SplitEnd(self._root.data())
@@ -235,11 +318,16 @@ class SplitEnd[D]:
     def fold[T](self, f: Callable[[T, D], T], init: T) -> T: ...
 
     def fold[T](self, f: Callable[[T, D], T], init: T | None = None) -> T:
-        """Reduce with a function, folding from tip to root.
+        """
+        .. admonition:: fold
+
+            Reduce with a function, folding from tip to root.
 
-        :param f: Folding function, first argument is for the accumulator.
-        :param init: Optional initial starting value for the fold.
-        :returns: Reduced value folding from tip to root in natural LIFO order.
+            :param f: Folding function, first argument
+                      is for the accumulator.
+            :param init: Optional initial starting value for the fold.
+            :returns: Reduced value folding from tip to root
+                      in natural LIFO order.
 
         """
         if init is None:
@@ -252,11 +340,15 @@ class SplitEnd[D]:
     def rev_fold[T](self, f: Callable[[T, D], T], init: T) -> T: ...
 
     def rev_fold[T](self, f: Callable[[T, D], T], init: T | None = None) -> T:
-        """Reduce with a function, fold from root to tip.
+        """
+        .. admonition:: reverse fold
+
+            Reduce with a function, fold from root to tip.
 
-        :param f: Folding function, first argument is for the accumulator.
-        :param init: Optional initial starting value for the fold.
-        :returns: Reduced value folding from root to tip.
+            :param f: Folding function, first argument
+                      is for the accumulator.
+            :param init: Optional initial starting value for the fold.
+            :returns: Reduced value folding from root to tip.
 
         """
         if init is None: