dtools.circular-array 3.10.1__py3-none-any.whl → 3.12.0__py3-none-any.whl

dtools/circular_array/__init__.py

@@ -12,18 +12,25 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""### Developer Tools - circular array data structure
+"""### Developer Tools - 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.10.1'
+__version__ = '3.12.0'
 __author__ = 'Geoffrey R. Scheller'
 __copyright__ = 'Copyright (c) 2023-2025 Geoffrey R. Scheller'
 __license__ = 'Apache License 2.0'

dtools/circular_array/ca.py

@@ -15,18 +15,19 @@
 """### Module for an indexable circular array data structure."""
 
 from __future__ import annotations
-from collections.abc import Callable, Iterable, Iterator, Sequence
+from collections.abc import Callable, Iterable, Iterator
 from typing import cast, Never, overload, TypeVar
 
-__all__ = ['ca', 'CA']
+__all__ = ['CA', 'ca']
 
-D = TypeVar('D')  # Not needed for mypy, hint for pdoc.
-L = TypeVar('L')
-R = TypeVar('R')
-U = TypeVar('U')
+D = TypeVar('D')  # Needed only for pdoc documentation generation. Otherwise,
+L = TypeVar('L')  # ignored by both MyPy and Python. Makes linters unhappy
+R = TypeVar('R')  # when these are used on function and method signatures due
+U = TypeVar('U')  # to "redefined-outer-name" warnings. Function and method
+T = TypeVar('T')  # signatures do not support variance and bounds constraints.
 
 
-class ca[D](Sequence[D]):
+class CA[D]():
     """Indexable circular array data structure
 
     - generic, stateful data structure
@@ -52,7 +53,7 @@ class ca[D](Sequence[D]):
                 [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
@@ -76,7 +77,7 @@ class ca[D](Sequence[D]):
             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]
@@ -135,7 +136,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)) + '|)'
@@ -149,11 +150,11 @@ 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:
@@ -163,12 +164,12 @@ class ca[D](Sequence[D]):
             return cast(D, self._data[(self._front + cnt + idx) % self._cap])
 
         if cnt == 0:
-            msg0 = 'Trying to get a value from an empty ca.'
+            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.'
+        msg3 = 'while getting value from a CA.'
         raise IndexError(msg1 + msg2 + msg3)
 
     @overload
@@ -181,7 +182,7 @@ class ca[D](Sequence[D]):
             if isinstance(vals, Iterable):
                 data = list(self)
                 data[idx] = vals
-                _ca = ca(data)
+                _ca = CA(data)
                 self._data, self._cnt, self._cap, self._front, self._rear = (
                     _ca._data,
                     _ca._cnt,
@@ -201,12 +202,12 @@ class ca[D](Sequence[D]):
             self._data[(self._front + cnt + idx) % self._cap] = cast(D, vals)
         else:
             if cnt < 1:
-                msg0 = 'Trying to set a value from an empty ca.'
+                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.'
+            msg3 = 'while setting value from a CA.'
             raise IndexError(msg1 + msg2 + msg3)
 
     @overload
@@ -217,7 +218,7 @@ class ca[D](Sequence[D]):
     def __delitem__(self, idx: int | slice) -> None:
         data = list(self)
         del data[idx]
-        _ca = ca(data)
+        _ca = CA(data)
         self._data, self._cnt, self._cap, self._front, self._rear = (
             _ca._data,
             _ca._cnt,
@@ -258,7 +259,7 @@ class ca[D](Sequence[D]):
         return True
 
     def pushl(self, *ds: D) -> None:
-        """Push data from the left onto the ca."""
+        """Push data from the left onto the CA."""
         for d in ds:
             if self._cnt == self._cap:
                 self._double_storage_capacity()
@@ -266,7 +267,7 @@ class ca[D](Sequence[D]):
             self._data[self._front], self._cnt = d, self._cnt + 1
 
     def pushr(self, *ds: D) -> None:
-        """Push data from the right onto the ca."""
+        """Push data from the right onto the CA."""
         for d in ds:
             if self._cnt == self._cap:
                 self._double_storage_capacity()
@@ -274,9 +275,9 @@ class ca[D](Sequence[D]):
             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.
+        """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:
@@ -295,14 +296,14 @@ class ca[D](Sequence[D]):
                 self._cap - 1,
             )
         else:
-            msg = 'Method popl called on an empty ca'
+            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.
+        """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 > 1:
@@ -321,7 +322,7 @@ class ca[D](Sequence[D]):
                 self._cap - 1,
             )
         else:
-            msg = 'Method popr called on an empty ca'
+            msg = 'Method popr called on an empty CA'
             raise ValueError(msg)
         return cast(D, d)
 
@@ -329,7 +330,7 @@ class ca[D](Sequence[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
+        - returns a default value in the event the `CA` is empty
 
         """
         try:
@@ -341,7 +342,7 @@ class ca[D](Sequence[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
+        - returns a default value in the event the `CA` is empty
 
         """
         try:
@@ -349,74 +350,72 @@ class ca[D](Sequence[D]):
         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
+        - returns an empty tuple if `CA` is empty
         - pop no more that `max` values
-        - will pop less if `ca` becomes empty
+        - will pop less if `CA` becomes empty
 
         """
         ds: list[D] = []
 
-        while max > 0:
+        while maximum > 0:
             try:
                 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, maximum: 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
+        - returns an empty tuple if `CA` is empty
         - pop no more that `max` values
-        - will pop less if `ca` becomes empty
+        - will pop less if `CA` becomes empty
 
         """
         ds: list[D] = []
-        while max > 0:
+        while maximum > 0:
             try:
                 ds.append(self.popr())
             except ValueError:
                 break
             else:
-                max -= 1
+                maximum -= 1
 
         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:
+        for _ in range(n, 0, -1):
             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:
+        for _ in range(n, 0, -1):
             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))
+        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.
+        """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.
@@ -429,7 +428,7 @@ class ca[D](Sequence[D]):
         """
         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)
             return initial
 
@@ -445,7 +444,7 @@ class ca[D](Sequence[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.
+        """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
@@ -453,12 +452,12 @@ class ca[D](Sequence[D]):
         - 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
+        - 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)
             return initial
 
@@ -474,21 +473,21 @@ class ca[D](Sequence[D]):
         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."""
+        """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."""
+        """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.
+        """Compact `CA` and resize to `minimum_capacity` if necessary.
 
-        To just compact the `ca`, do not provide a minimum capacity.
+        * to just compact the `CA`, do not provide a minimum capacity
 
         """
         self._compact_storage_capacity()
@@ -498,11 +497,6 @@ class ca[D](Sequence[D]):
                 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.
-
-    Upper case function name used to stand out in place of syntactic sugar
-    used by builtins, like `[]` for list or `{}` for dict or set.
-
-    """
-    return ca(ds)
+def ca[T](*ds: T) -> CA[T]:
+    """Function to produce a `CA` array from a variable number of arguments."""
+    return CA(ds)

{dtools_circular_array-3.10.1.dist-info → dtools_circular_array-3.12.0.dist-info}/METADATA

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: dtools.circular-array
-Version: 3.10.1
-Summary: ### Developer Tools - circular array data structure
-Keywords: circular array,circle array,ca,double ended queue,dequeue,dqueue,pop,push,popl,popr,pushl,pushr,indexable,auto-resizing,auto resizing,resizing
+Version: 3.12.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
@@ -61,38 +61,37 @@ syntactic sugar like `[]` or `{}`.
 #### Usage
 
 ```python
-    from dtools.circular_array.ca import CA
+    from dtools.circular_array.ca import CA, 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|)'
+    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|)'
     
-    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)
+    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 ca == CA(4, 5, 6)
+    assert ca2 == CA(4, 5, 6)
     four, *rest = ca.popft(1000)
     assert four == 4
     assert rest == [5, 6]
-    assert len(ca) == 0
+    assert len(ca2) == 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
+    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
 ```
 
 ______________________________________________________________________

dtools_circular_array-3.12.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+dtools/circular_array/__init__.py,sha256=HLp77z9ZpK_08IeOtC5DxUzSRgOfit2uNMtN2vLPycs,1225
+dtools/circular_array/ca.py,sha256=PRt-AOvR9WqwS6EdKFWXde7VxBc1yOD6kuCK_lXuWFQ,16683
+dtools/circular_array/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dtools_circular_array-3.12.0.dist-info/licenses/LICENSE,sha256=csqbZRvA3Nyuav1aszWvswE8CZtaKr-hMjjjcKqms7w,10774
+dtools_circular_array-3.12.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+dtools_circular_array-3.12.0.dist-info/METADATA,sha256=5teklBZccescI4dK27U5YL7LYb7gYpKyJ8G4VkqaKhA,3495
+dtools_circular_array-3.12.0.dist-info/RECORD,,

dtools_circular_array-3.10.1.dist-info/RECORD

@@ -1,7 +0,0 @@
-dtools/circular_array/__init__.py,sha256=-GZLNI-R4UvHgg5pLNGxdNPYO8LX4Aq6eUp9rYB3Vkg,1018
-dtools/circular_array/ca.py,sha256=FZe0ksC9BFzQXqqRY8YXaEpF0g38CR6-rdMOWcReKcw,16534
-dtools/circular_array/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-dtools_circular_array-3.10.1.dist-info/licenses/LICENSE,sha256=csqbZRvA3Nyuav1aszWvswE8CZtaKr-hMjjjcKqms7w,10774
-dtools_circular_array-3.10.1.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
-dtools_circular_array-3.10.1.dist-info/METADATA,sha256=49FC3FiNoCuhYf7e_gf2KNlYDYZ9Gj8m4M25g2fTCjQ,3505
-dtools_circular_array-3.10.1.dist-info/RECORD,,