pythonic-fp-queues 5.1.1__py3-none-any.whl → 5.1.3__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.
@@ -16,21 +16,13 @@
 Queues
 ------
 
-.. admonition:: Stateful Queues based on a circular array.
+.. admonition:: Stateful Queues
 
-    Geared to specific algorithms by limiting what can be done with the
-    queues. Sometimes the power of a data structure is not what it
-    empowers you to do, but what it prevents you from doing to yourself.
+    By limiting how their data can be accessed, each queue type
+    supports different algorithmic use cases.
 
-+-------------------------+-----------+--------------------------+
-| 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       |
-+-------------------------+-----------+--------------------------+
+    Sometimes the power of a data structure comes not what it empowers
+    you to do, but what it prevents you from doing to yourself.
 
 """
 

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,84 +21,164 @@ __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
 
     """
 
     __slots__ = ('_ca',)
 
-    def __init__(self, *dss: Iterable[D]) -> None:
+    def __init__(self, *ds: 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.
+        .. admonition:: Initializer
+
+            Initialize ``DEQueue`` with 0 or 1 iterables to populate
+            the queue left (front) to right (rear).
+
+        :param ds: Takes 0 or 1 iterable parameters.
+        :raises ValueError: When more than one parameter is provided.
+        :raises TypeError: When passed a non-iterable parameter.
 
         """
-        if (size := len(dss)) > 1:
+        if (size := len(ds)) > 1:
             msg = f'DEQueue expects at most 1 argument, got {size}'
             raise ValueError(msg)
-        self._ca = CA(dss[0]) if size == 1 else CA()
+        self._ca = CA(ds[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:
+        """
+        .. admonition:: Get length
+
+            Return the number of data elements in the ``DEQueue``.
+
+        """
         return len(self._ca)
 
     def __eq__(self, other: object) -> bool:
+        """
+        .. admonition:: Equality comparison
+
+            If ``other`` is a ``DEQueue`` and the corresponding
+            elements of ``self`` and ``other`` compare as equal,
+            then return ``True``. Otherwise return ``False``.
+
+        :returns: ``self == other``
+
+        """
         if not isinstance(other, DEQueue):
             return False
         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:
+        """
+        .. admonition:: String representation
+
+            Construct string 'DEQueue(d₁, d₂, … dₙ)' where
+
+            - d₁, d₂, … dₙ are the contents displayed with ``repr()``
+
+        :returns: A string to reproduce the ``DEQueue``.
+
+        """
         if len(self) == 0:
             return 'DEQueue()'
         return 'DEQueue(' + ', '.join(map(repr, self._ca)) + ')'
 
     def __str__(self) -> str:
+        r"""
+        .. admonition:: User string
+
+            Construct string '>< d₁ | d₂ | … | dₙ ><' where
+
+            - d₁, d₂, ..., dₙ are the contents displayed with ``str()``
+
+        :returns: A string meaningful to an end user.
+
+        """
         return '>< ' + ' | '.join(map(str, self)) + ' ><'
 
     def copy(self) -> 'DEQueue[D]':
-        """Shallow copy.
+        """
+        .. admonition:: Copy
+
+            Shallow copy the ``DEQueue``.
 
-        :returns: Shallow copy of the DEQueue.
+        :returns: New ``DEQueue`` instance containing the same references.
 
         """
         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: Items to be pushed onto DEQueue from the left.
+        :param ds: Data 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: Items to be pushed onto DEQueue from the right.
+        :param ds: Data 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
 
-        :returns: MayBe of popped item if queue was not empty, empty MayBe otherwise.
+            Pop next item from left side ``DEQueue``, if it exists.
+
+        :returns: ``MayBe`` of popped item if queue was not empty,
+                  empty ``MayBe`` otherwise.
 
         """
         if self._ca:
@@ -106,9 +186,13 @@ class DEQueue[D]:
         return MayBe()
 
     def popr(self) -> MayBe[D]:
-        """Pop next item off right side DEQueue, if it exists.
+        """
+        .. admonition:: Pop right
 
-        :returns: MayBe of popped item if queue was not empty, empty MayBe otherwise.
+            Pop next item off right side ''DEQueue``, if it exists.
+
+        :returns: ``MayBe`` of popped item if queue was not empty,
+                  empty ``MayBe`` otherwise.
 
         """
         if self._ca:
@@ -116,9 +200,13 @@ class DEQueue[D]:
         return MayBe()
 
     def peakl(self) -> MayBe[D]:
-        """Peak left side of DEQueue. Does not consume item.
+        """
+        .. admonition:: Peak left
 
-        :returns: MayBe of leftmost item if queue not empty, empty MayBe otherwise.
+            Peak left side of ``DEQueue``. Does not consume item.
+
+        :returns: ``MayBe`` of leftmost item if queue not empty,
+                  empty ``MayBe`` otherwise.
 
         """
         if self._ca:
@@ -126,9 +214,13 @@ class DEQueue[D]:
         return MayBe()
 
     def peakr(self) -> MayBe[D]:
-        """Peak right side of DEQueue. Does not consume item.
+        """
+        .. admonition:: Peak right
 
-        :returns: MayBe of rightmost item if queue not empty, empty MayBe otherwise.
+            Peak right side of ``DEQueue``. Does not consume item.
+
+        :returns: ``MayBe`` of rightmost item if queue not empty,
+                  empty ``MayBe`` otherwise.
 
         """
         if self._ca:
@@ -141,11 +233,15 @@ 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:
@@ -160,11 +256,15 @@ 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:
@@ -174,24 +274,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
 
-        .. tip::
+            Map left to right.
 
-            Order map done does not matter if ``f`` is pure.
+            .. tip::
+
+                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 items as if pushed on from right to left.
-    :returns: DEQueue with items initialized in FIFO order.
+    :param ds: Initial data to be pushed on right to left.
+    :returns: A new ``DEQueue`` instance.
 
     """
     return DEQueue(ds)

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,72 +21,141 @@ __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
 
     """
 
     __slots__ = ('_ca',)
 
-    def __init__(self, *dss: Iterable[D]) -> None:
+    def __init__(self, *ds: 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.
+        .. admonition:: Initializer
+
+            Initialize ``FIFOQueue`` with 0 or 1 iterables to populate
+            the queue in natural FIFO order.
+
+        :param ds: Takes 0 or 1 iterable parameters.
+        :raises ValueError: When more than one parameter is provided.
+        :raises TypeError: When passed a non-iterable parameter.
 
         """
-        if (size := len(dss)) > 1:
+        if (size := len(ds)) > 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()
+        self._ca = CA(ds[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:
+        """
+        .. admonition:: Get length
+
+            Return the number of data elements in the ``FIFOQueue``.
+
+        """
         return len(self._ca)
 
     def __eq__(self, other: object) -> bool:
+        """
+        .. admonition:: Equality comparison
+
+            If ``other`` is a ``FIFOQueue`` and the corresponding
+            elements of ``self`` and ``other`` compare as equal,
+            then return ``True``. Otherwise return ``False``.
+
+        :returns: ``self == other``
+
+        """
         if not isinstance(other, FIFOQueue):
             return False
         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:
+        """
+        .. admonition:: String representation
+
+            Construct string 'FIFOQueue(d₁, d₂, … dₙ)' where
+
+            - d₁, d₂, … dₙ are the contents displayed with ``repr()``
+
+        :returns: A string to reproduce the ``FIFOQueue``.
+
+        """
         if len(self) == 0:
            return 'FIFOQueue()'
         return 'FIFOQueue(' + ', '.join(map(repr, self._ca)) + ')'
 
     def __str__(self) -> str:
+        """
+        .. admonition:: User string
+
+            Construct string '<< d₁ < d₂ < … < dₙ <<' where
+
+            - d₁, d₂, ..., dₙ are the contents displayed with ``str()``
+
+        :returns: A string meaningful to an end user.
+
+        """
         return '<< ' + ' < '.join(map(str, self)) + ' <<'
 
     def copy(self) -> 'FIFOQueue[D]':
-        """Shallow copy.
+        """
+        .. admonition:: Copy
 
-        :returns: Shallow copy of the FIFOQueue.
+            Shallow copy the ``FIFOQueue``.
+
+        :returns: New ``FIFOQueue`` instance containing the same references.
 
         """
         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 queue was not empty, empty MayBe otherwise.
+        :returns: ``MayBe`` of popped data item if ``FIFOQueue``
+                   was not empty, empty ``MayBe`` otherwise.
 
         """
         if self._ca:
@@ -94,9 +163,13 @@ class FIFOQueue[D]:
         return MayBe()
 
     def peak_last_in(self) -> MayBe[D]:
-        """Peak at newest item on queue.
+        """
+        .. admonition:: Peak last
 
-        :returns: MayBe of newest item on queue, empty MayBe if queue empty.
+            Peak at newest item on ``FIFOQueue``.
+
+        :returns: ``MayBe`` of newest item on ``FIFOQueue``,
+                  empty ``MayBe`` if ``FIFOQueue`` empty.
 
         """
         if self._ca:
@@ -104,9 +177,13 @@ class FIFOQueue[D]:
         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 queue, empty MayBe if queue empty.
+        :returns: ``MayBe`` of oldest item on ``FIFOQueue``,
+                  empty ``MayBe`` if ``FIFOueue`` empty.
 
         """
         if self._ca:
@@ -119,11 +196,15 @@ 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 with ``f``, empty ``MayBe``
+                  if ``FIFOQueue`` empty and no starting value given.
 
         """
         if start is None:
@@ -133,20 +214,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
 
-        :param f: Function to map over queue.
-        :returns: New FIFOQueue instance.
+            Map ``f`` over the ``FIFOQueue``, retain original order.
+
+        :param f: Function to map over ``FIFOQueue``.
+        :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 items pushed on in FIFO order.
-    :returns: FIFOQueue with initialized items from ``ds``.
+    :param ds: Initial data to be pushed on in FIFO order.
+    :returns: New ``FIFOQueue`` instance.
 
     """
     return FIFOQueue(ds)

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,71 +22,140 @@ __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:
+    def __init__(self, *ds: 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.
+        .. admonition:: Initializer
+
+            Initialize ``LIFOQueue`` with 0 or 1 iterables to populate
+            the queue in natural LIFO order.
+
+        :param ds: Takes 0 or 1 iterable parameters.
+        :raises ValueError: When more than one parameter is provided.
+        :raises TypeError: When passed a non-iterable parameter.
 
         """
-        if (size := len(dss)) > 1:
+        if (size := len(ds)) > 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()
+        self._ca = CA(ds[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:
+        """
+        .. admonition:: Get length
+
+            Return the number of data elements in the ``LIFOQueue``.
+
+        """
         return len(self._ca)
 
     def __eq__(self, other: object) -> bool:
+        """
+        .. admonition:: Equality comparison
+
+            If ``other`` is a ``LIFOQueue`` and the corresponding
+            elements of ``self`` and ``other`` compare as equal,
+            then return ``True``. Otherwise return ``False``.
+
+        :returns: ``self == other``
+
+        """
         if not isinstance(other, LIFOQueue):
             return False
         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:
+        """
+        .. admonition:: String representation
+
+            Construct string 'LIFOQueue(d₁, d₂, … dₙ)' where
+
+            - d₁, d₂, … dₙ are the contents displayed with ``repr()``
+
+        :returns: A string to reproduce the ``LIFOQueue``.
+
+        """
         if len(self) == 0:
             return 'LIFOQueue()'
         return 'LIFOQueue(' + ', '.join(map(repr, self._ca)) + ')'
 
     def __str__(self) -> str:
+        r"""
+        .. admonition:: User string
+
+            Construct string '|| d₁ > d₂ > … > dₙ ><' where
+
+            - d₁, d₂, ..., dₙ are the contents displayed with ``str()``
+
+        :returns: A string meaningful to an end user.
+
+        """
         return '|| ' + ' > '.join(map(str, self)) + ' ><'
 
     def copy(self) -> 'LIFOQueue[D]':
-        """Shallow copy.
+        """
+        .. admonition:: Copy
+
+            Shallow copy the ``LIFOQueue``.
 
-        :returns: Shallow copy of the LIFOQueue.
+        :returns: New ``LIFOQueue`` instance containing the same references.
 
         """
         return LIFOQueue(reversed(self._ca))
 
     def push(self, *ds: D) -> None:
-        """Push items onto LIFOQueue.
+        """
+        .. admonition:: Push
 
-        :param ds: Items to be pushed onto LIFOQueue.
+            Push items 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 item if queue was not empty, empty MayBe otherwise.
+        :returns: ``MayBe`` of popped data item if ``LIFOQueue``
+                  was not empty, empty `MayBe` otherwise.
 
         """
         if self._ca:
@@ -94,9 +163,12 @@ class LIFOQueue[D]:
         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:
@@ -109,11 +181,15 @@ 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 with ``f``, empty ``MayBe``
+                  if ``LIFOQueue`` empty and no starting value given.
 
         """
         if start is None:
@@ -123,20 +199,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 queue.
-        :returns: New LIFOQueue instance.
+        :param f: Function to map over ``LIFOQueue``.
+        :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: Initial items pushed on in LIFO order.
-    :returns: LIFOQueue with initialized items from ``ds``.
+    :param ds: Items pushed onto queue in LIFO order.
+    :returns: New ``LIFOQueue`` instance.
 
     """
     return LIFOQueue(ds)

{pythonic_fp_queues-5.1.1.dist-info → pythonic_fp_queues-5.1.3.dist-info}/METADATA

@@ -1,25 +1,26 @@
 Metadata-Version: 2.4
 Name: pythonic-fp-queues
-Version: 5.1.1
+Version: 5.1.3
 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.1
+Requires-Dist: pythonic-fp-circulararray>=6.0.4
 Requires-Dist: pythonic-fp-fptools>=5.2.0
+Requires-Dist: pythonic-fp-gadgets>=4.1.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/
-Project-URL: Homepage, https://grscheller.github.io/pythonic-fp/homepage/build/html/
+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 +28,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 +43,23 @@ PyPI project
 
 Part of the
 `pythonic-fp
-<https://grscheller.github.io/pythonic-fp>`_
+<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>`_.
+<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.3.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=ICPHkGz0JKIk8aLk75ZUSPS6T9jSTynkJ-2A5Sy_iig,8532
+pythonic_fp/queues/de.pyi,sha256=db74UiSLFme25Yhc28Hhw3EKb2GfvU4wNBJtkTlr_e4,1150
+pythonic_fp/queues/fifo.py,sha256=qQhv57VuF2QuaRtGJhCtj5qtGPjoGKlQS9RbZIGsvmY,6803
+pythonic_fp/queues/fifo.pyi,sha256=19TGU3Qg91hCLo5A-5p9vmREcl38EUWhIAvJZtlb1eA,885
+pythonic_fp/queues/lifo.py,sha256=lQAzoCOzQrw3gF2A_GgF_4XkYpNivswPyZS-Qp5bxYw,6471
+pythonic_fp/queues/lifo.pyi,sha256=HdJ-t7R2w3VfCT06raCTXespdUZfpBgMepBlcxDvyuk,832
+pythonic_fp/queues/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pythonic_fp_queues-5.1.3.dist-info/licenses/LICENSE,sha256=IJMkVWQUVy-SonK6SMaMotDQ6Zb-lVi2bUTiGp1GUO8,10774
+pythonic_fp_queues-5.1.3.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+pythonic_fp_queues-5.1.3.dist-info/METADATA,sha256=CeQO0Dt1zxfeu94F7ziEET_hegfeZUjlpzzoIzzdQr4,2392
+pythonic_fp_queues-5.1.3.dist-info/RECORD,,

pythonic_fp_queues-5.1.1.dist-info/RECORD

@@ -1,13 +0,0 @@
-pythonic_fp/queues/__init__.py,sha256=MDXOn4_zIir0vvzaDpodmSCHN1usLSIqebEpFI9TPhQ,1625
-pythonic_fp/queues/__init__.pyi,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pythonic_fp/queues/de.py,sha256=EApnwnvGmOrzvbx0MEhspp_wlDtqMuJlJKPRip1b4hY,6084
-pythonic_fp/queues/de.pyi,sha256=db74UiSLFme25Yhc28Hhw3EKb2GfvU4wNBJtkTlr_e4,1150
-pythonic_fp/queues/fifo.py,sha256=aj34iqFfh4YTHKG9_QEZpSvnUdzkng-IeCjZQxOuWQ8,4602
-pythonic_fp/queues/fifo.pyi,sha256=19TGU3Qg91hCLo5A-5p9vmREcl38EUWhIAvJZtlb1eA,885
-pythonic_fp/queues/lifo.py,sha256=gvrZKgUbBVNA1I03Q1AGh8rLBOzmnpI2herrjCTzR7A,4414
-pythonic_fp/queues/lifo.pyi,sha256=HdJ-t7R2w3VfCT06raCTXespdUZfpBgMepBlcxDvyuk,832
-pythonic_fp/queues/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pythonic_fp_queues-5.1.1.dist-info/licenses/LICENSE,sha256=IJMkVWQUVy-SonK6SMaMotDQ6Zb-lVi2bUTiGp1GUO8,10774
-pythonic_fp_queues-5.1.1.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
-pythonic_fp_queues-5.1.1.dist-info/METADATA,sha256=ODc-wRv37wtjI64ZGS8nAHus6xgh4KQCzQgeuzOVWrY,2218
-pythonic_fp_queues-5.1.1.dist-info/RECORD,,