pythonic-fp.containers 2.0.0__py3-none-any.whl → 3.0.0__py3-none-any.whl

pythonic_fp/containers/queues/fifo.py

@@ -0,0 +1,145 @@
+# 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.
+
+"""Stateful First-In-First-Out (FIFO) Queue data structure.
+
+- O(1) pops
+- O(1) amortized pushes
+- in a Boolean context, true if not empty, false if empty
+- will automatically increase storage capacity when needed
+- neither indexable nor sliceable by design
+- O(1) length determination
+
+"""
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Iterator
+from typing import TypeVar
+from pythonic_fp.circulararray.auto import CA
+from pythonic_fp.fptools.maybe import MayBe
+
+__all__ = ['FIFOQueue', 'fifo_queue']
+
+D = TypeVar('D')
+
+
+class FIFOQueue[D]:
+
+    __slots__ = ('_ca',)
+
+    def __init__(self, *dss: Iterable[D]) -> None:
+        """Initial data in natural FIFO order, newest to oldest.
+
+        :param dss: takes up to one iterable
+        :raises ValueError: if more than 1 iterable is given
+
+        """
+        if (size := len(dss)) > 1:
+            msg = f'FIFOQueue expects at most 1 iterable argument, got {size}'
+            raise ValueError(msg)
+        self._ca = CA(dss[0]) if size == 1 else CA()
+
+    def __bool__(self) -> bool:
+        return len(self._ca) > 0
+
+    def __len__(self) -> int:
+        return len(self._ca)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, FIFOQueue):
+            return False
+        return self._ca == other._ca
+
+    def __iter__(self) -> Iterator[D]:
+        return iter(list(self._ca))
+
+    def __repr__(self) -> str:
+        if len(self) == 0:
+           return 'FIFOQueue()'
+        return 'FIFOQueue(' + ', '.join(map(repr, self._ca)) + ')'
+
+    def __str__(self) -> str:
+        return '<< ' + ' < '.join(map(str, self)) + ' <<'
+
+    def copy(self) -> FIFOQueue[D]:
+        """Shallow copy.
+
+        :return: shallow copy of the FIFOQueue
+
+        """
+        return FIFOQueue(self._ca)
+
+    def push(self, *ds: D) -> None:
+        """Push data onto FIFOQueue.
+
+        :param ds: data items to be pushed onto FIFOQueue
+
+        """
+        self._ca.pushr(*ds)
+
+    def pop(self) -> MayBe[D]:
+        """Pop oldest data item off of FIFOQueue.
+
+        :return: MayBe of popped data item if queue was not empty, empty MayBe otherwise
+
+        """
+        if self._ca:
+            return MayBe(self._ca.popl())
+        return MayBe()
+
+    def peak_last_in(self) -> MayBe[D]:
+        """Peak at newest data item on queue.
+
+        :return: MayBe of newest data item on queue, empty MayBe if queue empty
+        
+        """
+        if self._ca:
+            return MayBe(self._ca[-1])
+        return MayBe()
+
+    def peak_next_out(self) -> MayBe[D]:
+        """Peak at oldest data item on queue.
+
+        :return: MayBe of oldest data item on queue, empty MayBe if queue empty
+
+        """
+        if self._ca:
+            return MayBe(self._ca[0])
+        return MayBe()
+
+    def fold[T](self, f: Callable[[T, D], T], start: T | None = None) -> MayBe[T]:
+        """Reduces FIFOQueue in natural FIFO Order, oldest to newest.
+
+        :param f: reducing function, first argument is for accumulator
+        :param start: optional starting value
+        :return: MayBe of reduced value with f, empty MayBe if queue empty and no starting value given
+
+        """
+        if start is None:
+            if not self._ca:
+                return MayBe()
+        return MayBe(self._ca.foldl(f, start))
+
+    def map[U](self, f: Callable[[D], U]) -> FIFOQueue[U]:
+        """Map f over the FIFOQueue, retain original order.
+
+        :return: new FIFOQueue instance
+
+        """
+        return FIFOQueue(map(f, self._ca))
+
+
+def fifo_queue[D](*ds: D) -> FIFOQueue[D]:
+    """FIFOQueue factory function."""
+    return FIFOQueue(ds)

pythonic_fp/containers/queues/lifo.py

@@ -0,0 +1,136 @@
+# 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.
+
+"""Stateful Last-In-First-Out (LIFO) Queue data structure.
+
+- O(1) pops
+- O(1) amortized pushes
+- in a Boolean context, true if not empty, false if empty
+- will automatically increase storage capacity when needed
+- neither indexable nor sliceable by design
+- O(1) length determination
+
+"""
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Iterator
+from typing import TypeVar
+from pythonic_fp.circulararray.auto import CA
+from pythonic_fp.fptools.function import swap
+from pythonic_fp.fptools.maybe import MayBe
+
+__all__ = ['LIFOQueue', 'lifo_queue']
+
+D = TypeVar('D')
+
+
+class LIFOQueue[D]:
+
+    __slots__ = ('_ca',)
+
+    def __init__(self, *dss: Iterable[D]) -> None:
+        """Initial data in natural LIFO order, oldest to newest.
+
+        :param dss: takes up to one iterable
+        :raises ValueError: if more than 1 iterable is given
+
+        """
+        if (size := len(dss)) > 1:
+            msg = f'LIFOQueue expects at most 1 iterable argument, got {size}'
+            raise ValueError(msg)
+        self._ca = CA(dss[0]) if size == 1 else CA()
+
+    def __bool__(self) -> bool:
+        return len(self._ca) > 0
+
+    def __len__(self) -> int:
+        return len(self._ca)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, LIFOQueue):
+            return False
+        return self._ca == other._ca
+
+    def __iter__(self) -> Iterator[D]:
+        return reversed(list(self._ca))
+
+    def __repr__(self) -> str:
+        if len(self) == 0:
+            return 'LIFOQueue()'
+        return 'LIFOQueue(' + ', '.join(map(repr, self._ca)) + ')'
+
+    def __str__(self) -> str:
+        return '|| ' + ' > '.join(map(str, self)) + ' ><'
+
+    def copy(self) -> LIFOQueue[D]:
+        """Shallow copy.
+
+        :return: shallow copy of the LIFOQueue
+
+        """
+        return LIFOQueue(reversed(self._ca))
+
+    def push(self, *ds: D) -> None:
+        """Push data onto LIFOQueue.
+
+        :param ds: data items to be pushed onto LIFOQueue
+
+        """
+        self._ca.pushr(*ds)
+
+    def pop(self) -> MayBe[D]:
+        """Pop newest data item off of LIFOQueue.
+
+        :return: MayBe of popped data item if queue was not empty, empty MayBe otherwise
+
+        """
+        if self._ca:
+            return MayBe(self._ca.popr())
+        return MayBe()
+
+    def peak(self) -> MayBe[D]:
+        """Peak at newest data item on queue.
+
+        :return: MayBe of newest data item on queue, empty MayBe if queue empty
+
+        """
+        if self._ca:
+            return MayBe(self._ca[-1])
+        return MayBe()
+
+    def fold[T](self, f: Callable[[T, D], T], start: T | None = None) -> MayBe[T]:
+        """Reduces LIFOQUEUE in natural LIFO Order, newest to oldest.
+
+        :param f: reducing function, first argument is for accumulator
+        :param start: optional starting value
+        :return: MayBe of reduced value with f, empty MayBe if queue empty and no starting value given
+
+        """
+        if start is None:
+            if not self._ca:
+                return MayBe()
+        return MayBe(self._ca.foldr(swap(f), start))
+
+    def map[U](self, f: Callable[[D], U]) -> LIFOQueue[U]:
+        """Map f over the LIFOQueue, retain original order.
+
+        :return: new LIFOQueue instance
+
+        """
+        return LIFOQueue(reversed(CA(map(f, reversed(self._ca)))))
+
+
+def lifo_queue[D](*ds: D) -> LIFOQueue[D]:
+    """LIFOQueue factory function."""
+    return LIFOQueue(ds)

pythonic_fp_containers-3.0.0.dist-info/METADATA

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: pythonic-fp-containers
+Version: 3.0.0
+Summary: Package of container like data structures.
+Keywords: boxes,functional_tuple,immutable_list,queue,fifo,lifo,dqueue,dequeue
+Author-email: "Geoffrey R. Scheller" <geoffrey@scheller.com>
+Requires-Python: >=3.12
+Description-Content-Type: text/x-rst
+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: Typing :: Typed
+License-File: LICENSE
+Requires-Dist: pythonic-fp-circulararray>= 5.3.0
+Requires-Dist: pythonic-fp-fptools>=5.0.0
+Requires-Dist: pythonic-fp-iterables>=5.0.0
+Requires-Dist: pythonic-fp-singletons>=1.0.0
+Requires-Dist: pytest>=8.4.1 ; extra == "test"
+Requires-Dist: pythonic-fp-splitends>=1.0.0 ; extra == "test"
+Project-URL: Changelog, https://github.com/grscheller/pythonic-fp-containers/blob/main/CHANGELOG.rst
+Project-URL: Documentation, https://grscheller.github.io/pythonic-fp/containers/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-containers
+Provides-Extra: test
+
+Pythonic FP - Containers
+========================
+
+PyPI project
+`pythonic-fp.containers <https://pypi.org/project/pythonic-fp.containers>`_.
+
+Python package of container like data structures.
+
++------------------+------------------------------------------------------+
+| Description      |                        Module                        |
++==================+======================================================+
+| Single item box  | *module* ``pythonic_fp.containers.box``              |
+| Functional tuple | *module* ``pythonic_fp.containers.functional_tuple`` |
+| Immutable list   | *module* ``pythonic_fp.containers.immutable_list``   |
++------------------+------------------------------------------------------+
+
+**DEPRECATION WARNING:** ``pythonic_fp.fptools.box`` as been deprecated.
+Use ``pythonic_fp.box`` instead.
+
+This PyPI project is part of of the grscheller
+`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/containers/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_containers-3.0.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+pythonic_fp/containers/__init__.py,sha256=N5-djJadhpE6h8bg31AtUrqami8RPjsiUYwlwrPpYnI,1603
+pythonic_fp/containers/functional_tuple.py,sha256=AffGbovvg0WpnImZwzhD47djLps27Ns29eKzFosXOC4,5799
+pythonic_fp/containers/immutable_list.py,sha256=SGfGKRyDyBylrNn9qvpoKog531RKAusRsxhtnVa5Rps,6677
+pythonic_fp/containers/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pythonic_fp/containers/queues/__init__.py,sha256=GJdzodYt32pADih2UHOiR9U4jfZ6SQSw6PsCYZ2r1wg,1459
+pythonic_fp/containers/queues/de.py,sha256=lBoZE8SRe6__NEFpNiqKhumDtdIVvm7S7HMojEUAL1s,5288
+pythonic_fp/containers/queues/fifo.py,sha256=Q9luMfZzSJzGU3aJwnJ5OIeT6hs-6ieh70b5wYGodI4,4221
+pythonic_fp/containers/queues/lifo.py,sha256=xudvLpEvqv9bl3bCqTiwlC2IDZ9A5kHVl-aIjNAKyeA,4031
+pythonic_fp/containers/queues/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pythonic_fp_containers-3.0.0.dist-info/licenses/LICENSE,sha256=IJMkVWQUVy-SonK6SMaMotDQ6Zb-lVi2bUTiGp1GUO8,10774
+pythonic_fp_containers-3.0.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+pythonic_fp_containers-3.0.0.dist-info/METADATA,sha256=UeoEZi26JqOUc0AYxcwpr8FrxsNEA7XOu5IMySlm_jk,2672
+pythonic_fp_containers-3.0.0.dist-info/RECORD,,

pythonic_fp/containers/box.py

@@ -1,159 +0,0 @@
-# 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.
-
-"""Stateful container holds at most one item of a given type."""
-
-from __future__ import annotations
-
-__all__ = ['Box']
-
-from collections.abc import Callable, Iterator
-from typing import cast, Final, Never, overload, TypeVar
-from pythonic_fp.fptools.singletons import Sentinel
-
-D = TypeVar('D')
-
-_sentinel: Final[Sentinel] = Sentinel('Box')
-
-class Box[D]:
-    """Container holding at most one item of a given type
-
-    - where ``Box(item)`` contains at most one item of type ``~D``
-
-      - ``Box()`` creates an empty container
-      - can store any item of any type, including ``None``
-    """
-
-    __slots__ = ('_item',)
-    __match_args__ = ('_item',)
-
-    T = TypeVar('T')
-
-    @overload
-    def __init__(self) -> None: ...
-    @overload
-    def __init__(self, value: D) -> None: ...
-
-    def __init__(self, value: D | Sentinel = Sentinel('Box')) -> None:
-        """Initialize Box with an "optional" initial value.
-
-           :param value: "optional" initial value
-           :type value: ~D
-        """
-        self._item: D | Sentinel = value
-
-    def __bool__(self) -> bool:
-        return self._item is not Sentinel('Box')
-
-    def __iter__(self) -> Iterator[D]:
-        if self:
-            yield cast(D, self._item)
-
-    def __repr__(self) -> str:
-        if self:
-            return 'Box(' + repr(self._item) + ')'
-        return 'Box()'
-
-    def __len__(self) -> int:
-        return 1 if self else 0
-
-    def __eq__(self, other: object) -> bool:
-        if not isinstance(other, type(self)):
-            return False
-
-        if self._item is other._item:
-            return True
-        if self._item == other._item:
-            return True
-        return False
-
-    @overload
-    def get(self) -> D | Never: ...
-    @overload
-    def get(self, alt: D) -> D: ...
-    @overload
-    def get(self, alt: Sentinel) -> D | Never: ...
-
-    def get(self, alt: D | Sentinel = Sentinel('Box')) -> D | Never:
-        """Return the contained value if it exists, otherwise an alternate value.
-
-        :rtype: ~D 
-        :raises ValueError: when an alternate value is not provided but needed
-        """
-        if self._item is not _sentinel:
-            return cast(D, self._item)
-        if alt is _sentinel:
-            msg = 'Box: get from empty Box with no alt return value provided'
-            raise ValueError(msg)
-        return cast(D, alt)
-
-    def pop(self) -> D | Never:
-        """Pop the value if Box is not empty.
-
-        :rtype: ~D
-        :raises ValueError: if box is empty
-        """
-        if self._item is _sentinel:
-            msg = 'Box: Trying to pop an item from an empty Box'
-            raise ValueError(msg)
-        popped = cast(D, self._item)
-        self._item = _sentinel
-        return popped
-
-    def push(self, item: D) -> None | Never:
-        """Push an item in an empty Box.
-
-        :raises ValueError: if box is not empty
-        """
-        if self._item is Sentinel('Box'):
-            self._item = item
-        else:
-            msg = 'Box: Trying to push an item in an empty Box'
-            raise ValueError(msg)
-        return None
-
-    def put(self, item: D) -> None:
-        """Put an item in the Box. Discard any previous contents."""
-        self._item = item
-
-    def exchange(self, new_item: D) -> D | Never:
-        """Exchange an item with what is in the Box.
-
-        :rtype: ~D
-        :raises ValueError: if box is empty
-        """
-        if self._item is _sentinel:
-            msg = 'Box: Trying to exchange items using an empty Box'
-            raise ValueError(msg)
-        popped = cast(D, self._item)
-        self._item = new_item
-        return popped
-
-    def map[T](self, f: Callable[[D], T]) -> Box[T]:
-        """Map function ``f`` over contents.
-
-        :return: a new instance
-        """
-        if self._item is Sentinel('Box'):
-            return Box()
-        return Box(f(cast(D, self._item)))
-
-    def bind[T](self, f: Callable[[D], Box[T]]) -> Box[T]:
-        """Flatmap ``Box`` with function ``f``.
-
-        :return: a new instance
-        """
-        if self._item is _sentinel:
-            return Box()
-        return f(cast(D, self._item))