dtools.circular-array 3.12.1__py3-none-any.whl → 3.13.0__py3-none-any.whl

dtools/circular_array/__init__.py

@@ -19,15 +19,14 @@ data structure with amortized O(1) pushes and pops either end.
 
 Circular array data structure.
 
-- *module* dtools.circular_array
+- *module* dtools.circular_array.ca
   - *class* dtools.circular_array.ca.CA
     - initializer takes up to 1 iterable
   - *function* dtools.circular_array.ca.ca
-    - factory function taking a variable number of arguments
+    - constructs a `CA` from a variable number of arguments
 
 """
 
-__version__ = '3.12.1'
 __author__ = 'Geoffrey R. Scheller'
 __copyright__ = 'Copyright (c) 2023-2025 Geoffrey R. Scheller'
 __license__ = 'Apache License 2.0'

dtools/circular_array/ca.py

@@ -12,41 +12,42 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""### Module for an indexable circular array data structure."""
+"""### An indexable circular array data structure."""
 
 from __future__ import annotations
+
 from collections.abc import Callable, Iterable, Iterator
 from typing import cast, Never, overload, TypeVar
 
 __all__ = ['CA', 'ca']
 
-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.
+D = TypeVar('D')
 
 
-class CA[D]():
+class CA[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)
+    - in boolean context returns
+      - `True` when not empty
+      - `False` when empty
+    - in comparisons compare identity before equality, like builtins do
     - raises `IndexError` for out-of-bounds indexing
-    - raises `ValueError` for popping from or folding an empty `ca`
+    - raises `ValueError` for popping from or folding an empty `CA`
 
     """
 
     __slots__ = '_data', '_cnt', '_cap', '_front', '_rear'
 
+    L = TypeVar('L')
+    R = TypeVar('R')
+    U = TypeVar('U')
+
     def __init__(self, *dss: Iterable[D]) -> None:
         if len(dss) < 2:
             self._data: list[D | None] = (
@@ -77,7 +78,6 @@ class CA[D]():
             self._front, self._cap = self._front + self._cap, 2 * self._cap
 
     def _compact_storage_capacity(self) -> None:
-        """Compact the CA."""
         match self._cnt:
             case 0:
                 self._cap, self._front, self._rear, self._data = 2, 0, 1, [None, None]
@@ -211,11 +211,11 @@ class CA[D]():
             raise IndexError(msg1 + msg2 + msg3)
 
     @overload
-    def __delitem__(self, idx: int) -> None: ...
+    def __delitem__(self, idx: int, /) -> None: ...
     @overload
-    def __delitem__(self, idx: slice) -> None: ...
+    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)
@@ -259,7 +259,11 @@ class CA[D]():
         return True
 
     def pushl(self, *ds: D) -> None:
-        """Push data from the left onto the CA."""
+        """Push left.
+
+        - push data from the left onto the CA
+
+        """
         for d in ds:
             if self._cnt == self._cap:
                 self._double_storage_capacity()
@@ -267,7 +271,11 @@ class CA[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 right.
+
+        - push data from the right onto the CA
+
+        """
         for d in ds:
             if self._cnt == self._cap:
                 self._double_storage_capacity()
@@ -275,9 +283,10 @@ class CA[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 left.
 
-        Raises `ValueError` when called on an empty CA.
+        - pop one value off the left side of the `CA`
+        - raises `ValueError` when called on an empty `CA`
 
         """
         if self._cnt > 1:
@@ -301,9 +310,10 @@ class CA[D]():
         return cast(D, d)
 
     def popr(self) -> D | Never:
-        """Pop one value off the right side of the CA.
+        """Pop right
 
-        Raises `ValueError` when called on an empty CA.
+        - pop one value off the right side of the `CA`
+        - raises `ValueError` when called on an empty `CA`
 
         """
         if self._cnt > 1:
@@ -330,7 +340,7 @@ class CA[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 the default value if `CA` is empty
 
         """
         try:
@@ -342,7 +352,7 @@ class CA[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 the default value if `CA` is empty
 
         """
         try:
@@ -353,9 +363,8 @@ class CA[D]():
     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
+        - returns the results in a tuple of type
+        - pop no more that `maximum` values
         - will pop less if `CA` becomes empty
 
         """
@@ -374,9 +383,8 @@ class CA[D]():
     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
-        - pop no more that `max` values
+        - returns the results in a tuple
+        - pop no more that `maximum` values
         - will pop less if `CA` becomes empty
 
         """
@@ -392,34 +400,31 @@ class CA[D]():
         return tuple(ds)
 
     def rotl(self, n: int = 1, /) -> None:
-        """Rotate `CA` arguments left n times."""
+        """Rotate `CA` components to the left n times."""
         if self._cnt < 2:
             return
         for _ in range(n, 0, -1):
             self.pushr(self.popl())
 
     def rotr(self, n: int = 1, /) -> None:
-        """Rotate `CA` arguments right n times."""
+        """Rotate `CA` components to the right n times."""
         if self._cnt < 2:
             return
         for _ in range(n, 0, -1):
             self.pushl(self.popr())
 
     def map[U](self, f: Callable[[D], U], /) -> CA[U]:
-        """Apply function f over contents, returns new `CA` instance.
+        """Apply function `f` over the `CA` contents,
 
-        - parameter `f` function of type `f[~D, ~U] -> CA[~U]`
-        - returns a new instance of type `CA[~U]`
+        - returns a new `CA` instance
 
         """
         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.
+    def foldl[L](self, f: Callable[[L, D], L], initial: L | None = None, /) -> L:
+        """Left fold `CA` with function `f` and an 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
+        - first argument to `f` is for the accumulated 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`
@@ -443,12 +448,10 @@ class CA[D]():
             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.
+    def foldr[R](self, f: Callable[[D, R], R], initial: R | None = None, /) -> R:
+        """Right fold `CA` with function `f` and an 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
+        - second argument to f is for the accumulated 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`
@@ -497,6 +500,6 @@ class CA[D]():
                 self._front, self._rear = 0, self._cap - 1
 
 
-def ca[T](*ds: T) -> CA[T]:
+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.12.1.dist-info → dtools_circular_array-3.13.0.dist-info}/METADATA

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: dtools.circular-array
-Version: 3.12.1
+Version: 3.13.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
+Keywords: circular array,dequeue,pop,push,indexable,auto resizing
 Author-email: "Geoffrey R. Scheller" <geoffrey@scheller.com>
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
@@ -17,6 +17,7 @@ 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: Homepage, https://github.com/grscheller/dtools-docs
 Project-URL: Source, https://github.com/grscheller/dtools-circular-array
 Provides-Extra: test
 
@@ -39,24 +40,25 @@ namespace project.
 - O(1) amortized pushes and pops either end.
 - O(1) indexing
 - fully supports slicing
-- safely mutates while iterating over copies of previous state
+- safely mutates over 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.
+A full featured auto resizing circular array data structure. Double
+sided, indexable, sliceable, and iterable. When iterated, uses cached
+copies of its present state so that the circular array itself can safely
+be mutated.
 
-Useful either if used directly as an improved version of a Python List
-or in a "has-a" relationship when implementing other data structures.
+Useful either if used directly like 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
+  - *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 `{}`.
+Above nomenclature modeled after builtin data types like `list`, where
+`CA` and `ca` correspond respectfully to `list` and  `[]` in their use
+cases.
 
 #### Usage
 

dtools_circular_array-3.13.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+dtools/circular_array/__init__.py,sha256=T_Jqa8AzDhow6q5O6A_FP5kCHBohEYJYSpo5xcsfTuU,1168
+dtools/circular_array/ca.py,sha256=xSvYBPAFAJU_KbHAjmSIFAt3Pq9YkVVojo0BIoxIZPY,15918
+dtools/circular_array/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dtools_circular_array-3.13.0.dist-info/licenses/LICENSE,sha256=csqbZRvA3Nyuav1aszWvswE8CZtaKr-hMjjjcKqms7w,10774
+dtools_circular_array-3.13.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+dtools_circular_array-3.13.0.dist-info/METADATA,sha256=NRnV41SCn3OKLWHgud6_WpQg_dr9WGbeXraJ6CkzAZg,3448
+dtools_circular_array-3.13.0.dist-info/RECORD,,

dtools_circular_array-3.12.1.dist-info/RECORD

@@ -1,7 +0,0 @@
-dtools/circular_array/__init__.py,sha256=2CvFEORjHTaRYTteVH-Ifo7THhbttgif71VigBM-3-Y,1189
-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.1.dist-info/licenses/LICENSE,sha256=csqbZRvA3Nyuav1aszWvswE8CZtaKr-hMjjjcKqms7w,10774
-dtools_circular_array-3.12.1.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
-dtools_circular_array-3.12.1.dist-info/METADATA,sha256=9HGyzkYTReGc9LUbP_X1qbWEK-EQKVwA_gAaZdI_5cI,3495
-dtools_circular_array-3.12.1.dist-info/RECORD,,