pythonic-fp-circulararray 5.3.2__py3-none-any.whl → 5.4.0__py3-none-any.whl

pythonic_fp/circulararray/auto.pyi

@@ -4,7 +4,10 @@ from typing import overload
 __all__ = ['CA', 'ca']
 
 class CA[I]:
-    def __init__(self, items: Iterable[I] | None = None) -> None: ...
+    @overload
+    def __init__(self) -> None: ...
+    @overload
+    def __init__(self, items: Iterable[I]) -> None: ...
     def __iter__(self) -> Iterator[I]: ...
     def __reversed__(self) -> Iterator[I]: ...
     def __bool__(self) -> bool: ...
@@ -33,8 +36,14 @@ class CA[I]:
     def rotl(self, n: int = 1) -> None: ...
     def rotr(self, n: int = 1) -> None: ...
     def map[U](self, f: Callable[[I], U]) -> CA[U]: ...
-    def foldl[L](self, f: Callable[[L, I], L], start: L | None = None) -> L: ...
-    def foldr[R](self, f: Callable[[I, R], R], start: R | None = None) -> R: ...
+    @overload
+    def foldl[L](self, f: Callable[[I, I], I]) -> I: ...
+    @overload
+    def foldl[L](self, f: Callable[[L, I], L], start: L) -> L: ...
+    @overload
+    def foldr[R](self, f: Callable[[I, I], I]) -> I: ...
+    @overload
+    def foldr[R](self, f: Callable[[I, R], R], start: R) -> R: ...
     def capacity(self) -> int: ...
     def empty(self) -> None: ...
     def fraction_filled(self) -> float: ...

pythonic_fp/circulararray/fixed.py

@@ -16,50 +16,55 @@
 Fixed Storage Capacity
 ======================
 
-Circular array with fixed storage capacity.
+**Circular array with fixed storage capacity.**
 
-- O(1) pops and pushes either end 
+- O(1) pops and pushes either end
 - O(1) indexing, does not support slicing
 - fixed total storage capacity
-- iterable, can safely mutate while iterators continue iterating over previous state
+- iterable, safely mutates while iterators iterating over previous state
 - comparisons compare identity before equality, like builtins
 - in boolean context, falsy when either empty or full, otherwise truthy
-- factory function caf produces a fixed storage capacity circular array from its arguments
+- function ``caf`` produces fixed capacity circular array from arguments
 
 """
+
 from collections.abc import Callable, Iterable, Iterator
-from typing import cast, Final
+from typing import cast, Final, overload
+from pythonic_fp.gadgets.sentinels.novalue import NoValue
 
 __all__ = ['CAF', 'caf']
 
+nada: Final[NoValue] = NoValue()
 
-class CAF[I]():
 
+class CAF[I]:
     __slots__ = '_items', '_cnt', '_cap', '_front', '_rear'
 
+    @overload
+    def __init__(self) -> None: ...
+    @overload
+    def __init__(self, items: Iterable[I]) -> None: ...
+    @overload
+    def __init__(self, items: Iterable[I], capacity: int) -> None: ...
+
     def __init__(
-            self,
-            items: Iterable[I] | None = None,
-            capacity: int = 2
-        ) -> None:
+        self, items: Iterable[I | NoValue] | NoValue = nada, capacity: int = 2
+    ) -> None:
         """
-        Basically a list that can be grown from both ends
-        in O(1) time and space complexity.
-
-        :param items: optional iterable to initial populate circular array
-        :param capacity: fixed storage capacity of circular array
-        :raises TypeError: if items is not Iterable
-
+        :param items: "Optional" iterable to initial populate circular array.
+        :param capacity: Minimum fixed storage capacity of circular array.
+        :raises TypeError: When ``items`` not Iterable,
         """
         capacity = max(2, capacity)
-        if items is None:
-            self._items: list[I | None] = [None]*capacity
+        if items is nada:
+            self._items: list[I | NoValue] = [nada] * capacity
             count = 0
         else:
-            dlist: list[I | None] = list(items)
+            values: list[I | NoValue] = list(cast(Iterable[I | NoValue], items))
+            dlist: list[I | NoValue] = list(values)
             count = len(dlist)
             capacity = max(count, capacity)
-            self._items = dlist + [None]*(capacity - count)
+            self._items = dlist + [nada] * (capacity - count)
         self._cap: Final[int] = capacity
         self._cnt = count
         if count == 0:
@@ -72,16 +77,16 @@ class CAF[I]():
     def __iter__(self) -> Iterator[I]:
         if self._cnt > 0:
             (
-                    capacity,
-                    rear,
-                    position,
-                    current_state,
+                capacity,
+                rear,
+                position,
+                current_state,
             ) = (
-                    self._cap,
-                    self._rear,
-                    self._front,
-                    self._items.copy(),
-                )
+                self._cap,
+                self._rear,
+                self._front,
+                self._items.copy(),
+            )
 
             while position != rear:
                 yield cast(I, current_state[position])
@@ -91,16 +96,16 @@ class CAF[I]():
     def __reversed__(self) -> Iterator[I]:
         if self._cnt > 0:
             (
-                    capacity,
-                    front,
-                    position,
-                    current_state,
+                capacity,
+                front,
+                position,
+                current_state,
             ) = (
-                    self._cap,
-                    self._front,
-                    self._rear,
-                    self._items.copy(),
-                )
+                self._cap,
+                self._front,
+                self._rear,
+                self._items.copy(),
+            )
 
             while position != front:
                 yield cast(I, current_state[position])
@@ -156,16 +161,16 @@ class CAF[I]():
         del item_list[idx]
         _ca = CAF(item_list, self._cap)
         (
-                self._items,
-                self._cnt,
-                self._front,
-                self._rear,
+            self._items,
+            self._cnt,
+            self._front,
+            self._rear,
         ) = (
-                _ca._items,
-                _ca._cnt,
-                _ca._front,
-                _ca._rear,
-            )
+            _ca._items,
+            _ca._cnt,
+            _ca._front,
+            _ca._rear,
+        )
         del _ca
 
     def __eq__(self, other: object) -> bool:
@@ -175,161 +180,157 @@ class CAF[I]():
             return False
 
         (
-                front1,
-                count1,
-                capacity1,
-                front2,
-                count2,
-                capacity2,
+            front1,
+            count1,
+            capacity1,
+            front2,
+            count2,
+            capacity2,
         ) = (
-                self._front,
-                self._cnt,
-                self._cap,
-                other._front,
-                other._cnt,
-                other._cap,
-            )
+            self._front,
+            self._cnt,
+            self._cap,
+            other._front,
+            other._cnt,
+            other._cap,
+        )
 
         if count1 != count2:
             return False
 
         for nn in range(count1):
-            if self._items[(front1 + nn) % capacity1] is other._items[(front2 + nn) % capacity2]:
+            if (
+                self._items[(front1 + nn) % capacity1]
+                is other._items[(front2 + nn) % capacity2]
+            ):
                 continue
-            if self._items[(front1 + nn) % capacity1] != other._items[(front2 + nn) % capacity2]:
+            if (
+                self._items[(front1 + nn) % capacity1]
+                != other._items[(front2 + nn) % capacity2]
+            ):
                 return False
         return True
 
     def pushl(self, item: I) -> None:
-        """
-        Push single item onto left side (front) of circular array.
-
-        :param item: single item pushed onto circular array from left
-        :raises ValueError: when called on a full CAF
+        """Push ``item`` on from left.
 
+        :param item: Single item pushed onto circular array from left (front).
+        :raises ValueError: When called on a full ``CAF``.
         """
         if self._cnt == self._cap:
             msg = 'Method pushl called on a full CAF'
             raise ValueError(msg)
 
         (
-                self._front,
-                self._items[self._front],
-                self._cnt,
+            self._front,
+            self._items[self._front],
+            self._cnt,
         ) = (
-                (self._front - 1) % self._cap,
-                item,
-                self._cnt + 1,
-            )
+            (self._front - 1) % self._cap,
+            item,
+            self._cnt + 1,
+        )
 
     def pushr(self, item: I) -> None:
-        """
-        Push a single item onto right side (rear) of circular array.
-
-        :param item: single item pushed onto circular array from right
-        :raises ValueError: when called on a full fixed storage capacity circular array
+        """Push ``item`` on from Right.
 
+        :param item: Single ``item`` pushed onto circular array from right (rear).
+        :raises ValueError: When called on a full fixed storage capacity circular array.
         """
         if self._cnt == self._cap:
             msg = 'Method pushr called on a full CAF'
             raise ValueError(msg)
 
         (
-                self._rear,
-                self._items[self._rear],
-                self._cnt,
+            self._rear,
+            self._items[self._rear],
+            self._cnt,
         ) = (
-                (self._rear + 1) % self._cap,
-                item,
-                self._cnt + 1,
-            )
+            (self._rear + 1) % self._cap,
+            item,
+            self._cnt + 1,
+        )
 
     def popl(self) -> I:
-        """
-        Pop item off left side (front) of circular array.
-
-        :returns: item popped from left side of circular array
-        :raises ValueError: when called on an empty circular array
+        """Pop single item off from left side.
 
+        :returns: Item popped from left side (front) of circular array.
+        :raises ValueError: When called on an empty circular array.
         """
         if self._cnt > 1:
             (
-                    d,
-                    self._items[self._front],
-                    self._front,
-                    self._cnt,
+                d,
+                self._items[self._front],
+                self._front,
+                self._cnt,
             ) = (
-                    self._items[self._front],
-                    None,
-                    (self._front + 1) % self._cap,
-                    self._cnt - 1,
-                )
+                self._items[self._front],
+                nada,
+                (self._front + 1) % self._cap,
+                self._cnt - 1,
+            )
         elif self._cnt == 1:
             (
-                    d,
-                    self._items[self._front],
-                    self._cnt,
-                    self._front,
-                    self._rear,
+                d,
+                self._items[self._front],
+                self._cnt,
+                self._front,
+                self._rear,
             ) = (
-                    self._items[self._front],
-                    None,
-                    0,
-                    0,
-                    self._cap - 1,
-                )
+                self._items[self._front],
+                nada,
+                0,
+                0,
+                self._cap - 1,
+            )
         else:
             msg = 'Method popl called on an empty CAF'
             raise ValueError(msg)
         return cast(I, d)
 
     def popr(self) -> I:
-        """
-        Pop item off right side (rear) of circular array.
-
-        :returns: item popped from right side of circular array
-        :raises ValueError: when called on an empty circular array
+        """Pop single item off from right side.
 
+        :returns: Item popped from right side (rear) of circular array.
+        :raises ValueError: When called on an empty circular array.
         """
         if self._cnt > 1:
             (
-                    d,
-                    self._items[self._rear],
-                    self._rear,
-                    self._cnt,
+                d,
+                self._items[self._rear],
+                self._rear,
+                self._cnt,
             ) = (
-                    self._items[self._rear],
-                    None,
-                    (self._rear - 1) % self._cap,
-                    self._cnt - 1,
-                )
+                self._items[self._rear],
+                nada,
+                (self._rear - 1) % self._cap,
+                self._cnt - 1,
+            )
         elif self._cnt == 1:
             (
-                    d,
-                    self._items[self._front],
-                    self._cnt,
-                    self._front,
-                    self._rear,
+                d,
+                self._items[self._front],
+                self._cnt,
+                self._front,
+                self._rear,
             ) = (
-                    self._items[self._front],
-                    None,
-                    0,
-                    0,
-                    self._cap - 1,
-                )
+                self._items[self._front],
+                nada,
+                0,
+                0,
+                self._cap - 1,
+            )
         else:
             msg = 'Method popr called on an empty CAF'
             raise ValueError(msg)
         return cast(I, d)
 
     def popld(self, default: I) -> I:
-        """
-        Pop one item from left side of the circular array, provide
+        """Pop one item from left side of the circular array, provide
         a mandatory default value. "Safe" version of popl.
 
-        :param default: item returned if circular array is empty
-        :returns: item popped from left side or default item if empty
-
+        :param default: Item returned if circular array is empty.
+        :returns: Item popped from left side or default item if empty.
         """
         try:
             return self.popl()
@@ -337,13 +338,11 @@ class CAF[I]():
             return default
 
     def poprd(self, default: I) -> I:
-        """
-        Pop one item from right side of the circular array, provide
+        """Pop one item from right side of the circular array, provide
         a mandatory default value. "Safe" version of popr.
 
-        :param default: item returned if circular array is empty
-        :returns: item popped from right side or default item if empty
-
+        :param default: Item returned if circular array is empty.
+        :returns: Item popped from right side or default item if empty.
         """
         try:
             return self.popr()
@@ -351,12 +350,10 @@ class CAF[I]():
             return default
 
     def poplt(self, maximum: int) -> tuple[I, ...]:
-        """
-        Pop multiple items from left side of circular array.
-
-        :param maximum: maximum number of items to pop, may pop less if not enough items
-        :returns: items in the order popped, left to right
+        """Pop multiple items from left side of circular array.
 
+        :param maximum: Maximum number of items to pop, may pop less if not enough items.
+        :returns: Tuple of items in the order popped, left to right.
         """
         item_list: list[I] = []
 
@@ -371,12 +368,10 @@ class CAF[I]():
         return tuple(item_list)
 
     def poprt(self, maximum: int) -> tuple[I, ...]:
-        """
-        Pop multiple items from right side of circular array.
-
-        :param maximum: maximum number of items to pop, may pop less if not enough items
-        :returns: items in the order popped, right to left
+        """Pop multiple items from right side of circular array.
 
+        :param maximum: Maximum number of items to pop, may pop less if not enough items.
+        :returns: Tuple of items in the order popped, right to left.
         """
         item_list: list[I] = []
         while maximum > 0:
@@ -389,11 +384,9 @@ class CAF[I]():
         return tuple(item_list)
 
     def rotl(self, n: int = 1) -> None:
-        """
-        Rotate items to the left.
-
-        :param n: number of times to shift elements to the left
+        """Rotate items to the left.
 
+        :param n: Number of times to shift elements to the left.
         """
         if self._cnt < 2:
             return
@@ -401,122 +394,117 @@ class CAF[I]():
             self.pushr(self.popl())
 
     def rotr(self, n: int = 1) -> None:
-        """
-        Rotate items to the right.
-
-        :param n: number of times to shift elements to the right
+        """Rotate items to the right.
 
+        :param n: Number of times to shift elements to the right.
         """
         if self._cnt < 2:
             return
         for _ in range(n, 0, -1):
             self.pushl(self.popr())
 
-    def map[U](self, f: Callable[[I], U]) -> "CAF[U]":
-        """
-        Apply function ``f`` over the circular array's contents,
-
-        :param f: callable from type I to type U
-        :returns: new fixed circular array instance
+    def map[U](self, f: Callable[[I], U]) -> 'CAF[U]':
+        """Apply function ``f`` over the circular array's contents,
 
+        :param f: Callable from type ``I`` to type ``U``.
+        :returns: New fixed capacity circular array instance.
         """
         return CAF(map(f, self), self._cap)
 
-    def foldl[L](self, f: Callable[[L, I], L], start: L | None = None) -> L:
-        """
-        Fold left with a function and optional stating item.
+    @overload
+    def foldl[L](self, f: Callable[[I, I], I]) -> I: ...
+    @overload
+    def foldl[L](self, f: Callable[[L, I], L], start: L) -> L: ...
 
-        :param f: first argument to f is for the accumulator
-        :param start: optional starting item
-        :returns: reduced value produced by the left fold
-        :raises ValueError: when circular array empty and no starting item given
+    def foldl[L](self, f: Callable[[L, I], L], start: L | NoValue = nada) -> L:
+        """Fold left with a function and optional stating item.
 
+        :param f: Folding function, first argument to ``f`` is for the accumulator.
+        :param start: Optional starting item.
+        :returns: Reduced value produced by the left fold.
+        :raises ValueError: When circular array empty and no starting item given.
         """
         if self._cnt == 0:
-            if start is None:
+            if start is nada:
                 msg = 'Method foldl called on an empty CAF without a start item.'
                 raise ValueError(msg)
-            return start
+            return cast(L, start)
 
-        if start is None:
+        if start is nada:
             acc = cast(L, self[0])  # in this case D = L
             for idx in range(1, self._cnt):
                 acc = f(acc, self[idx])
             return acc
 
-        acc = start
+        acc = cast(L, start)
         for d in self:
             acc = f(acc, d)
         return acc
 
-    def foldr[R](self, f: Callable[[I, R], R], start: R | None = None) -> R:
-        """
-        Fold right with a function and an optional starting item.
+    @overload
+    def foldr[R](self, f: Callable[[I, I], I]) -> I: ...
+    @overload
+    def foldr[R](self, f: Callable[[I, R], R], start: R) -> R: ...
 
-        :param f: second argument to f is for the accumulator
-        :param start: optional starting item
-        :returns: reduced value produced by the right fold
-        :raises ValueError: when circular array empty and no starting item given
+    def foldr[R](self, f: Callable[[I, R], R], start: R | NoValue = nada) -> R:
+        """Fold right with a function and an optional starting item.
 
+        :param f: Folding function, second argument to ``f`` is for the accumulator.
+        :param start: Optional starting item.
+        :returns: Reduced value produced by the right fold.
+        :raises ValueError: When circular array empty and no starting item given.
         """
         if self._cnt == 0:
-            if start is None:
+            if start is nada:
                 msg = 'Method foldr called on empty CAF without initial value.'
                 raise ValueError(msg)
-            return start
+            return cast(R, start)
 
-        if start is None:
+        if start is nada:
             acc = cast(R, self[-1])  # in this case D = R
             for idx in range(self._cnt - 2, -1, -1):
                 acc = f(self[idx], acc)
             return acc
 
-        acc = start
+        acc = cast(R, start)
         for d in reversed(self):
             acc = f(d, acc)
         return acc
 
     def capacity(self) -> int:
-        """
-        Return fixed storage capacity of the circular array.
-
-        :returns: fixed storage capacity
+        """Return fixed storage capacity of the circular array.
 
+        :returns: Fixed storage capacity.
         """
         return self._cap
 
     def empty(self) -> None:
-        """
-        Empty the circular array."""
+        """Empty the circular array."""
         (
-                self._items,
-                self._front,
-                self._rear,
-                self._cnt,
+            self._items,
+            self._front,
+            self._rear,
+            self._cnt,
         ) = (
-                [None] * self._cap,
-                0,
-                self._cap - 1,
-                0,
-            )
+            [nada] * self._cap,
+            0,
+            self._cap - 1,
+            0,
+        )
 
     def fraction_filled(self) -> float:
-        """
-        Find fraction of the storage capacity which is filled.
-
-        :returns: the ratio count/capacity
+        """Find fraction of the storage capacity which is filled.
 
+        :returns: The ratio count/capacity.
         """
         return self._cnt / self._cap
 
 
 def caf[T](*items: T, capacity: int = 2) -> CAF[T]:
-    """
-    Produce a circular array from a variable number of arguments.
-
-    :param items: initial items for a new circular array
-    :param capacity: the minimum storage capacity to set
-    :returns: new fixed storage capacity circular array
+    """Produce a circular array from a variable number of arguments.
 
+    :param items: Initial items for a new fixed capacity :circular array.
+    :param capacity: The minimum storage capacity to set.
+    :returns: New fixed storage capacity circular array.
     """
-    return CAF(items, capacity = capacity)
+    return CAF(items, capacity=capacity)