pythonic-fp-queues 5.1.0__py3-none-any.whl → 5.1.2__py3-none-any.whl

pythonic_fp/queues/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2023-2024 Geoffrey R. Scheller
+# 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.
@@ -14,20 +14,18 @@
 
 """
 Queues
-======
+------
 
-+-------------------------+-----------+--------------------------+
-| module                  | class     | name                     |
-+=========================+===========+==========================+
-| pythonic_fp.queues.fifo | FIFOQueue | First-In-First-Out Queue |
-+-------------------------+-----------+--------------------------+
-| pythonic_fp.queues.lifo | LIFOQueue | Last-In-First-Out Queue  |
-+-------------------------+-----------+--------------------------+
-| pythonic_fp.queues.de   | DEQueue   | Double-Ended Queue       |
-+-------------------------+-----------+--------------------------+
+.. admonition:: Stateful Queues
+
+    By limiting how their data can be accessed, each queue type
+    supports different algorithmic use cases.
+
+    Sometimes the power of a data structure comes not what it empowers
+    you to do, but what it prevents you from doing to yourself.
 
 """
 
 __author__ = 'Geoffrey R. Scheller'
-__copyright__ = 'Copyright (c) 2023-2025 Geoffrey R. Scheller'
+__copyright__ = 'Copyright (c) 2023-2026 Geoffrey R. Scheller'
 __license__ = 'Apache License 2.0'

pythonic_fp/queues/de.py

@@ -1,4 +1,4 @@
-# Copyright 2023-2025 Geoffrey R. Scheller
+# 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.
@@ -21,14 +21,18 @@ __all__ = ['DEQueue', 'de_queue']
 
 
 class DEQueue[D]:
-    """Stateful Double-Ended (DE) Queue data structure.
+    """
+    .. admonition:: DEQueue
+
+        Stateful Double-Ended (DE) Queue data structure.
 
-    - O(1) pops each end
-    - O(1) amortized pushes each end
-    - O(1) length determination
-    - in a Boolean context, truthy if not empty, falsy if empty
-    - will automatically increase storage capacity when needed
-    - neither indexable nor sliceable by design
+        - has a left and a right side
+        - O(1) pops each end
+        - O(1) amortized pushes each end
+        - O(1) length determination
+        - in a Boolean context, truthy if not empty, falsy if empty
+        - will automatically increase storage capacity when needed
+        - neither indexable nor sliceable by design
 
     """
 
@@ -36,9 +40,11 @@ class DEQueue[D]:
 
     def __init__(self, *dss: Iterable[D]) -> None:
         """
-        :param dss: "Optionally" takes a single iterable to initialize data in FIFO order.
-        :raises TypeError: When ``dss[0]`` not Iterable.
-        :raises ValueError: If more than 1 iterable is given.
+        :param dss: Takes 0 or 1 iterable parameters. Populates
+                    queue from the iterable left to right.
+        :raises TypeError: When passed a non-iterable parameter.
+        :raises ValueError: When more than one parameter is given.
+
         """
         if (size := len(dss)) > 1:
             msg = f'DEQueue expects at most 1 argument, got {size}'
@@ -46,6 +52,12 @@ class DEQueue[D]:
         self._ca = CA(dss[0]) if size == 1 else CA()
 
     def __bool__(self) -> bool:
+        """
+        .. admonition:: Truthiness
+
+            Queue truthy when non-empty, falsy when empty.
+
+        """
         return len(self._ca) > 0
 
     def __len__(self) -> int:
@@ -57,9 +69,25 @@ class DEQueue[D]:
         return self._ca == other._ca
 
     def __iter__(self) -> Iterator[D]:
+        """
+        .. admonition:: Iteration
+
+            Iterate over current state left to right.
+
+        :returns: An iterator of the data.
+
+        """
         return iter(list(self._ca))
 
     def __reversed__(self) -> Iterator[D]:
+        """
+        .. admonition:: Iteration
+
+            Iterate over current state right to left.
+
+        :returns: An iterator of the data.
+
+        """
         return reversed(list(self._ca))
 
     def __repr__(self) -> str:
@@ -71,57 +99,89 @@ class DEQueue[D]:
         return '>< ' + ' | '.join(map(str, self)) + ' ><'
 
     def copy(self) -> 'DEQueue[D]':
-        """Shallow copy.
+        """
+        .. admonition:: Shallow copy
+
+            Make a shallow copy of the queue.
+
+        :returns: Shallow copy of the ``DEQueue``.
 
-        :returns: Shallow copy of the DEQueue.
         """
         return DEQueue(self._ca)
 
     def pushl(self, *ds: D) -> None:
-        """Push data onto left side of DEQueue.
+        """
+        .. admonition:: Push left
+
+            Push data onto left side of ``DEQueue``.
+
+        :param ds: Data to be pushed onto ``DEQueue`` from the left.
 
-        :param ds: Items to be pushed onto DEQueue from the left.
         """
         self._ca.pushl(*ds)
 
     def pushr(self, *ds: D) -> None:
-        """Push data onto right side of DEQueue.
+        """
+        .. admonition:: Push right
+
+            Push data onto right side of ``DEQueue``.
+
+        :param ds: Data to be pushed onto ``DEQueue`` from the right.
 
-        :param ds: Items to be pushed onto DEQueue from the right.
         """
         self._ca.pushr(*ds)
 
     def popl(self) -> MayBe[D]:
-        """Pop next item from left side DEQueue, if it exists.
+        """
+        .. admonition:: Pop left
+
+            Pop next item from left side ``DEQueue``, if it exists.
+
+        :returns: ``MayBe`` of popped item if queue was not empty,
+                  empty ``MayBe`` otherwise.
 
-        :returns: MayBe of popped item if queue was not empty, empty MayBe otherwise.
         """
         if self._ca:
             return MayBe(self._ca.popl())
         return MayBe()
 
     def popr(self) -> MayBe[D]:
-        """Pop next item off right side DEQueue, if it exists.
+        """
+        .. admonition:: Pop right
+
+            Pop next item off right side ''DEQueue``, if it exists.
+
+        :returns: ``MayBe`` of popped item if queue was not empty,
+                  empty ``MayBe`` otherwise.
 
-        :returns: MayBe of popped item if queue was not empty, empty MayBe otherwise.
         """
         if self._ca:
             return MayBe(self._ca.popr())
         return MayBe()
 
     def peakl(self) -> MayBe[D]:
-        """Peak left side of DEQueue. Does not consume item.
+        """
+        .. admonition:: Peak left
+
+            Peak left side of ``DEQueue``. Does not consume item.
+
+        :returns: ``MayBe`` of leftmost item if queue not empty,
+                  empty ``MayBe`` otherwise.
 
-        :returns: MayBe of leftmost item if queue not empty, empty MayBe otherwise.
         """
         if self._ca:
             return MayBe(self._ca[0])
         return MayBe()
 
     def peakr(self) -> MayBe[D]:
-        """Peak right side of DEQueue. Does not consume item.
+        """
+        .. admonition:: Peak right
+
+            Peak right side of ``DEQueue``. Does not consume item.
+
+        :returns: ``MayBe`` of rightmost item if queue not empty,
+                  empty ``MayBe`` otherwise.
 
-        :returns: MayBe of rightmost item if queue not empty, empty MayBe otherwise.
         """
         if self._ca:
             return MayBe(self._ca[-1])
@@ -133,11 +193,16 @@ class DEQueue[D]:
     def foldl[L](self, f: Callable[[L, D], L], start: L) -> MayBe[L]: ...
 
     def foldl[L](self, f: Callable[[L, D], L], start: L | None = None) -> MayBe[L]:
-        """Reduces DEQueue left to right.
+        """
+        .. admonition:: Fold left
+
+            Reduce ``DEQueue`` left to right.
 
         :param f: Reducing function, first argument is for accumulator.
         :param start: Optional starting value.
-        :returns: MayBe of reduced value with f, empty MayBe if queue empty and no starting value given.
+        :returns: ``MayBe`` of reduced value with f, empty ``MayBe`` if
+                  queue empty and no starting value given.
+
         """
         if start is None:
             if not self._ca:
@@ -151,11 +216,16 @@ class DEQueue[D]:
     def foldr[R](self, f: Callable[[D, R], R], start: R) -> MayBe[R]: ...
 
     def foldr[R](self, f: Callable[[D, R], R], start: R | None = None) -> MayBe[R]:
-        """Reduces DEQueue right to left.
+        """
+        .. admonition:: Fold right
+
+            Reduce ``DEQueue`` right to left.
 
         :param f: Reducing function, second argument is for accumulator.
         :param start: Optional starting value.
-        :returns: MayBe of reduced value with f, empty MayBe if queue empty and no starting value given.
+        :returns: ``MayBe`` of reduced value with f, empty ``MayBe`` if
+                  queue empty and no starting value given.
+
         """
         if start is None:
             if not self._ca:
@@ -164,22 +234,31 @@ class DEQueue[D]:
         return MayBe(self._ca.foldr(f, start))
 
     def map[U](self, f: Callable[[D], U]) -> 'DEQueue[U]':
-        """Map left to right.
+        """
+        .. admonition:: Map
+
+            Map left to right.
 
-        .. tip::
+            .. tip::
 
-            Order map done does not matter if ``f`` is pure.
+                Order map done does not matter if ``f`` is pure.
 
         :param f: Function to map over queue.
-        :returns: New DEQueue instance, retain original order.
+        :returns: New ``DEQueue`` instance, retain original order.
+
         """
         return DEQueue(map(f, self._ca))
 
 
 def de_queue[D](*ds: D) -> DEQueue[D]:
-    """DEQueue factory function.
+    """
+    .. admonition:: Create DEQueue
+
+        Factory function to create a ``DEQueue``
+        instance from the function's arguments.
+
+    :param ds: Initial data to be pushed on right to left.
+    :returns: A new ``DEQueue`` instance.
 
-    :param ds: Initial items as if pushed on from right to left.
-    :returns: DEQueue with items initialized in FIFO order.
     """
     return DEQueue(ds)

pythonic_fp/queues/de.pyi

@@ -0,0 +1,31 @@
+from collections.abc import Callable, Iterable, Iterator
+from pythonic_fp.fptools.maybe import MayBe
+from typing import overload
+
+__all__ = ['DEQueue', 'de_queue']
+
+class DEQueue[D]:
+    def __init__(self, *dss: Iterable[D]) -> None: ...
+    def __bool__(self) -> bool: ...
+    def __len__(self) -> int: ...
+    def __eq__(self, other: object) -> bool: ...
+    def __iter__(self) -> Iterator[D]: ...
+    def __reversed__(self) -> Iterator[D]: ...
+    def copy(self) -> DEQueue[D]: ...
+    def pushl(self, *ds: D) -> None: ...
+    def pushr(self, *ds: D) -> None: ...
+    def popl(self) -> MayBe[D]: ...
+    def popr(self) -> MayBe[D]: ...
+    def peakl(self) -> MayBe[D]: ...
+    def peakr(self) -> MayBe[D]: ...
+    @overload
+    def foldl[L](self, f: Callable[[D, D], D]) -> MayBe[D]: ...
+    @overload
+    def foldl[L](self, f: Callable[[L, D], L], start: L) -> MayBe[L]: ...
+    @overload
+    def foldr[R](self, f: Callable[[D, D], D]) -> MayBe[D]: ...
+    @overload
+    def foldr[R](self, f: Callable[[D, R], R], start: R) -> MayBe[R]: ...
+    def map[U](self, f: Callable[[D], U]) -> DEQueue[U]: ...
+
+def de_queue[D](*ds: D) -> DEQueue[D]: ...

pythonic_fp/queues/fifo.py

@@ -1,4 +1,4 @@
-# Copyright 2023-2024 Geoffrey R. Scheller
+# 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.
@@ -21,14 +21,17 @@ __all__ = ['FIFOQueue', 'fifo_queue']
 
 
 class FIFOQueue[D]:
-    """Stateful First-In-First-Out (FIFO) Queue data structure.
+    """
+    .. admonition:: FIFOQueue
+
+        Stateful First-In-First-Out (FIFO) Queue data structure.
 
-    - O(1) pops
-    - O(1) amortized pushes
-    - O(1) length determination
-    - in a Boolean context, truthy if not empty, falsy if empty
-    - will automatically increase storage capacity when needed
-    - neither indexable nor sliceable by design
+        - O(1) pops
+        - O(1) amortized pushes
+        - O(1) length determination
+        - in a Boolean context, truthy if not empty, falsy if empty
+        - will automatically increase storage capacity when needed
+        - neither indexable nor sliceable by design
 
     """
 
@@ -36,8 +39,11 @@ class FIFOQueue[D]:
 
     def __init__(self, *dss: Iterable[D]) -> None:
         """
-        :param dss: Takes 1 or 0 iterables, initializes items in natural FIFO order.
-        :raises ValueError: If more than 1 iterable is given.
+        :param dss: Takes 0 or 1 iterable parameters. Populates
+                    queue from the iterable in FIFO order.
+        :raises TypeError: When passed a non-iterable parameter.
+        :raises ValueError: When more than one parameter is given.
+
         """
         if (size := len(dss)) > 1:
             msg = f'FIFOQueue expects at most 1 iterable argument, got {size}'
@@ -45,6 +51,12 @@ class FIFOQueue[D]:
         self._ca = CA(dss[0]) if size == 1 else CA()
 
     def __bool__(self) -> bool:
+        """
+        .. admonition:: Truthiness
+
+            ``FIFOQueue`` truthy when non-empty, falsy when empty.
+
+        """
         return len(self._ca) > 0
 
     def __len__(self) -> int:
@@ -56,6 +68,14 @@ class FIFOQueue[D]:
         return self._ca == other._ca
 
     def __iter__(self) -> Iterator[D]:
+        """
+        .. admonition:: Iteration
+
+            Iterate over current state in natural FIFO order.
+
+        :returns: An iterator of the data.
+
+        """
         return iter(list(self._ca))
 
     def __repr__(self) -> str:
@@ -67,41 +87,64 @@ class FIFOQueue[D]:
         return '<< ' + ' < '.join(map(str, self)) + ' <<'
 
     def copy(self) -> 'FIFOQueue[D]':
-        """Shallow copy.
+        """
+        .. admonition:: Shallow copy
+
+            Make a shallow copy of the ``FIFOQueue``.
+
+        :returns: Shallow copy of the ``FIFOQueue``.
 
-        :returns: Shallow copy of the FIFOQueue.
         """
         return FIFOQueue(self._ca)
 
     def push(self, *ds: D) -> None:
-        """Push items onto FIFOQueue.
+        """
+        .. admonition:: Push
+
+            Push data items onto ``FIFOQueue``.
+
+        :param ds: Items to be pushed onto ''FIFOQueue''.
 
-        :param ds: Items to be pushed onto FIFOQueue.
         """
         self._ca.pushr(*ds)
 
     def pop(self) -> MayBe[D]:
-        """Pop oldest data item off of FIFOQueue.
+        """
+        .. admonition:: Pop
+
+            Pop oldest data item off of ``FIFOQueue``.
+
+        :returns: ``MayBe`` of popped data item if ``FIFOQueue``
+                   was not empty, empty ``MayBe`` otherwise.
 
-        :returns: 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 item on queue.
+        """
+        .. admonition:: Peak last
+
+            Peak at newest item on ``FIFOQueue``.
+
+        :returns: ``MayBe`` of newest item on ``FIFOQueue``,
+                  empty ``MayBe`` if ``FIFOQueue`` empty.
 
-        :returns: MayBe of newest 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.
+        """
+        .. admonition:: Peak next out
+
+            Peak at oldest data item on ``FIFOQueue``.
+
+        :returns: ``MayBe`` of oldest item on ``FIFOQueue``,
+                  empty ``MayBe`` if ``FIFOueue`` empty.
 
-        :returns: MayBe of oldest item on queue, empty MayBe if queue empty.
         """
         if self._ca:
             return MayBe(self._ca[0])
@@ -113,11 +156,16 @@ class FIFOQueue[D]:
     def fold[T](self, f: Callable[[T, D], T], start: T) -> MayBe[T]: ...
 
     def fold[T](self, f: Callable[[T, D], T], start: T | None = None) -> MayBe[T]:
-        """Reduces FIFOQueue in natural FIFO Order, oldest to newest.
+        """
+        .. admonition:: Fold
+
+            Reduces ``FIFOQueue`` in natural FIFO Order, oldest to newest.
 
         :param f: Reducing function, first argument is for accumulator.
         :param start: Optional starting value.
-        :returns: MayBe of reduced value, empty MayBe if queue empty and no starting value given.
+        :returns: ``MayBe`` of reduced value, empty ``MayBe`` if ``FIFOQueue``
+                  empty and no starting value given.
+
         """
         if start is None:
             if not self._ca:
@@ -126,18 +174,27 @@ class FIFOQueue[D]:
         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.
+        """
+        .. admonition:: Map
+
+            Map ``f`` over the ``FIFOQueue``, retain original order.
+
+        :param f: Function to map over ``FIFOQueue``.
+        :returns: New ``FIFOQueue`` instance.
 
-        :param f: Function to map over queue.
-        :returns: New FIFOQueue instance.
         """
         return FIFOQueue(map(f, self._ca))
 
 
 def fifo_queue[D](*ds: D) -> FIFOQueue[D]:
-    """FIFOQueue factory function.
+    """
+    .. admonition:: Create FIFOQueue
+
+        Factory function to create an ``FIFOQueue``
+        instance from the function's arguments.
+
+    :param ds: Initial data to be pushed on in FIFO order.
+    :returns: New ``FIFOQueue`` instance.
 
-    :param ds: Initial items pushed on in FIFO order.
-    :returns: FIFOQueue with initialized items from ``ds``.
     """
     return FIFOQueue(ds)

pythonic_fp/queues/fifo.pyi

@@ -0,0 +1,24 @@
+from collections.abc import Callable, Iterable, Iterator
+from pythonic_fp.fptools.maybe import MayBe
+from typing import overload
+
+__all__ = ['FIFOQueue', 'fifo_queue']
+
+class FIFOQueue[D]:
+    def __init__(self, *dss: Iterable[D]) -> None: ...
+    def __bool__(self) -> bool: ...
+    def __len__(self) -> int: ...
+    def __eq__(self, other: object) -> bool: ...
+    def __iter__(self) -> Iterator[D]: ...
+    def copy(self) -> FIFOQueue[D]: ...
+    def push(self, *ds: D) -> None: ...
+    def pop(self) -> MayBe[D]: ...
+    def peak_last_in(self) -> MayBe[D]: ...
+    def peak_next_out(self) -> MayBe[D]: ...
+    @overload
+    def fold[T](self, f: Callable[[D, D], D]) -> MayBe[D]: ...
+    @overload
+    def fold[T](self, f: Callable[[T, D], T], start: T) -> MayBe[T]: ...
+    def map[U](self, f: Callable[[D], U]) -> FIFOQueue[U]: ...
+
+def fifo_queue[D](*ds: D) -> FIFOQueue[D]: ...

pythonic_fp/queues/lifo.py

@@ -1,4 +1,4 @@
-# Copyright 2023-2024 Geoffrey R. Scheller
+# 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.
@@ -22,22 +22,28 @@ __all__ = ['LIFOQueue', 'lifo_queue']
 
 
 class LIFOQueue[D]:
-    """Stateful Last-In-First-Out (LIFO) Queue data structure.
+    """
+    .. admonition:: LIFOQueue
+
+        Stateful Last-In-First-Out (LIFO) Queue data structure.
 
-    - O(1) pops
-    - O(1) amortized pushes
-    - O(1) length determination
-    - 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) pops
+        - O(1) amortized pushes
+        - O(1) length determination
+        - in a Boolean context, true if not empty, false if empty
+        - will automatically increase storage capacity when needed
+        - neither indexable nor sliceable by design
 
     """
     __slots__ = ('_ca',)
 
     def __init__(self, *dss: Iterable[D]) -> None:
         """
-        :param dss: Takes 1 or 0 iterables, initializes data in natural LIFO order.
-        :raises ValueError: If more than 1 iterable is given.
+        :param dss: Takes 0 or 1 iterable parameters. Populates
+                    queue from the iterable in LIFO order.
+        :raises TypeError: When passed a non-iterable parameter.
+        :raises ValueError: When more than one parameter is given.
+
         """
         if (size := len(dss)) > 1:
             msg = f'LIFOQueue expects at most 1 iterable argument, got {size}'
@@ -45,6 +51,12 @@ class LIFOQueue[D]:
         self._ca = CA(dss[0]) if size == 1 else CA()
 
     def __bool__(self) -> bool:
+        """
+        .. admonition:: Truthiness
+
+            ``LIFOQueue`` truthy when non-empty, falsy when empty.
+
+        """
         return len(self._ca) > 0
 
     def __len__(self) -> int:
@@ -56,6 +68,14 @@ class LIFOQueue[D]:
         return self._ca == other._ca
 
     def __iter__(self) -> Iterator[D]:
+        """
+        .. admonition:: Iteration
+
+            Iterate over current state in natural LIFO order.
+
+        :returns: Iterator of the data.
+
+        """
         return reversed(list(self._ca))
 
     def __repr__(self) -> str:
@@ -67,32 +87,46 @@ class LIFOQueue[D]:
         return '|| ' + ' > '.join(map(str, self)) + ' ><'
 
     def copy(self) -> 'LIFOQueue[D]':
-        """Shallow copy.
+        """
+        .. admonition:: Shallow copy
+
+            Make a shallow copy of the ``LIFOQueue``.
+
+        :returns: Shallow copy of the ``LIFOQueue``.
 
-        :returns: Shallow copy of the LIFOQueue.
         """
         return LIFOQueue(reversed(self._ca))
 
     def push(self, *ds: D) -> None:
         """Push items onto LIFOQueue.
 
-        :param ds: Items to be pushed onto LIFOQueue.
+        :param ds: Items to be pushed onto ``LIFOQueue``.
+
         """
         self._ca.pushr(*ds)
 
     def pop(self) -> MayBe[D]:
-        """Pop newest data item off of LIFOQueue.
+        """
+        .. admonition:: Pop
+
+            Pop newest data item off of ``LIFOQueue``.
+
+        :returns: ``MayBe`` of popped data item if ``LIFOQueue``
+                  was not empty, empty `MayBe` otherwise.
 
-        :returns: MayBe of popped 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 item on queue.
+        """
+        .. admonition:: Peak last
+
+            Peak at newest item on ``LIFOQueue``.
+
+        :returns: ``MayBe`` of newest item on queue, empty ``MayBe`` if queue empty.
 
-        :returns: MayBe of newest item on queue, empty MayBe if queue empty.
         """
         if self._ca:
             return MayBe(self._ca[-1])
@@ -104,11 +138,16 @@ class LIFOQueue[D]:
     def fold[T](self, f: Callable[[T, D], T], start: T) -> MayBe[T]: ...
 
     def fold[T](self, f: Callable[[T, D], T], start: T | None = None) -> MayBe[T]:
-        """Reduces LIFOQUEUE in natural LIFO Order, newest to oldest.
+        """
+        .. admonition:: Fold
+
+            Reduces ``LIFOQUEUE`` in natural LIFO Order, newest to oldest.
 
         :param f: Reducing function, first argument is for accumulator.
         :param start: Optional starting value.
-        :returns: MayBe of reduced value, empty MayBe if queue empty and no starting value given.
+        :returns: ``MayBe`` of reduced value, empty ``MayBe`` if ``LIFOQueue``
+                  empty and no starting value given.
+
         """
         if start is None:
             if not self._ca:
@@ -117,18 +156,27 @@ class LIFOQueue[D]:
         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.
+        """
+        .. admonition:: Map
+
+            Map ``f`` over the ``LIFOQueue``, retain original order.
+
+        :param f: Function to map over ``LIFOQueue``.
+        :returns: New ``LIFOQueue`` instance.
 
-        :param f: Function to map over queue.
-        :returns: New LIFOQueue instance.
         """
         return LIFOQueue(reversed(CA(map(f, reversed(self._ca)))))
 
 
 def lifo_queue[D](*ds: D) -> LIFOQueue[D]:
-    """LIFOQueue factory function.
+    """
+    .. admonition:: Create LIFOQueue
+
+        Factory function to create an ``LIFOQUEUE``
+        instance from the function's arguments.
+
+    :param ds: Items pushed onto queue in LIFO order.
+    :returns: New ``LIFOQueue`` instance.
 
-    :param ds: Initial items pushed on in LIFO order.
-    :returns: LIFOQueue with initialized items from ``ds``.
     """
     return LIFOQueue(ds)

pythonic_fp/queues/lifo.pyi

@@ -0,0 +1,23 @@
+from collections.abc import Callable, Iterable, Iterator
+from pythonic_fp.fptools.maybe import MayBe
+from typing import overload
+
+__all__ = ['LIFOQueue', 'lifo_queue']
+
+class LIFOQueue[D]:
+    def __init__(self, *dss: Iterable[D]) -> None: ...
+    def __bool__(self) -> bool: ...
+    def __len__(self) -> int: ...
+    def __eq__(self, other: object) -> bool: ...
+    def __iter__(self) -> Iterator[D]: ...
+    def copy(self) -> LIFOQueue[D]: ...
+    def push(self, *ds: D) -> None: ...
+    def pop(self) -> MayBe[D]: ...
+    def peak(self) -> MayBe[D]: ...
+    @overload
+    def fold[T](self, f: Callable[[D, D], D]) -> MayBe[D]: ...
+    @overload
+    def fold[T](self, f: Callable[[T, D], T], start: T) -> MayBe[T]: ...
+    def map[U](self, f: Callable[[D], U]) -> LIFOQueue[U]: ...
+
+def lifo_queue[D](*ds: D) -> LIFOQueue[D]: ...

{pythonic_fp_queues-5.1.0.dist-info → pythonic_fp_queues-5.1.2.dist-info}/METADATA

@@ -1,25 +1,25 @@
 Metadata-Version: 2.4
 Name: pythonic-fp-queues
-Version: 5.1.0
+Version: 5.1.2
 Summary: Queues
 Keywords: queue,fifo,lifo,dqueue
 Author-email: "Geoffrey R. Scheller" <geoffrey@scheller.com>
-Requires-Python: >=3.12
+Requires-Python: >=3.13
 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: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
 License-File: LICENSE
-Requires-Dist: pythonic-fp-circulararray>=6.0.0
-Requires-Dist: pythonic-fp-fptools>=5.1.2
+Requires-Dist: pythonic-fp-circulararray>=6.0.4
+Requires-Dist: pythonic-fp-fptools>=5.2.0
 Requires-Dist: pytest>=8.4.1 ; extra == "test"
 Project-URL: Changelog, https://github.com/grscheller/pythonic-fp-queues/blob/main/CHANGELOG.rst
-Project-URL: Documentation, https://grscheller.github.io/pythonic-fp/queues/development/build/html/index.html
-Project-URL: Homepage, https://github.com/grscheller/pythonic-fp/blob/main/README.md
+Project-URL: Documentation, https://grscheller.github.io/pythonic-fp/projects/queues.html
+Project-URL: Homepage, https://grscheller.github.io/pythonic-fp/
 Project-URL: Source, https://github.com/grscheller/pythonic-fp-queues
 Provides-Extra: test
 
@@ -27,8 +27,8 @@ Pythonic FP - Queues
 ====================
 
 PyPI project
-`pythonic-fp.queues
-<https://pypi.org/project/pythonic-fp.queues>`_.
+`pythonic-fp-queues
+<https://pypi.org/project/pythonic-fp-queues>`_.
 
 +-------------------------+-----------+--------------------------+
 | module                  | class     | name                     |
@@ -42,19 +42,23 @@ PyPI project
 
 Part of the
 `pythonic-fp
-<https://grscheller.github.io/pythonic-fp/homepage/build/html/index.html>`_
+<https://grscheller.github.io/pythonic-fp/>`_
 PyPI projects.
 
 Documentation
 -------------
 
+Documentation and other links for this project are hosted on
+`GitHub Pages
+<https://grscheller.github.io/pythonic-fp/projects/queues.html>`_.
+
 Documentation for this project is hosted on
 `GitHub Pages
-<https://grscheller.github.io/pythonic-fp/queues/development/build/html>`_.
+<https://grscheller.github.io/pythonic-fp-queues/development/html/>`_.
 
 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_queues-5.1.2.dist-info/RECORD

@@ -0,0 +1,13 @@
+pythonic_fp/queues/__init__.py,sha256=NOkkXOQaHmiemvY4Ke5ZdFJCl3_P3bmV87Xz5Y-R9cU,1028
+pythonic_fp/queues/__init__.pyi,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pythonic_fp/queues/de.py,sha256=hRFeogJ4XuXRFV4xOpD3mLoNo1jklP4uT5Ilrw-PiJg,7456
+pythonic_fp/queues/de.pyi,sha256=db74UiSLFme25Yhc28Hhw3EKb2GfvU4wNBJtkTlr_e4,1150
+pythonic_fp/queues/fifo.py,sha256=EvZub5bRsW3xqCbREKz8dXIt3heBmzsDOzJQuF6Mm30,5728
+pythonic_fp/queues/fifo.pyi,sha256=19TGU3Qg91hCLo5A-5p9vmREcl38EUWhIAvJZtlb1eA,885
+pythonic_fp/queues/lifo.py,sha256=_uBM9XnZMm-OYEDhAHPdcHBy_C6h2d0B0dTpoXaJ62A,5348
+pythonic_fp/queues/lifo.pyi,sha256=HdJ-t7R2w3VfCT06raCTXespdUZfpBgMepBlcxDvyuk,832
+pythonic_fp/queues/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pythonic_fp_queues-5.1.2.dist-info/licenses/LICENSE,sha256=IJMkVWQUVy-SonK6SMaMotDQ6Zb-lVi2bUTiGp1GUO8,10774
+pythonic_fp_queues-5.1.2.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+pythonic_fp_queues-5.1.2.dist-info/METADATA,sha256=fzVKSB2LG3S9c78klIzZ6zvaH1JT4mfRa6NZzZiD7d0,2350
+pythonic_fp_queues-5.1.2.dist-info/RECORD,,

pythonic_fp_queues-5.1.0.dist-info/RECORD

@@ -1,9 +0,0 @@
-pythonic_fp/queues/__init__.py,sha256=BagRl3n3W-lxxPigkGNFMDFNs8surchki-YNXczrPto,1352
-pythonic_fp/queues/de.py,sha256=qHDFe1djYGcDMn1THApsYtAd_iZDnJyrMJK0gHkD2vA,6072
-pythonic_fp/queues/fifo.py,sha256=V7kAxqnBBBgheBHbaCo1tyORHJqeVR-HMzWiDdAulbU,4593
-pythonic_fp/queues/lifo.py,sha256=HAlSz4eKlVatLXkL6uux_gZXjFwiA4X_btDTAF6PM10,4406
-pythonic_fp/queues/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pythonic_fp_queues-5.1.0.dist-info/licenses/LICENSE,sha256=IJMkVWQUVy-SonK6SMaMotDQ6Zb-lVi2bUTiGp1GUO8,10774
-pythonic_fp_queues-5.1.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
-pythonic_fp_queues-5.1.0.dist-info/METADATA,sha256=6AAV5vX106ojMsJtRQXGxZHz7ROKCZsghKcpYcuzASo,2282
-pythonic_fp_queues-5.1.0.dist-info/RECORD,,