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

pythonic_fp/circulararray/auto.py

@@ -18,38 +18,44 @@ 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:
+    @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.
+        :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:
@@ -62,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])
@@ -153,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])
@@ -184,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])
 
@@ -218,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'
@@ -259,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:
@@ -280,28 +291,34 @@ 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
 
@@ -314,14 +331,14 @@ class CA[I]():
             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`` on from right.
@@ -332,14 +349,14 @@ class CA[I]():
             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 single item off from left side.
@@ -349,30 +366,30 @@ class CA[I]():
         """
         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)
@@ -386,30 +403,30 @@ class CA[I]():
         """
         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)
@@ -493,7 +510,7 @@ class CA[I]():
         for _ in range(n, 0, -1):
             self.pushl(self.popr())
 
-    def map[U](self, f: Callable[[I], U]) -> "CA[U]":
+    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``.
@@ -501,52 +518,62 @@ class CA[I]():
         """
         return CA(map(f, self))
 
-    def foldl[L](self, f: Callable[[L, I], L], start: L | None = None) -> L:
+    @overload
+    def foldl[L](self, f: Callable[[I, I], I]) -> I: ...
+    @overload
+    def foldl[L](self, f: Callable[[L, I], L], start: L) -> L: ...
+
+    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.
+        :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:
+    @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 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.
+        :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
@@ -561,16 +588,16 @@ class CA[I]():
     def empty(self) -> None:
         """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.
@@ -589,12 +616,12 @@ class CA[I]():
         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
 

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

@@ -18,44 +18,53 @@ 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:
         """
-        :param items: Optional iterable to initial populate circular array.
-        :param capacity: Fixed storage capacity of circular array.
+        :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:
@@ -68,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])
@@ -87,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])
@@ -152,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:
@@ -171,28 +180,34 @@ 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
 
@@ -207,14 +222,14 @@ class CAF[I]():
             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 ``item`` on from Right.
@@ -227,14 +242,14 @@ class CAF[I]():
             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 single item off from left side.
@@ -244,30 +259,30 @@ class CAF[I]():
         """
         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)
@@ -281,30 +296,30 @@ class CAF[I]():
         """
         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)
@@ -388,7 +403,7 @@ class CAF[I]():
         for _ in range(n, 0, -1):
             self.pushl(self.popr())
 
-    def map[U](self, f: Callable[[I], U]) -> "CAF[U]":
+    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``.
@@ -396,7 +411,12 @@ class CAF[I]():
         """
         return CAF(map(f, self), self._cap)
 
-    def foldl[L](self, f: Callable[[L, I], L], start: L | None = None) -> L:
+    @overload
+    def foldl[L](self, f: Callable[[I, I], I]) -> I: ...
+    @overload
+    def foldl[L](self, f: Callable[[L, I], L], start: L) -> L: ...
+
+    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.
@@ -405,23 +425,28 @@ class CAF[I]():
         :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:
+    @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 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.
@@ -430,18 +455,18 @@ class CAF[I]():
         :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
@@ -456,16 +481,16 @@ class CAF[I]():
     def empty(self) -> None:
         """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.
@@ -482,4 +507,4 @@ def caf[T](*items: T, capacity: int = 2) -> CAF[T]:
     :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)

pythonic_fp/circulararray/fixed.pyi

@@ -1,9 +1,15 @@
 from collections.abc import Callable, Iterable, Iterator
+from typing import overload
 
 __all__ = ['CAF', 'caf']
 
 class CAF[I]:
-    def __init__(self, items: Iterable[I] | None = None, capacity: int = 2) -> None: ...
+    @overload
+    def __init__(self) -> None: ...
+    @overload
+    def __init__(self, items: Iterable[I]) -> None: ...
+    @overload
+    def __init__(self, items: Iterable[I], capacity: int) -> None: ...
     def __iter__(self) -> Iterator[I]: ...
     def __reversed__(self) -> Iterator[I]: ...
     def __bool__(self) -> bool: ...
@@ -23,8 +29,14 @@ class CAF[I]:
     def rotl(self, n: int = 1) -> None: ...
     def rotr(self, n: int = 1) -> None: ...
     def map[U](self, f: Callable[[I], U]) -> CAF[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-5.3.3.dist-info → pythonic_fp_circulararray-5.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythonic-fp-circulararray
-Version: 5.3.3
+Version: 5.4.0
 Summary: Circular Array
 Keywords: auto resizing,circular array,circulararray,dequeue,indexable,pop,push
 Author-email: "Geoffrey R. Scheller" <geoffrey@scheller.com>
@@ -14,6 +14,7 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Typing :: Typed
 License-File: LICENSE
+Requires-Dist: pythonic-fp-gadgets>=3.1.0
 Requires-Dist: pytest>=8.4.1 ; extra == "test"
 Project-URL: Changelog, https://github.com/grscheller/pythonic-fp-circulararray/blob/main/CHANGELOG.rst
 Project-URL: Documentation, https://grscheller.github.io/pythonic-fp/circulararray/development/build/html/index.html
@@ -30,17 +31,31 @@ PyPI project
 
 Python module implementing stateful circular array data structures.
 
-- O(1) pops either end 
-- O(1) amortized pushes either end 
-- O(1) indexing, fully supports slicing
-- Auto-resizing larger when necessary, manually compatible
-- iterable, can safely mutate while iterators continue iterating over previous state
-- comparisons compare identity before equality, like builtins
-- in boolean context returns true when not empty, false when empty
-
-This PyPI project is part of of the grscheller
-`pythonic-fp namespace projects
-<https://github.com/grscheller/pythonic-fp/blob/main/README.md>`_
+- variable storage capacity circular array
+
+  - 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, safely mutates while iterators iterating over previous state
+  - comparisons compare identity before equality, like builtins
+  - in boolean context, falsy when empty, otherwise truthy
+  - function ``ca`` produces auto-resizing circular array from arguments
+
+- fixed storage capacity circular array
+
+  - O(1) pops and pushes either end 
+  - O(1) indexing, does not support slicing
+  - fixed total storage capacity
+  - 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
+  - function ``caf`` produces fixed capacity circular array from arguments
+
+Part of the
+`pythonic-fp
+<https://grscheller.github.io/pythonic-fp/homepage/build/html/index.html>`_
+PyPI projects.
 
 Documentation
 -------------

pythonic_fp_circulararray-5.4.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+pythonic_fp/circulararray/__init__.py,sha256=uR0KASmw1Zraz9l3VPbqPm9WUKzWk-0_tUGT0opabzQ,1515
+pythonic_fp/circulararray/__init__.pyi,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pythonic_fp/circulararray/auto.py,sha256=mM5kAZnSo4etgA0uSp05VUMGpIOeKXIoCCQ1C3pIETo,19457
+pythonic_fp/circulararray/auto.pyi,sha256=DegIbRFv66Ws4N1J1dExQ6cQJOTZw-XXUEJHi1OgIBk,1861
+pythonic_fp/circulararray/fixed.py,sha256=VhCWBcE0C8toYqGyd9aKJ1bSJu8sHA46AQGJ7mGxYBE,15700
+pythonic_fp/circulararray/fixed.pyi,sha256=Uk0QnXn3_q_6urXeRFEMxsL0gS-3Xa4UsyDRVXk8YoY,1648
+pythonic_fp/circulararray/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pythonic_fp_circulararray-5.4.0.dist-info/licenses/LICENSE,sha256=psuoW8kuDP96RQsdhzwOqi6fyWv0ct8CR6Jr7He_P_k,10173
+pythonic_fp_circulararray-5.4.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+pythonic_fp_circulararray-5.4.0.dist-info/METADATA,sha256=x6ZQX_ItPF3ndJZFS15JOOqKPK01yM6YEf0Y3e9PsK8,2761
+pythonic_fp_circulararray-5.4.0.dist-info/RECORD,,

pythonic_fp_circulararray-5.3.3.dist-info/RECORD

@@ -1,11 +0,0 @@
-pythonic_fp/circulararray/__init__.py,sha256=uR0KASmw1Zraz9l3VPbqPm9WUKzWk-0_tUGT0opabzQ,1515
-pythonic_fp/circulararray/__init__.pyi,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pythonic_fp/circulararray/auto.py,sha256=_rZhOsC3PGs97j15qM4vXpkpRDTfVkxEGwYyBi9uAQU,19334
-pythonic_fp/circulararray/auto.pyi,sha256=yfQ2kzIiXFb2Bpg3cMwHwv2oSlyOUMTgmdPZM_-oU_8,1669
-pythonic_fp/circulararray/fixed.py,sha256=nzwPnaVOh-KKv503_c--f_m0SkOaUI6mSe1Bo5WACCA,15316
-pythonic_fp/circulararray/fixed.pyi,sha256=y_7eMvH18B1lpLPp2P-VkN-xcQVKJn6cOisp9LSBBRk,1362
-pythonic_fp/circulararray/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pythonic_fp_circulararray-5.3.3.dist-info/licenses/LICENSE,sha256=psuoW8kuDP96RQsdhzwOqi6fyWv0ct8CR6Jr7He_P_k,10173
-pythonic_fp_circulararray-5.3.3.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
-pythonic_fp_circulararray-5.3.3.dist-info/METADATA,sha256=rdgGmosD6wF1Cfye7QBuZJXGnjs3uDgPzmYYvVpUx-M,2180
-pythonic_fp_circulararray-5.3.3.dist-info/RECORD,,