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

pythonic_fp/circulararray/auto.py

@@ -16,44 +16,46 @@
 Variable Storage Capacity
 =========================
 
-Circular array with variable storage capacity.
+**Circular array with variable storage capacity.**
 
-- O(1) pops either end 
-- O(1) amortized pushes either end 
+- O(1) pops either end
+- O(1) amortized pushes either end
 - O(1) indexing, fully supports slicing
 - auto-resizing more storage capacity when necessary, manually compatible
-- 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 empty, otherwise truthy
-- factory function ca produces a variable storage capacity circular array from its arguments
+- function ``ca`` produces auto-resizing circular array from arguments
 
 """
+
 from collections.abc import Callable, Iterable, Iterator
-from typing import cast, overload
+from typing import cast, Final, overload
+from pythonic_fp.gadgets.sentinels.novalue import NoValue
 
 __all__ = ['CA', 'ca']
 
+nada: Final[NoValue] = NoValue()
 
-class CA[I]():
 
+class CA[I]:
     __slots__ = '_items', '_cnt', '_cap', '_front', '_rear'
 
-    def __init__(
-            self,
-            items: Iterable[I] | None = None
-        ) -> 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
-        :raises TypeError: if items is not Iterable
+    @overload
+    def __init__(self) -> None: ...
+    @overload
+    def __init__(self, items: Iterable[I]) -> None: ...
 
+    def __init__(self, items: Iterable[I | NoValue] | NoValue = nada) -> None:
+        """
+        :param items: "Optional" iterable to initial populate circular array.
+        :raises TypeError: When ``items`` not Iterable.
         """
-        if items is None:
-            self._items: list[I | None] = [None, None]
+        if items is nada:
+            self._items: list[I | NoValue] = [nada, nada]
         else:
-            self._items = [None] + list(items) + [None]
+            values: list[I | NoValue] = list(cast(Iterable[I | NoValue], items))
+            self._items = [nada] + values + [nada]
         self._cap = cap = len(self._items)
         self._cnt = cap - 2
         if cap == 2:
@@ -66,88 +68,93 @@ class CA[I]():
     def _double_storage_capacity(self) -> None:
         if self._front <= self._rear:
             (
-                    self._items,
-                    self._cap,
+                self._items,
+                self._cap,
             ) = (
-                    self._items + [None] * self._cap,
-                    self._cap * 2,
-                )
+                self._items + [nada] * self._cap,
+                self._cap * 2,
+            )
         else:
             (
-                    self._items,
-                    self._front,
-                    self._cap,
+                self._items,
+                self._front,
+                self._cap,
             ) = (
-                    self._items[: self._front] + [None]*self._cap + self._items[self._front:],
-                    self._front + self._cap,
-                    2*self._cap,
-                )
+                self._items[: self._front]
+                + [nada] * self._cap
+                + self._items[self._front :],
+                self._front + self._cap,
+                2 * self._cap,
+            )
 
     def _compact_storage_capacity(self) -> None:
         match self._cnt:
             case 0:
                 (
-                        self._cap,
-                        self._front,
-                        self._rear,
-                        self._items,
+                    self._cap,
+                    self._front,
+                    self._rear,
+                    self._items,
                 ) = (
-                        2,
-                        0,
-                        1,
-                        [None, None],
-                    )
+                    2,
+                    0,
+                    1,
+                    [nada, nada],
+                )
             case 1:
                 (
+                    self._cap,
+                    self._front,
+                    self._rear,
+                    self._items,
+                ) = (
+                    3,
+                    1,
+                    1,
+                    [nada, self._items[self._front], nada],
+                )
+            case _:
+                if self._front <= self._rear:
+                    (
                         self._cap,
                         self._front,
                         self._rear,
                         self._items,
-                ) = (
-                        3,
-                        1,
+                    ) = (
+                        self._cnt + 2,
                         1,
-                        [None, self._items[self._front], None],
+                        self._cnt,
+                        [nada] + self._items[self._front : self._rear + 1] + [nada],
                     )
-            case _:
-                if self._front <= self._rear:
-                    ( 
-                            self._cap,
-                            self._front,
-                            self._rear,
-                            self._items,
-                    ) = (
-                            self._cnt + 2,
-                            1,
-                            self._cnt,
-                            [None] + self._items[self._front : self._rear + 1] + [None],
-                        )
                 else:
                     (
-                            self._cap,
-                            self._front,
-                            self._rear,
-                            self._items,
+                        self._cap,
+                        self._front,
+                        self._rear,
+                        self._items,
                     ) = (
-                            self._cnt + 2,
-                            1,
-                            self._cnt,
-                            [None] + self._items[self._front :] + self._items[: self._rear + 1] + [None],
-                        )
+                        self._cnt + 2,
+                        1,
+                        self._cnt,
+                        [nada]
+                        + self._items[self._front :]
+                        + self._items[: self._rear + 1]
+                        + [nada],
+                    )
 
     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])
@@ -157,16 +164,16 @@ class CA[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])
@@ -188,9 +195,9 @@ class CA[I]():
     @overload
     def __getitem__(self, idx: int) -> I: ...
     @overload
-    def __getitem__(self, idx: slice) -> "CA[I]": ...
+    def __getitem__(self, idx: slice) -> 'CA[I]': ...
 
-    def __getitem__(self, idx: int | slice) -> I | "CA[I]":
+    def __getitem__(self, idx: int | slice) -> I | 'CA[I]':
         if isinstance(idx, slice):
             return CA(list(self)[idx])
 
@@ -222,18 +229,18 @@ class CA[I]():
                 item_list[idx] = vals
                 _ca = CA(item_list)
                 (
-                        self._items,
-                        self._cnt,
-                        self._cap,
-                        self._front,
-                        self._rear,
+                    self._items,
+                    self._cnt,
+                    self._cap,
+                    self._front,
+                    self._rear,
                 ) = (
-                        _ca._items,
-                        _ca._cnt,
-                        _ca._cap,
-                        _ca._front,
-                        _ca._rear,
-                    )
+                    _ca._items,
+                    _ca._cnt,
+                    _ca._cap,
+                    _ca._front,
+                    _ca._rear,
+                )
                 return
 
             msg = 'must assign iterable to extended slice'
@@ -263,18 +270,18 @@ class CA[I]():
         del item_list[idx]
         _ca = CA(item_list)
         (
-                self._items,
-                self._cnt,
-                self._cap,
-                self._front,
-                self._rear,
+            self._items,
+            self._cnt,
+            self._cap,
+            self._front,
+            self._rear,
         ) = (
-                _ca._items,
-                _ca._cnt,
-                _ca._cap,
-                _ca._front,
-                _ca._rear,
-            )
+            _ca._items,
+            _ca._cnt,
+            _ca._cap,
+            _ca._front,
+            _ca._rear,
+        )
         del _ca
 
     def __eq__(self, other: object) -> bool:
@@ -284,157 +291,153 @@ class CA[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, *items: I) -> None:
-        """
-        Push items onto left side (front) of circular array.
-
-        :param items: items pushed onto circular array from left
+        """Push ``items`` on from left.
 
+        :param items: Items pushed onto circular array from left (front).
         """
         for item in items:
             if self._cnt == self._cap:
                 self._double_storage_capacity()
             (
-                    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, *items: I) -> None:
-        """
-        Push items onto right side (rear) of circular array.
-
-        :param items: items pushed onto circular array from right
+        """Push ``items`` on from right.
 
+        :param items: Items pushed onto circular array from right (rear).
         """
         for item in items:
             if self._cnt == self._cap:
                 self._double_storage_capacity()
             (
-                    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 CA'
             raise ValueError(msg)
         return cast(I, d)
 
     def popr(self) -> I:
-        """
-        Pop item off right side (rear) of circular array.
-
-        :return: item popped from right side of circular array
-        :raises ValueError: when called on an empty circular array
+        """Pop single item off from right.
 
+        :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 CA'
             raise ValueError(msg)
         return cast(I, d)
 
     def popld(self, default: I) -> I:
-        """
-        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
-        :return: item popped from left side or default item if empty
+        """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.
         """
         try:
             return self.popl()
@@ -442,13 +445,11 @@ class CA[I]():
             return default
 
     def poprd(self, default: I) -> I:
-        """
-        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
-        :return: item popped from right side or default item if empty
+        """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.
         """
         try:
             return self.popr()
@@ -456,12 +457,10 @@ class CA[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
-        :return: 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] = []
 
@@ -476,12 +475,10 @@ class CA[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
-        :return: 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:
@@ -494,11 +491,9 @@ class CA[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
@@ -506,142 +501,135 @@ class CA[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]) -> "CA[U]":
-        """
-        Apply function f over the circular array's contents,
-
-        :param f: callable from type I to type U
-        :returns: new circular array instance
+    def map[U](self, f: Callable[[I], U]) -> 'CA[U]':
+        """Apply function ``f`` over the circular array's contents.
 
+        :param f: Callable from type ``I`` to type ``U``.
+        :returns: New auto-resizing circular array instance.
         """
         return CA(map(f, self))
 
-    def foldl[L](self, f: Callable[[L, I], L], start: L | None = None) -> L:
-        """
-        Fold left with a function and optional starting 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 = NoValue()) -> L:
+        """Fold left with a function and optional starting 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 CA 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 CA 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 current storage capacity of the circular array.
-
-        :returns: current storage capacity
+        """Return current storage capacity of the circular array.
 
+        :returns: Current storage capacity.
         """
         return self._cap
 
     def empty(self) -> None:
-        """
-        Empty the circular array, keep current storage capacity."""
+        """Empty the circular array, keep current storage capacity."""
         (
-                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 resize(self, minimum_capacity: int = 2) -> None:
-        """
-        Compact circular array and, if necessary, resize to a minimum
+        """Compact circular array and, if necessary, resize to a minimum
         storage capacity. To just compact the circular array, do not
         provide ``minimum_capacity``.
 
-        :param minimum_capacity: minimum storage capacity to compact the circular array
-
+        :param minimum_capacity: Minimum storage capacity to compact the circular array.
         """
         self._compact_storage_capacity()
         if (min_cap := minimum_capacity) > self._cap:
             (
-                    self._cap,
-                    self._items,
+                self._cap,
+                self._items,
             ) = (
-                    min_cap,
-                    self._items + [None] * (min_cap - self._cap),
-                )
+                min_cap,
+                self._items + [nada] * (min_cap - self._cap),
+            )
             if self._cnt == 0:
                 self._front, self._rear = 0, self._cap - 1
 
 
 def ca[T](*items: T) -> CA[T]:
-    """
-    Produce circular array from a variable number of arguments.
-
-    :param items: initial items for a new circular array
-    :returns: new variable storage capacity circular array
+    """Produce circular array from a variable number of arguments.
 
+    :param items: Initial items for a new auto-resizing circular array.
+    :returns: New variable storage capacity circular array.
     """
     return CA(items)