dtools.circular-array 3.9.1__py3-none-any.whl → 3.11.0__py3-none-any.whl

dtools/circular_array/__init__.py

@@ -12,17 +12,23 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""### Circular Array
+"""### Developer Tools - circular array data structure
 
-Package for an indexable, sliceable circular array data structure.
+Package for an indexable, sliceable, auto-resizing circular array
+data structure with amortized O(1) pushes and pops either end.
 
-#### Modules
+#### Circular Array Data Structure
 
-* module dtools.circular_array.ca: circular array data structure
+* *module* dtools.circular_array.ca
+  * circular array data structure
+* *class* dtools.circular_array.ca.CA
+  * initializer takes 1 or 0 iterables
+* *function* dtools.circular_array.ca.ca
+  * factory function taking a variable number of arguments
 
 """
-__version__ = "3.9.1"
-__author__ = "Geoffrey R. Scheller"
-__copyright__ = "Copyright (c) 2023-2025 Geoffrey R. Scheller"
-__license__ = "Apache License 2.0"
 
+__version__ = '3.11.0'
+__author__ = 'Geoffrey R. Scheller'
+__copyright__ = 'Copyright (c) 2023-2025 Geoffrey R. Scheller'
+__license__ = 'Apache License 2.0'

dtools/circular_array/ca.py

@@ -12,43 +12,47 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""### Indexable circular array data structure module."""
+"""### Module for an indexable circular array data structure."""
+
 from __future__ import annotations
 from collections.abc import Callable, Iterable, Iterator, Sequence
-from typing import Any, cast, Never, overload, TypeVar
+from typing import cast, Never, overload, TypeVar
 
-__all__ = [ 'ca', 'CA' ]
+__all__ = ['CA', 'ca']
 
-D = TypeVar('D')
-L = TypeVar('L')
-R = TypeVar('R')
-U = TypeVar('U')
+D = TypeVar('D')  # type: ignore[unused-ignore]  # Needed only for pdoc
+L = TypeVar('L')  # type: ignore[unused-ignore]  # documentation generation.
+R = TypeVar('R')  # type: ignore[unused-ignore]  # Otherwise, not needed
+U = TypeVar('U')  # type: ignore[unused-ignore]  # by either MyPy or Python.
 
-class ca[D](Sequence[D]):
-    """
-    #### Indexable circular array data structure
-
-    * generic, stateful data structure
-    * amortized O(1) pushing and popping from either end
-    * O(1) random access any element
-    * will resize itself as needed
-    * sliceable
-    * makes defensive copies of contents for the purposes of iteration
-    * in boolean context returns true if not empty, false if empty
-    * in comparisons compare identity before equality (like Python built-ins do)
-    * lowercase class name choosen to match built-ins like `list` and `tuple`
-    * raises `IndexError` for out-of-bounds indexing
-    * raises `ValueError` for popping from or folding an empty `ca`
-    * raises `TypeError` if 2 or more arguments are passed to constructor
+
+class CA[D](Sequence[D]):
+    """Indexable circular array data structure
+
+    - generic, stateful data structure
+    - lowercase class name chosen to match nomenclature for builtins
+      - like `list` and `tuple`
+    - amortized O(1) pushing and popping from either end
+    - O(1) random access any element
+    - will resize itself as needed
+    - sliceable
+    - makes defensive copies of contents for the purposes of iteration
+    - in boolean context returns true if not empty, false if empty
+    - in comparisons compare identity before equality (like builtins)
+    - raises `IndexError` for out-of-bounds indexing
+    - raises `ValueError` for popping from or folding an empty `ca`
 
     """
+
     __slots__ = '_data', '_cnt', '_cap', '_front', '_rear'
 
     def __init__(self, *dss: Iterable[D]) -> None:
         if len(dss) < 2:
-            self._data: list[D|None] = [None] + cast(list[D|None], list(*dss)) + [None]
+            self._data: list[D | None] = (
+                [None] + cast(list[D | None], list(*dss)) + [None]
+            )
         else:
-            msg = f'ca expected at most 1 argument, got {len(dss)}'
+            msg = f'CA expected at most 1 argument, got {len(dss)}'
             raise TypeError(msg)
         self._cap = cap = len(self._data)
         self._cnt = cap - 2
@@ -61,33 +65,55 @@ class ca[D](Sequence[D]):
 
     def _double_storage_capacity(self) -> None:
         if self._front <= self._rear:
-            self._data += [None]*self._cap
+            self._data += [None] * self._cap
             self._cap *= 2
         else:
-            self._data = self._data[:self._front] + [None]*self._cap + self._data[self._front:]
-            self._front, self._cap = self._front + self._cap, 2*self._cap
+            self._data = (
+                self._data[: self._front]
+                + [None] * self._cap
+                + self._data[self._front :]
+            )
+            self._front, self._cap = self._front + self._cap, 2 * self._cap
 
     def _compact_storage_capacity(self) -> None:
-        """Compact the ca."""
+        """Compact the CA."""
         match self._cnt:
             case 0:
-                self._cap, self._front, self._rear, self._data = \
-                    2, 0, 1, [None, None]
+                self._cap, self._front, self._rear, self._data = 2, 0, 1, [None, None]
             case 1:
-                self._cap, self._front, self._rear, self._data = \
-                    3, 1, 1, [None, self._data[self._front], None]
+                self._cap, self._front, self._rear, self._data = (
+                    3,
+                    1,
+                    1,
+                    [None, self._data[self._front], None],
+                )
             case _:
                 if self._front <= self._rear:
-                    self._cap, self._front, self._rear, self._data = \
-                        self._cnt+2, 1, self._cnt, [None] + self._data[self._front:self._rear+1] + [None]
+                    self._cap, self._front, self._rear, self._data = (
+                        self._cnt + 2,
+                        1,
+                        self._cnt,
+                        [None] + self._data[self._front : self._rear + 1] + [None],
+                    )
                 else:
-                    self._cap, self._front, self._rear, self._data = \
-                        self._cnt+2, 1, self._cnt, [None] + self._data[self._front:] + self._data[:self._rear+1] + [None]
+                    self._cap, self._front, self._rear, self._data = (
+                        self._cnt + 2,
+                        1,
+                        self._cnt,
+                        [None]
+                        + self._data[self._front :]
+                        + self._data[: self._rear + 1]
+                        + [None],
+                    )
 
     def __iter__(self) -> Iterator[D]:
         if self._cnt > 0:
-            capacity, rear, position, current_state = \
-                self._cap, self._rear, self._front, self._data.copy()
+            capacity, rear, position, current_state = (
+                self._cap,
+                self._rear,
+                self._front,
+                self._data.copy(),
+            )
 
             while position != rear:
                 yield cast(D, current_state[position])
@@ -96,8 +122,12 @@ class ca[D](Sequence[D]):
 
     def __reversed__(self) -> Iterator[D]:
         if self._cnt > 0:
-            capacity, front, position, current_state = \
-                self._cap, self._front, self._rear, self._data.copy()
+            capacity, front, position, current_state = (
+                self._cap,
+                self._front,
+                self._rear,
+                self._data.copy(),
+            )
 
             while position != front:
                 yield cast(D, current_state[position])
@@ -105,7 +135,7 @@ class ca[D](Sequence[D]):
             yield cast(D, current_state[position])
 
     def __repr__(self) -> str:
-        return 'CA(' + ', '.join(map(repr, self)) + ')'
+        return 'ca(' + ', '.join(map(repr, self)) + ')'
 
     def __str__(self) -> str:
         return '(|' + ', '.join(map(str, self)) + '|)'
@@ -119,48 +149,50 @@ class ca[D](Sequence[D]):
     @overload
     def __getitem__(self, idx: int, /) -> D: ...
     @overload
-    def __getitem__(self, idx: slice, /) -> ca[D]: ...
+    def __getitem__(self, idx: slice, /) -> CA[D]: ...
 
-    def __getitem__(self, idx: int|slice, /) -> D|ca[D]:
+    def __getitem__(self, idx: int | slice, /) -> D | CA[D]:
         if isinstance(idx, slice):
-            return ca(list(self)[idx])
+            return CA(list(self)[idx])
 
         cnt = self._cnt
         if 0 <= idx < cnt:
             return cast(D, self._data[(self._front + idx) % self._cap])
-        elif -cnt <= idx < 0:
+
+        if -cnt <= idx < 0:
             return cast(D, self._data[(self._front + cnt + idx) % self._cap])
-        else:
-            if cnt > 0:
-                foo = [1, 2, 3]
-                foo.__setitem__
-                msg1 = 'Out of bounds: '
-                msg2 = f'index = {idx} not between {-cnt} and {cnt-1} '
-                msg3 = 'while getting value from a ca.'
-                raise IndexError(msg1 + msg2 + msg3)
-            else:
-                msg0 = 'Trying to get a value from an empty ca.'
-                raise IndexError(msg0)
+
+        if cnt == 0:
+            msg0 = 'Trying to get a value from an empty CA.'
+            raise IndexError(msg0)
+
+        msg1 = 'Out of bounds: '
+        msg2 = f'index = {idx} not between {-cnt} and {cnt - 1} '
+        msg3 = 'while getting value from a CA.'
+        raise IndexError(msg1 + msg2 + msg3)
 
     @overload
     def __setitem__(self, idx: int, vals: D, /) -> None: ...
     @overload
     def __setitem__(self, idx: slice, vals: Iterable[D], /) -> None: ...
 
-    def __setitem__(self, idx: int|slice, vals: D|Iterable[D], /) -> None:
+    def __setitem__(self, idx: int | slice, vals: D | Iterable[D], /) -> None:
         if isinstance(idx, slice):
             if isinstance(vals, Iterable):
                 data = list(self)
                 data[idx] = vals
-                _ca = ca(data)
-                self._data, self._cnt, self._cap, self._front, self._rear = \
-                            _ca._data, _ca._cnt, _ca._cap, _ca._front, _ca._rear
+                _ca = CA(data)
+                self._data, self._cnt, self._cap, self._front, self._rear = (
+                    _ca._data,
+                    _ca._cnt,
+                    _ca._cap,
+                    _ca._front,
+                    _ca._rear,
+                )
                 return
-            else:
-                msg = 'must assign iterable to extended slice'
-                foo = [1,2,3]
-                foo.__delitem__(2)
-                raise TypeError(msg)
+
+            msg = 'must assign iterable to extended slice'
+            raise TypeError(msg)
 
         cnt = self._cnt
         if 0 <= idx < cnt:
@@ -168,27 +200,31 @@ class ca[D](Sequence[D]):
         elif -cnt <= idx < 0:
             self._data[(self._front + cnt + idx) % self._cap] = cast(D, vals)
         else:
-            if cnt > 0:
-                msg1 = 'Out of bounds: '
-                msg2 = f'index = {idx} not between {-cnt} and {cnt-1} '
-                msg3 = 'while setting value from a ca.'
-                raise IndexError(msg1 + msg2 + msg3)
-            else:
-                msg0 = 'Trying to set a value from an empty ca.'
+            if cnt < 1:
+                msg0 = 'Trying to set a value from an empty CA.'
                 raise IndexError(msg0)
 
+            msg1 = 'Out of bounds: '
+            msg2 = f'index = {idx} not between {-cnt} and {cnt - 1} '
+            msg3 = 'while setting value from a CA.'
+            raise IndexError(msg1 + msg2 + msg3)
+
     @overload
     def __delitem__(self, idx: int) -> None: ...
     @overload
     def __delitem__(self, idx: slice) -> None: ...
 
-    def __delitem__(self, idx: int|slice) -> None:
+    def __delitem__(self, idx: int | slice) -> None:
         data = list(self)
         del data[idx]
-        _ca = ca(data)
-        self._data, self._cnt, self._cap, self._front, self._rear = \
-                    _ca._data, _ca._cnt, _ca._cap, _ca._front, _ca._rear
-        return
+        _ca = CA(data)
+        self._data, self._cnt, self._cap, self._front, self._rear = (
+            _ca._data,
+            _ca._cnt,
+            _ca._cap,
+            _ca._front,
+            _ca._rear,
+        )
 
     def __eq__(self, other: object, /) -> bool:
         if self is other:
@@ -196,125 +232,157 @@ class ca[D](Sequence[D]):
         if not isinstance(other, type(self)):
             return False
 
-        frontL, frontR, \
-        countL, countR, \
-        capacityL, capacityR = \
-            self._front, other._front, \
-            self._cnt, other._cnt, \
-            self._cap, other._cap
+        front1, front2, count1, count2, capacity1, capacity2 = (
+            self._front,
+            other._front,
+            self._cnt,
+            other._cnt,
+            self._cap,
+            other._cap,
+        )
 
-        if countL != countR:
+        if count1 != count2:
             return False
 
-        for nn in range(countL):
-            if self._data[(frontL+nn)%capacityL] is other._data[(frontR+nn)%capacityR]:
+        for nn in range(count1):
+            if (
+                self._data[(front1 + nn) % capacity1]
+                is other._data[(front2 + nn) % capacity2]
+            ):
                 continue
-            if self._data[(frontL+nn)%capacityL] != other._data[(frontR+nn)%capacityR]:
+            if (
+                self._data[(front1 + nn) % capacity1]
+                != other._data[(front2 + nn) % capacity2]
+            ):
                 return False
         return True
 
-    def pushL(self, *ds: D) -> None:
-        """Push data from the left onto the ca."""
+    def pushl(self, *ds: D) -> None:
+        """Push data from the left onto the CA."""
         for d in ds:
             if self._cnt == self._cap:
                 self._double_storage_capacity()
             self._front = (self._front - 1) % self._cap
             self._data[self._front], self._cnt = d, self._cnt + 1
 
-    def pushR(self, *ds: D) -> None:
-        """Push data from the right onto the ca."""
+    def pushr(self, *ds: D) -> None:
+        """Push data from the right onto the CA."""
         for d in ds:
             if self._cnt == self._cap:
                 self._double_storage_capacity()
             self._rear = (self._rear + 1) % self._cap
             self._data[self._rear], self._cnt = d, self._cnt + 1
 
-    def popL(self) -> D|Never:
-        """Pop one value off the left side of the ca.
+    def popl(self) -> D | Never:
+        """Pop one value off the left side of the CA.
+
+        Raises `ValueError` when called on an empty CA.
 
-        * raises `ValueError` when called on an empty ca
         """
         if self._cnt > 1:
-            d, self._data[self._front], self._front, self._cnt = \
-                self._data[self._front], None, (self._front+1) % self._cap, self._cnt - 1
-        elif self._cnt < 1:
-            msg = 'Method popL called on an empty ca'
-            raise ValueError(msg)
+            d, self._data[self._front], self._front, self._cnt = (
+                self._data[self._front],
+                None,
+                (self._front + 1) % self._cap,
+                self._cnt - 1,
+            )
+        elif self._cnt == 1:
+            d, self._data[self._front], self._cnt, self._front, self._rear = (
+                self._data[self._front],
+                None,
+                0,
+                0,
+                self._cap - 1,
+            )
         else:
-            d, self._data[self._front], self._cnt, self._front, self._rear = \
-                self._data[self._front], None, 0, 0, self._cap - 1
+            msg = 'Method popl called on an empty CA'
+            raise ValueError(msg)
         return cast(D, d)
 
-    def popR(self) -> D|Never:
-        """Pop one value off the right side of the ca.
+    def popr(self) -> D | Never:
+        """Pop one value off the right side of the CA.
+
+        Raises `ValueError` when called on an empty CA.
 
-        * raises `ValueError` when called on an empty ca
         """
-        if self._cnt > 0:
-            d, self._data[self._rear], self._rear, self._cnt = \
-                self._data[self._rear], None, (self._rear - 1) % self._cap, self._cnt - 1
-        elif self._cnt < 1:
-            msg = 'Method popR called on an empty ca'
-            raise ValueError(msg)
+        if self._cnt > 1:
+            d, self._data[self._rear], self._rear, self._cnt = (
+                self._data[self._rear],
+                None,
+                (self._rear - 1) % self._cap,
+                self._cnt - 1,
+            )
+        elif self._cnt == 1:
+            d, self._data[self._front], self._cnt, self._front, self._rear = (
+                self._data[self._front],
+                None,
+                0,
+                0,
+                self._cap - 1,
+            )
         else:
-            d, self._data[self._front], self._cnt, self._front, self._rear = \
-                self._data[self._front], None, 0, 0, self._cap - 1
+            msg = 'Method popr called on an empty CA'
+            raise ValueError(msg)
         return cast(D, d)
 
-    def popLD(self, default: D, /) -> D:
+    def popld(self, default: D, /) -> D:
         """Pop one value from left, provide a mandatory default value.
 
-        * safe version of popL
-        * returns a default value in the event the `ca` is empty
+        - safe version of popl
+        - returns a default value in the event the `CA` is empty
+
         """
         try:
-            return self.popL()
+            return self.popl()
         except ValueError:
             return default
 
-    def popRD(self, default: D, /) -> D:
+    def poprd(self, default: D, /) -> D:
         """Pop one value from right, provide a mandatory default value.
 
-        * safe version of popR
-        * returns a default value in the event the `ca` is empty
+        - safe version of popr
+        - returns a default value in the event the `CA` is empty
+
         """
         try:
-            return self.popR()
+            return self.popr()
         except ValueError:
             return default
 
-    def popLT(self, max: int) -> tuple[D, ...]:
-        """Pop multiple values from left side of ca.
+    def poplt(self, maximum: int) -> tuple[D, ...]:
+        """Pop multiple values from left side of `CA`.
+
+        - returns the results in a tuple of type `tuple[~D, ...]`
+        - returns an empty tuple if `CA` is empty
+        - pop no more that `max` values
+        - will pop less if `CA` becomes empty
 
-        * returns the results in a tuple of type `tuple[~D, ...]`
-        * returns an empty tuple if `ca` is empty
-        * pop no more that `max` values
-        * will pop less if `ca` becomes empty
         """
         ds: list[D] = []
 
-        while max > 0:
+        while maximum > 0:
             try:
-                ds.append(self.popL())
+                ds.append(self.popl())
             except ValueError:
                 break
             else:
-                max -= 1
+                maximum -= 1
 
         return tuple(ds)
 
-    def popRT(self, max: int) -> tuple[D, ...]:
-        """Pop multiple values from right side of `ca`.
+    def poprt(self, max: int) -> tuple[D, ...]:
+        """Pop multiple values from right side of `CA`.
+
+        - returns the results in a tuple of type `tuple[~D, ...]`
+        - returns an empty tuple if `CA` is empty
+        - pop no more that `max` values
+        - will pop less if `CA` becomes empty
 
-        * returns the results in a tuple of type `tuple[~D, ...]`
-        * returns an empty tuple if `ca` is empty
-        * pop no more that `max` values
-        * will pop less if `ca` becomes empty
         """
         ds: list[D] = []
         while max > 0:
             try:
-                ds.append(self.popR())
+                ds.append(self.popr())
             except ValueError:
                 break
             else:
@@ -322,113 +390,114 @@ class ca[D](Sequence[D]):
 
         return tuple(ds)
 
-    def rotL(self, n: int=1) -> None:
-        """Rotate ca arguments left n times."""
+    def rotl(self, n: int = 1) -> None:
+        """Rotate `CA` arguments left n times."""
         if self._cnt < 2:
             return
         while n > 0:
-            self.pushR(self.popL())
+            self.pushr(self.popl())
             n -= 1
 
-    def rotR(self, n: int=1) -> None:
-        """Rotate ca arguments right n times."""
+    def rotr(self, n: int = 1) -> None:
+        """Rotate `CA` arguments right n times."""
         if self._cnt < 2:
             return
         while n > 0:
-            self.pushL(self.popR())
+            self.pushl(self.popr())
             n -= 1
 
-    def map[U](self, f: Callable[[D], U], /) -> ca[U]:
-        """Apply function f over contents, returns new `ca` instance.
+    def map[U](self, f: Callable[[D], U], /) -> CA[U]:
+        """Apply function f over contents, returns new `CA` instance.
+
+        - parameter `f` function of type `f[~D, ~U] -> CA[~U]`
+        - returns a new instance of type `CA[~U]`
 
-        * parameter `f` function of type `f[~D, ~U] -> ca[~U]`
-        * returns a new instance of type `ca[~U]`
         """
-        return ca(map(f, self))
-
-    def foldL[L](self, f: Callable[[L, D], L], /, initial: L|None=None) -> L:
-        """Left fold ca via function and optional initial value.
-
-        * parameter `f` function of type `f[~L, ~D] -> ~L`
-          * the first argument to `f` is for the accumulated value.
-        * parameter `initial` is an optional initial value
-        * returns the reduced value of type `~L`
-          * note that `~L` and `~D` can be the same type
-          * if an initial value is not given then by necessity `~L = ~D`
-        * raises `ValueError` when called on an empty `ca` and `initial` not given
+        return CA(map(f, self))
+
+    def foldl[L](self, f: Callable[[L, D], L], /, initial: L | None = None) -> L:
+        """Left fold `CA` via function and optional initial value.
+
+        - parameter `f` function of type `f[~L, ~D] -> ~L`
+          - the first argument to `f` is for the accumulated value.
+        - parameter `initial` is an optional initial value
+        - returns the reduced value of type `~L`
+          - note that `~L` and `~D` can be the same type
+          - if an initial value is not given then by necessity `~L = ~D`
+        - raises `ValueError` when called on an empty `ca` and `initial` not given
+
         """
         if self._cnt == 0:
             if initial is None:
-                msg = 'Method foldL called on an empty ca without an initial value.'
+                msg = 'Method foldl called on an empty `CA` without an initial value.'
                 raise ValueError(msg)
-            else:
-                return initial
-        else:
-            if initial is None:
-                acc = cast(L, self[0])  # in this case D = L
-                for idx in range(1, self._cnt):
-                    acc = f(acc, self[idx])
-                return acc
-            else:
-                acc = initial
-                for d in self:
-                    acc = f(acc, d)
-                return acc
-
-    def foldR[R](self, f: Callable[[D, R], R], /, initial: R|None=None) -> R:
-        """Right fold ca via function and optional initial value.
-
-        * parameter `f` function of type `f[~D, ~R] -> ~R`
-          * the second argument to f is for the accumulated value
-        * parameter `initial` is an optional initial value
-        * returns the reduced value of type `~R`
-          * note that `~R` and `~D` can be the same type
-          * if an initial value is not given then by necessity `~R = ~D`
-        * raises `ValueError` when called on an empty `ca` and `initial` not given
+            return initial
+
+        if initial is None:
+            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 = initial
+        for d in self:
+            acc = f(acc, d)
+        return acc
+
+    def foldr[R](self, f: Callable[[D, R], R], /, initial: R | None = None) -> R:
+        """Right fold `CA` via function and optional initial value.
+
+        - parameter `f` function of type `f[~D, ~R] -> ~R`
+          - the second argument to f is for the accumulated value
+        - parameter `initial` is an optional initial value
+        - returns the reduced value of type `~R`
+          - note that `~R` and `~D` can be the same type
+          - if an initial value is not given then by necessity `~R = ~D`
+        - raises `ValueError` when called on an empty `CA` and `initial` not given
+
         """
         if self._cnt == 0:
             if initial is None:
-                msg = 'Method foldR called on an empty ca without an initial value.'
+                msg = 'Method foldr called on empty `CA` without initial value.'
                 raise ValueError(msg)
-            else:
-                return initial
-        else:
-            if initial is None:
-                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
-            else:
-                acc = initial
-                for d in reversed(self):
-                    acc = f(d, acc)
-                return acc
+            return initial
+
+        if initial is None:
+            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 = initial
+        for d in reversed(self):
+            acc = f(d, acc)
+        return acc
 
     def capacity(self) -> int:
-        """Returns current capacity of the ca."""
+        """Returns current capacity of the `CA`."""
         return self._cap
 
     def empty(self) -> None:
-        """Empty the ca, keep current capacity."""
-        self._data, self._front, self._rear = [None]*self._cap, 0, self._cap
+        """Empty the `CA`, keep current capacity."""
+        self._data, self._front, self._rear = [None] * self._cap, 0, self._cap
+
+    def fraction_filled(self) -> float:
+        """Returns fractional capacity of the `CA`."""
+        return self._cnt / self._cap
 
-    def fractionFilled(self) -> float:
-        """Returns fractional capacity of the ca."""
-        return self._cnt/self._cap
+    def resize(self, minimum_capacity: int = 2) -> None:
+        """Compact `CA` and resize to `minimum_capacity` if necessary.
 
-    def resize(self, minimum_capacity: int=2) -> None:
-        """Compact `ca` and resize to `min_cap` if necessary.
+        To just compact the `CA`, do not provide a minimum capacity.
 
-        * to just compact the `ca`, do not provide a min_cap
         """
         self._compact_storage_capacity()
         if (min_cap := minimum_capacity) > self._cap:
-            self._cap, self._data = \
-                min_cap, self._data + [None]*(min_cap - self._cap)
+            self._cap, self._data = min_cap, self._data + [None] * (min_cap - self._cap)
             if self._cnt == 0:
                 self._front, self._rear = 0, self._cap - 1
 
-def CA[D](*ds: D) -> ca[D]:
-    """Function to produce a `ca` array from a variable number of arguments."""
-    return ca(ds)
 
+def ca[D](*ds: D) -> CA[D]:
+    """Function to produce a `CA` array from a variable number of arguments."""
+    return CA(ds)

dtools_circular_array-3.11.0.dist-info/METADATA

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: dtools.circular-array
+Version: 3.11.0
+Summary: ### Developer Tools - circular array data structure
+Keywords: circular array,circle array,CA,dequeue,dqueue,FIFO,LIFO,pop,push,indexable,auto-resizing,auto resizing,resizing
+Author-email: "Geoffrey R. Scheller" <geoffrey@scheller.com>
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+License-File: LICENSE
+Requires-Dist: pytest >=8.3.5 ; extra == "test"
+Project-URL: Changelog, https://github.com/grscheller/dtools-circular-array/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://grscheller.github.io/dtools-docs/circular-array
+Project-URL: Source, https://github.com/grscheller/dtools-circular-array
+Provides-Extra: test
+
+# Developer Tools - Circular Array
+
+Python package containing a module implementing a circular array data
+structure,
+
+- **Repositories**
+  - [dtools.circular-array][1] project on *PyPI*
+  - [Source code][2] on *GitHub*
+- **Detailed documentation**
+  - [Detailed API documentation][3] on *GH-Pages*
+
+This project is part of the [Developer Tools for Python][4] **dtools.**
+namespace project.
+
+## Overview
+
+- O(1) amortized pushes and pops either end.
+- O(1) indexing
+- fully supports slicing
+- safely mutates while iterating over copies of previous state
+
+### Module circular_array
+
+A full featured, auto resizing circular array. Python package containing
+a module implementing a full featured, indexable, sliceable, double
+sided, auto-resizing circular array data structure.
+
+Useful either if used directly as an improved version of a Python List
+or in a "has-a" relationship when implementing other data structures.
+
+- *module* dtools.circular_array
+  - *class* ca: circular array data structure
+  - *function* CA: factory function to produce a ca from data
+
+Above nomenclature modeled after of a builtin data type like `list`, where
+`ca` takes an optional iterator as an argument and CA is all caps to represent
+syntactic sugar like `[]` or `{}`.
+
+#### Usage
+
+```python
+    from dtools.circular_array.ca import CA
+    
+    ca1 = ca(1, 2, 3)
+    assert ca1.popl() == 1
+    assert ca1.popr() == 3
+    ca1.pushr(42, 0)
+    ca1.pushl(0, 1)
+    assert repr(ca1) == 'ca(1, 0, 2, 42, 0)'
+    assert str(ca1) == '(|1, 0, 2, 42, 0|)'
+    
+    ca2 = CA(range(1,11))
+    assert repr(ca2) == 'ca(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)'
+    assert str(ca2) == '(|1, 2, 3, 4, 5, 6, 7, 8, 9, 10|)'
+    assert len(ca2) == 10
+    tup3 = ca2.poplt(3)
+    tup4 = ca2.poprt(4)
+    assert tup3 == (1, 2, 3)
+    assert tup4 == (10, 9, 8, 7)
+    assert ca2 == CA(4, 5, 6)
+    four, *rest = ca.popft(1000)
+    assert four == 4
+    assert rest == [5, 6]
+    assert len(ca2) == 0
+    
+    ca3 = CA([1, 2, 3])
+    assert ca3.popld(42) == 1
+    assert ca3.poprd(42) == 3
+    assert ca3.popld(42) == 2
+    assert ca3.poprd(42) == 42
+    assert ca3.popld(42) == 42
+    assert len(ca2) == 0
+```
+
+______________________________________________________________________
+
+[1]: https://pypi.org/project/dtools.circular-array
+[2]: https://github.com/grscheller/dtools-circular-array
+[3]: https://grscheller.github.io/dtools-docs/circular-array
+[4]: https://github.com/grscheller/dtools-docs
+

dtools_circular_array-3.11.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+dtools/circular_array/__init__.py,sha256=JfokAp0Jh8b5oU6aYQKNG1_8FB1OFT4geAowCLQSGQ0,1222
+dtools/circular_array/ca.py,sha256=nAyi-fuIriMt2R08Ibq_KCdKuMNM199hTfye7Ap9qj8,16604
+dtools/circular_array/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dtools_circular_array-3.11.0.dist-info/licenses/LICENSE,sha256=csqbZRvA3Nyuav1aszWvswE8CZtaKr-hMjjjcKqms7w,10774
+dtools_circular_array-3.11.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+dtools_circular_array-3.11.0.dist-info/METADATA,sha256=lE6GWKO2BQU_EEKseM5UKSLqsz5Rc-s8YdAiQt8Gjvw,3491
+dtools_circular_array-3.11.0.dist-info/RECORD,,

{dtools_circular_array-3.9.1.dist-info → dtools_circular_array-3.11.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: flit 3.10.1
+Generator: flit 3.12.0
 Root-Is-Purelib: true
 Tag: py3-none-any

dtools_circular_array-3.9.1.dist-info/METADATA

@@ -1,90 +0,0 @@
-Metadata-Version: 2.3
-Name: dtools.circular-array
-Version: 3.9.1
-Summary: ### Circular Array
-Keywords: circular array,circle array,CA,double ended queue,dequeue,dqueue,pop,push,popL,popR,pushL,pushR,indexable,auto-resizing,auto resizing,resizing
-Author-email: "Geoffrey R. Scheller" <geoffrey@scheller.com>
-Requires-Python: >=3.12
-Description-Content-Type: text/markdown
-Classifier: Development Status :: 5 - Production/Stable
-Classifier: Framework :: Pytest
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: Apache Software License
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Typing :: Typed
-Requires-Dist: pytest >=8.3.2 ; extra == "test"
-Project-URL: Changelog, https://github.com/grscheller/dtools-circular-array/blob/main/CHANGELOG.md
-Project-URL: Documentation, https://grscheller.github.io/dtools-docs/circular-array
-Project-URL: Source, https://github.com/grscheller/dtools-circular-array
-Provides-Extra: test
-
-# Developer Tools - Circular Array Implementation
-
-Python module implementing a full featured, indexable,
-double sided, auto-resizing queue data structure.
-
-* **Repositories**
-  * [dtools.circular-array][1] project on *PyPI*
-  * [Source code][2] on *GitHub*
-* **Detailed documentation**
-  * [Detailed API documentation][3] on *GH-Pages*
-
-This project is part of the
-[Developer Tools for Python][4] **dtools.** namespace project.
-
-### Overview
-
-Useful if used directly as an improved version of a Python List or in
-a "has-a" relationship when implementing other data structures.
-
-* O(1) pushes and pops either end.
-* O(1) indexing
-* fully supports slicing
-* iterates over copies of the data allowing ca to mutate
-
-### Usage
-
-```python
-from dtools.circular_array.ca import CA
-
-ca = CA(1, 2, 3)
-assert ca.popL() == 1
-assert ca.popR() == 3
-ca.pushR(42, 0)
-ca.pushL(0, 1)
-assert repr(ca) == 'CA(1, 0, 2, 42, 0)'
-assert str(ca) == '(|1, 0, 2, 42, 0|)'
-
-ca = CA(*range(1,11))
-assert repr(ca) == 'CA(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)'
-assert str(ca) == '(|1, 2, 3, 4, 5, 6, 7, 8, 9, 10|)'
-assert len(ca) == 10
-tup3 = ca.popLT(3)
-tup4 = ca.popRT(4)
-assert tup3 == (1, 2, 3)
-assert tup4 == (10, 9, 8, 7)
-
-assert ca == CA(4, 5, 6)
-four, *rest = ca.popFT(1000)
-assert four == 4
-assert rest == [5, 6]
-assert len(ca) == 0
-
-ca = CA(1, 2, 3)
-assert ca.popLD(42) == 1
-assert ca.popRD(42) == 3
-assert ca.popLD(42) == 2
-assert ca.popRD(42) == 42
-assert ca.popLD(42) == 42
-assert len(ca) == 0
-```
-
----
-
-[1]: https://pypi.org/project/dtools.circular-array
-[2]: https://github.com/grscheller/dtools-circular-array
-[3]: https://grscheller.github.io/dtools-docs/circular-array
-[4]: https://github.com/grscheller/dtools-docs
-
-

dtools_circular_array-3.9.1.dist-info/RECORD

@@ -1,7 +0,0 @@
-dtools/circular_array/__init__.py,sha256=HdCpPnMesO8z3CGuoNfqMjYLRmiedHYdcQTGE6e6qf8,922
-dtools/circular_array/ca.py,sha256=a-hcJ4hQhLexqX2fqsOogEIPjpzR8PQ5zAE49-Xi8tc,15722
-dtools/circular_array/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-dtools_circular_array-3.9.1.dist-info/LICENSE,sha256=csqbZRvA3Nyuav1aszWvswE8CZtaKr-hMjjjcKqms7w,10774
-dtools_circular_array-3.9.1.dist-info/WHEEL,sha256=CpUCUxeHQbRN5UGRQHYRJorO5Af-Qy_fHMctcQ8DSGI,82
-dtools_circular_array-3.9.1.dist-info/METADATA,sha256=r80WBcYr2g_k-1uH27NICHx3be6BuKivHiI5tGyMtBY,2717
-dtools_circular_array-3.9.1.dist-info/RECORD,,