pythonic-fp.splitends 0.30.0__py3-none-any.whl → 1.0.1__py3-none-any.whl

pythonic_fp/splitends/__init__.py

@@ -12,10 +12,21 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Pythonic FP - Splitends
+"""Mutable stack objects that can safely share data.
+
+Python package Implementing a singularly linked LIFO queue
+called a ``SplitEnd``. These data structures can safely share
+data nodes between themselves.
+
+- each ``SplitEnd`` is a very simple stateful (mutable) LIFO stack
+- data can be "extended" to or "snipped" off of the end (tip)
+- the "root" value of a ``SplitEnd`` is fixed and cannot be "snipped"
+- 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`` copy method and ``len`` are O(1)
+- in boolean context returns true if the ``SplitEnd`` is not just a "root"
 
-Package implementing a singularly linked LIFO queue called a SplitEnd. These
-data structures can safely share data nodes between themselves.
 """
 
 __author__ = 'Geoffrey R. Scheller'

pythonic_fp/splitends/splitend.py

@@ -12,57 +12,51 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""SplitEnd stack related data structures
-
-With use I am finding this data structure needs some sort of supporting
-infrastructure. Hence I split the original splitend module out to be its own
-subpackage.
-"""
-
-from __future__ import annotations
+"""LIFO stacks safely sharing immutable data between themselves."""
 
 from collections.abc import Callable, Hashable, Iterator
-from typing import Never, TypeVar
-from pythonic_fp.containers.maybe import MayBe as MB
-from .splitend_node import SENode as Node
+from typing import TypeVar
+from pythonic_fp.iterables.folding import maybe_fold_left
+from .splitend_node import SENode
 
 __all__ = ['SplitEnd']
 
 D = TypeVar('D', bound=Hashable)
-T = TypeVar('T')
 
 
 class SplitEnd[D]:
-    """LIFO stacks which can safely share immutable data between themselves.
-
-    - each SplitEnd is a very simple stateful (mutable) LIFO stack
-    - data can be pushed and popped to the stack
-    - the first value pushed onto the SplitEnd becomes it "root"
-    - 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
-    - len() returns the number of elements on the SplitEnd stack
-    - in boolean context, return true if split end is not the "root"
+    """Like one of many "split ends" from a shaft of hair,
+    a ``splitend`` can be "snipped" shorter or "extended"
+    further from its "tip". Its root is irremovable and
+    cannot be "snipped" off. While mutable, different
+    splitends can safely share data with each other.
+
     """
-    __slots__ = '_count', '_top', '_root'
 
-    def __init__(self, root_data: D, *ds: D) -> None:
-        node = Node(root_data, MB[Node[D]]())
-        self._root = MB(node)
-        self._top, self._count = self._root, 1
-        for d in ds:
-            node = Node(d, self._top)
-            self._top, self._count = MB(node), self._count + 1
+    __slots__ = '_count', '_tip', '_root'
+
+    def __init__(self, root_data: D, *data: D) -> None:
+        """
+        :param root_data: irremovable initial data at bottom of stack
+        :param data: removable data to be pushed onto splitend stack
+
+        """
+        node: SENode[D] = SENode(root_data)
+        self._root = node
+        self._tip, self._count = node, 1
+        for d in data:
+            node = SENode(d, self._tip)
+            self._tip, self._count = node, self._count + 1
 
     def __iter__(self) -> Iterator[D]:
-        return iter(self._top.get())
+        return iter(self._tip)
 
     def __reversed__(self) -> Iterator[D]:
         return reversed(list(self))
 
     def __bool__(self) -> bool:
         # Returns true until all data is exhausted
-        return bool(self._top.get())
+        return bool(self._tip)
 
     def __len__(self) -> int:
         return self._count
@@ -82,8 +76,8 @@ class SplitEnd[D]:
         if self._root != other._root:
             return False
 
-        left = self._top.get()
-        right = other._top.get()
+        left = self._tip
+        right = other._tip
         for _ in range(self._count):
             if left is right:
                 return True
@@ -94,40 +88,67 @@ class SplitEnd[D]:
                 right = right._prev.get()
         return True
 
-    def push(self, *ds: D) -> None:
-        """Push data onto the top of the SplitEnd."""
+    def extend(self, *ds: D) -> None:
+        """Add data onto the tip of the SplitEnd. Like adding a hair
+        extension.
+
+        :param ds: data to extend the splitend
+
+        """
         for d in ds:
-            node = Node(d, self._top)
-            self._top, self._count = MB(node), self._count + 1
+            node = SENode(d, self._tip)
+            self._tip, self._count = node, self._count + 1
+
+    def snip(self) -> D:
+        """Snip data off tip of SplitEnd. Just return data if tip is root.
+
+        :returns: data snipped off tip, otherwise root data if tip is root
 
-    def pop(self) -> D | Never:
-        """Pop data off of the top of the SplitEnd.
-        Re-root SplitEnd if root is popped off.
         """
-        data, self._top, self._count = self._top.get().pop2() + (self._count - 1,)
-        if self._count == 0:
-            self._count, self._top = 1, self._root
+        if self._count > 1:
+            data, self._tip, self._count = self._tip.pop2() + (self._count - 1,)
+        else:
+            data = self._tip.peak()
+
         return data
 
     def peak(self) -> D:
-        """Return the data at the top of the SplitEnd, doesn't consume it."""
-        return self._top.get().peak()
+        """Return data from tip of SplitEnd, do not consume it.
+
+        :returns: data at the end of the SplitEnd
+
+        """
+        return self._tip.peak()
+
+    def copy(self) -> 'SplitEnd[D]':
+        """Return a copy of the SplitEnd. O(1) space & time complexity.
 
-    def copy(self) -> SplitEnd[D]:
-        """Return a copy of the SplitEnd.
+        :returns: a new SplitEnd instance with same data and root
 
-        - O(1) space & time complexity.
-        - returns a new instance with same data, including the root
         """
-        se: SplitEnd[D] = SplitEnd(self._root.get().peak())
-        se._count, se._top, se._root = self._count, self._top, self._root
+        se: SplitEnd[D] = SplitEnd(self._root.peak())
+        se._count, se._tip, se._root = self._count, self._tip, self._root
         return se
 
-    def fold[T](self, f: Callable[[T, D], T], init: T | None = None, /) -> T | Never:
-        """Reduce with a function, fold in natural LIFO Order."""
-        if self._top:
-            return self._top.get().fold(f, init)
-        if init is not None:
-            return init
-        msg = 'SE: Folding empty SplitEnd but no initial value supplied'
-        raise ValueError(msg)
+    def fold[T](self, f: Callable[[T, D], T], init: T | None = None) -> T:
+        """Reduce with a function, fold in natural LIFO Order.
+
+        :param f: folding function, for 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
+
+        """
+        return self._tip.fold(f, init)
+
+    def rev_fold[T](self, f: Callable[[T, D], T], init: T | None = None) -> T:
+        """Reduce with a function, fold from root to tip.
+
+        :param f: folding function, for 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
+
+        """
+        # The get() is safe because SplitEnds are never "empty" due to the root.
+        if init is None:
+            return maybe_fold_left(reversed(self), f).get()
+        return maybe_fold_left(reversed(self), f, init).get()

pythonic_fp/splitends/splitend.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 Callable, Hashable, Iterator
+from typing import TypeVar
+
+__all__ = ['SplitEnd']
+
+D = TypeVar('D', bound=Hashable)
+
+class SplitEnd[D]:
+    __slots__ = '_count', '_tip', '_root'
+
+    def __init__(self, root_data: D, *data: D) -> None: ...
+    def __iter__(self) -> Iterator[D]: ...
+    def __reversed__(self) -> Iterator[D]: ...
+    def __bool__(self) -> bool: ...
+    def __len__(self) -> int: ...
+    def __repr__(self) -> str: ...
+    def __str__(self) -> str: ...
+    def __eq__(self, other: object, /) -> bool: ...
+    def extend(self, *ds: D) -> None: ...
+    def snip(self) -> D: ...
+    def peak(self) -> D: ...
+    def copy(self) -> SplitEnd[D]: ...
+    def fold[T](self, f: Callable[[T, D], T], init: T | None = None) -> T: ...
+    def rev_fold[T](self, f: Callable[[T, D], T], init: T | None = None) -> T: ...

pythonic_fp/splitends/splitend_node.py

@@ -14,19 +14,19 @@
 
 """Data node class used privately by class SplitEnd.
 
-Node classes used with graph-like data structures. API designed to be used by
-other data structures which contain these data structures.
+Node classes used to make bush-like graphs. API made public since it
+might prove useful to someone designing other data structures similar
+to a ``splitend``.
+
 """
 
-from __future__ import annotations
 from collections.abc import Callable, Hashable, Iterator
 from typing import cast, TypeVar
-from pythonic_fp.containers.maybe import MayBe as MB
+from pythonic_fp.fptools.maybe import MayBe
 
 __all__ = ['SENode']
 
 D = TypeVar('D', bound=Hashable)
-T = TypeVar('T')
 
 
 class SENode[D]:
@@ -34,31 +34,28 @@ class SENode[D]:
 
     - hashable data node for a end-to-root singularly linked list.
     - designed so multiple splitends can safely share the same data
-    - this type of node always
-
-      - contain data
-      - potential link to previous node
-
-    - nodes point towards a unique "bottom node" with no predecessor
-
-      - in a Boolean context returns true if not at the bottom
-      - multiple bottom nodes can exist
 
     - two nodes compare as equal if
 
       - both their previous Nodes are the same
-      - their data compares as equal
+      - their data compare as equal
 
     - more than one node can point to the same proceeding node
 
       - forming bush like graphs
+
     """
 
     __slots__ = '_data', '_prev'
 
-    def __init__(self, data: D, prev: MB[SENode[D]] = MB()) -> None:
+    def __init__(self, data: D, prev: 'SENode[D] | None' = None) -> None:
+        """
+        :param data: nodes always contain data of type D
+        :param prev: potential link to a previous node
+
+        """
         self._data: D = data
-        self._prev: MB[SENode[D]] = prev
+        self._prev: MayBe[SENode[D]] = MayBe(prev) if prev is not None else MayBe()
 
     def __iter__(self) -> Iterator[D]:
         node = self
@@ -68,7 +65,7 @@ class SENode[D]:
         yield node._data
 
     def __bool__(self) -> bool:
-        return self._prev != MB()
+        return self._prev != MayBe()
 
     def __eq__(self, other: object) -> bool:
         if not isinstance(other, type(self)):
@@ -81,22 +78,47 @@ class SENode[D]:
         return False
 
     def peak(self) -> D:
-        """Return contained data"""
+        """Returns contained data.
+
+        :returns: data stored in SENode
+
+        """
         return self._data
 
-    def pop2(self) -> tuple[D, MB[SENode[D]]]:
-        """Return the data at the *end* and potential *tail*."""
-        return self._data, self._prev
+    def pop2(self) -> 'tuple[D, SENode[D]]':
+        """Return the data at the tip and the tail of the SENode.
+
+        :returns: a tuple of the data at the tip and the previous SENode
+
+        """
+        if self._prev:
+            return self._data, self._prev.get()
+        return self._data, self
+
+    def push(self, data: D) -> 'SENode[D]':
+        """Push data onto the queue and return a new node containing the data.
 
-    def push(self, data: D) -> SENode[D]:
-        """Push data onto the queue and return a new node containing the data."""
-        return SENode(data, MB(self))
+        :param data: data to be pushed onto the SENode stack
+        :returns: the resulting SENode[D] representing the top of the stack
+
+        """
+        return SENode(data, self)
 
     def fold[T](self, f: Callable[[T, D], T], init: T | None = None) -> T:
-        """Reduce data across linked nodes.
+        """Fold data across linked nodes with a function..
+
+        .. code:: python
+
+            def fold[T](
+                    self,
+                    f: Callable([T, D], T],
+                    init: T | None = None
+            ) -> T
+
+        :param f: folding function, first argument is for accumulated value
+        :param init: optional initial starting value for the fold
+        :returns: reduced value folding from end to root in natural LIFO order
 
-        - with a function and an optional starting value
-        - reduces in natural LIFO order, from self to the root
         """
         if init is None:
             acc: T = cast(T, self._data)

pythonic_fp/splitends/splitend_node.pyi

@@ -0,0 +1,36 @@
+# 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, Hashable, Iterator
+from typing import TypeVar
+from pythonic_fp.fptools.maybe import MayBe
+
+__all__ = ['SENode']
+
+D = TypeVar('D', bound=Hashable)
+
+class SENode[D]:
+    __slots__ = '_data', '_prev'
+
+    _data: D
+    _prev: MayBe[SENode[D]]
+
+    def __init__(self, data: D, prev: SENode[D] | None = None) -> None: ...
+    def __iter__(self) -> Iterator[D]: ...
+    def __bool__(self) -> bool: ...
+    def __eq__(self, other: object) -> bool: ...
+    def peak(self) -> D: ...
+    def pop2(self) -> tuple[D, SENode[D]]: ...
+    def push(self, data: D) -> SENode[D]: ...
+    def fold[T](self, f: Callable[[T, D], T], init: T | None = None) -> T: ...

pythonic_fp_splitends-1.0.1.dist-info/METADATA

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: pythonic-fp-splitends
+Version: 1.0.1
+Summary: Mutable stack objects 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
+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: Typing :: Typed
+License-File: LICENSE
+Requires-Dist: pythonic-fp-fptools>=5.1.0
+Requires-Dist: pythonic-fp-iterables>=5.1.0
+Requires-Dist: pytest>=8.4.1 ; extra == "test"
+Requires-Dist: pythonic-fp-gadgets>=3.0.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/releases.html
+Project-URL: Homepage, https://github.com/grscheller/pythonic-fp/blob/main/README.md
+Project-URL: Source, https://github.com/grscheller/pythonic-fp-splitends
+Provides-Extra: test
+
+Pythonic FP - SplitEnds
+=======================
+
+PyPI project
+`pythonic-fp.splitends <https://pypi.org/project/pythonic-fp.splitends/>`_.
+
+Python package Implementing a singularly linked LIFO queue called
+a ``SplitEnd``. These data structures can safely share data nodes
+between themselves.
+
+- each ``SplitEnd`` is a very simple stateful (mutable) LIFO stack
+- data can be "extended" to or "snipped" off of the end (tip)
+- the "root" value of a ``SplitEnd`` is fixed and cannot be "snipped"
+- 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`` copy method and ``len`` are O(1)
+- in boolean context returns true if the ``SplitEnd`` is not just a "root"
+
+This PyPI project is part of of the grscheller
+`pythonic-fp namespace projects <https://github.com/grscheller/pythonic-fp/blob/main/README.md>`_
+
+**Warning:** This PyPI project is Alpha level software and subject to
+change.
+
+Documentation
+-------------
+
+Documentation for this project is hosted on
+`GitHub Pages
+<https://grscheller.github.io/pythonic-fp/splitends/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_splitends-1.0.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+pythonic_fp/splitends/__init__.py,sha256=gZzfqx_ODj0p32Zije6mFB-VUovxn2e8MGXjtpqcP2g,1457
+pythonic_fp/splitends/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pythonic_fp/splitends/splitend.py,sha256=k5oBCoTDL3OGKAgJ9bYeHZ5JL-FnRKwdQ7mEqS1e3x0,5018
+pythonic_fp/splitends/splitend.pyi,sha256=xBJHTBdMO0VzeyhIUTiflm3BA3Pfq1GOjy9kvJOju1Q,1437
+pythonic_fp/splitends/splitend_node.py,sha256=Fr74SpejGuLPK4giv1jKslX7NXxYe6Zh31Q3HDyAvEE,3894
+pythonic_fp/splitends/splitend_node.pyi,sha256=3vmKwiQBsJV0v043fkA6CVPaNSFeJ02chUuwIs3G-YY,1273
+pythonic_fp_splitends-1.0.1.dist-info/licenses/LICENSE,sha256=IJMkVWQUVy-SonK6SMaMotDQ6Zb-lVi2bUTiGp1GUO8,10774
+pythonic_fp_splitends-1.0.1.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+pythonic_fp_splitends-1.0.1.dist-info/METADATA,sha256=Q1-I-USkH1CwBTKIJ82ctnvwuLFKZxDGvQmawdzLHkY,2575
+pythonic_fp_splitends-1.0.1.dist-info/RECORD,,

pythonic_fp_splitends-0.30.0.dist-info/METADATA

@@ -1,55 +0,0 @@
-Metadata-Version: 2.4
-Name: pythonic-fp.splitends
-Version: 0.30.0
-Summary: Pythonic FP - Splitends
-Keywords: SplitEnd,lifo,stack
-Author-email: "Geoffrey R. Scheller" <geoffrey@scheller.com>
-Requires-Python: >=3.12
-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: Typing :: Typed
-License-File: LICENSE
-Requires-Dist: pythonic-fp.containers >=2.0.0
-Project-URL: Changelog, https://grscheller.github.io/pythonic-fp-splitends/html/changelog.html
-Project-URL: Documentation, https://grscheller.github.io/pythonic-fp-splitends/html/
-Project-URL: Homepage, https://github.com/grscheller/pythonic-fp/blob/main/README.md
-Project-URL: Source, https://github.com/grscheller/pythonic-fp-splitends
-
-# Pythonic FP - SplitEnds
-
-PyPI project
-[pythonic-fp.splitends](https://pypi.org/project/pythonic-fp.splitends/)
-implementing a singularly linked data structures allowing data to be
-safely shared between multiple instances.
-
-- Singularly link stack with shareable data nodes
-  - *module* `pythonic_fp.splitends.splitend`
-  - *class* `SplitEnd`
-
-- Shareable nodes used by SplitEnd instances
-  - *module* `pythonic_fp.splitends.splitend_node`
-  - *class* `SENode`
-    - shareable nodes used by SplitEnd instances
-      - this class is designed to be inaccessible to client code
-
-This PyPI project is part of of the grscheller
-[pythonic-fp namespace projects](https://github.com/grscheller/pythonic-fp/blob/main/README.md).
-
-**Warning:** This PyPI project is Alpha level software and subject to
-change. It will probably remain Alpha for quite a while.
-
-## Documentation
-
-Documentation hosted on
-[GitHub Pages](https://grscheller.github.io/pythonic-fp-splitends/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_splitends-0.30.0.dist-info/RECORD

@@ -1,8 +0,0 @@
-pythonic_fp/splitends/__init__.py,sha256=hAswthv0JMpJlJqid_hwgIO1OEYRqGSRKcACKBdvmUw,898
-pythonic_fp/splitends/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pythonic_fp/splitends/splitend.py,sha256=C4Zw_s02oAo9ivItinbeavJWFSuyWRx8QdLxa9MQAe0,4608
-pythonic_fp/splitends/splitend_node.py,sha256=T0bAGMY4dL8Vv5w5z6BYX6pUrNQhXHaLVZo2XTtmvFI,3362
-pythonic_fp_splitends-0.30.0.dist-info/licenses/LICENSE,sha256=IJMkVWQUVy-SonK6SMaMotDQ6Zb-lVi2bUTiGp1GUO8,10774
-pythonic_fp_splitends-0.30.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
-pythonic_fp_splitends-0.30.0.dist-info/METADATA,sha256=nYdAplEfe5m2LH5X2Yc1fOIZ3lPijnVa-jbfzjJ4vUs,2091
-pythonic_fp_splitends-0.30.0.dist-info/RECORD,,