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

dtools/{circular_array/ca.py → circular_array.py}

@@ -12,41 +12,51 @@
 # 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.
+
+An indexable, sliceable, auto-resizing circular array
+data structure with amortized O(1) pushes and pops either end.
+
+"""
 
 from __future__ import annotations
+
+__author__ = 'Geoffrey R. Scheller'
+__copyright__ = 'Copyright (c) 2023-2025 Geoffrey R. Scheller'
+__license__ = 'Apache License 2.0'
+
 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`
+    - generic, stateful, invariant 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 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 +87,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 +220,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 +268,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 +280,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 +292,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 +319,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 +349,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 +361,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 +372,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 +392,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 +409,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 +457,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 +509,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.14.0.dist-info}/METADATA

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: dtools.circular-array
-Version: 3.12.1
-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
+Version: 3.14.0
+Summary: ### An indexable circular array data structure.
+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
@@ -16,7 +16,8 @@ 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: Documentation, https://grscheller.github.io/dtools-namespace-projects/circular-array
+Project-URL: Homepage, https://github.com/grscheller/dtools-namespace-projects/blob/main/README.md
 Project-URL: Source, https://github.com/grscheller/dtools-circular-array
 Provides-Extra: test
 
@@ -31,37 +32,41 @@ structure,
 - **Detailed documentation**
   - [Detailed API documentation][3] on *GH-Pages*
 
-This project is part of the [Developer Tools for Python][4] **dtools.**
-namespace project.
+This project is part of the [Developer Tools for Python][4] **dtools**
+namespace projects.
 
 ## Overview
 
 - 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
+    - initializer takes 1 or 0 iterators
+    - like `list` or `set`
+  - *function* `ca`: produces a `CA` from function's arguments
+    - similar use case as syntactic constructs `[]` or `{}`
 
-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
 
 ```python
-    from dtools.circular_array.ca import CA, ca
+    from dtools.circular_array import CA, ca
     
     ca1 = ca(1, 2, 3)
     assert ca1.popl() == 1
@@ -79,8 +84,8 @@ syntactic sugar like `[]` or `{}`.
     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 ca2 == ca(4, 5, 6)
+    four, *rest = ca2.poplt(1000)
     assert four == 4
     assert rest == [5, 6]
     assert len(ca2) == 0
@@ -94,10 +99,8 @@ syntactic sugar like `[]` or `{}`.
     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
+[3]: https://grscheller.github.io/dtools-namespace-projects/circular-array
+[4]: https://github.com/grscheller/dtools-namespace-projects/blob/main/README.md
 

dtools_circular_array-3.14.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+dtools/circular_array.py,sha256=GJn30Xub6oSd2Ltiy76ccUytiNpVS43RJNU4Oax6EkM,16184
+dtools_circular_array-3.14.0.dist-info/licenses/LICENSE,sha256=csqbZRvA3Nyuav1aszWvswE8CZtaKr-hMjjjcKqms7w,10774
+dtools_circular_array-3.14.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+dtools_circular_array-3.14.0.dist-info/METADATA,sha256=PPfMaC0yPeiMRUp9rsXxFtEmw7mUVkJK-DAtffjKjhI,3597
+dtools_circular_array-3.14.0.dist-info/RECORD,,

dtools/circular_array/__init__.py

@@ -1,33 +0,0 @@
-# Copyright 2023-2025 Geoffrey R. Scheller
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-"""### 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.
-
-Circular array data structure.
-
-- *module* dtools.circular_array
-  - *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
-
-"""
-
-__version__ = '3.12.1'
-__author__ = 'Geoffrey R. Scheller'
-__copyright__ = 'Copyright (c) 2023-2025 Geoffrey R. Scheller'
-__license__ = 'Apache License 2.0'

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,,