pythonic-fp-circulararray 6.0.4__py3-none-any.whl → 6.1.1__py3-none-any.whl

pythonic_fp/circulararray/__init__.py

@@ -14,19 +14,17 @@
 
 """
 Circular Array
---------------
+==============
 
-.. admonition:: Stateful circular array data structures.
+.. admonition:: Stateful circular array data structures
 
-    - O(1) pops and pushes either end
+    - O(1) pops and pushes on either side
     - O(1) size determination
     - O(1) indexing
-    - Two types of circular arrays, fixed and variable capacity
+    - two types of circular arrays
 
-.. note::
-
-    - Class constructors ``CA`` and ``CAF`` take an optional iterator to populate circular array.
-    - Factory Functions ``ca`` and ``caf`` take a variable number of parameters to populate circular array.
+      - fixed capacity: ``CAF``
+      - variable capacity: ``CA``
 
 """
 

pythonic_fp/circulararray/auto.py

@@ -12,20 +12,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""
-.. admonition:: Variable storage capacity circular array CA
-
-    - 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
-
-"""
-
 from collections.abc import Callable, Iterable, Iterator
 from typing import cast, Final, overload
 from pythonic_fp.gadgets.sentinels.novalue import NoValue
@@ -36,17 +22,37 @@ nada: Final[NoValue] = NoValue()
 
 
 class CA[X]:
+    """
+    .. admonition:: Auto resizing circular array CA
+
+        - 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 but not threadsafe
+        - comparisons compare identity before equality, like builtins
+        - in boolean context, falsy when empty, otherwise truthy
+        - function ``ca`` produces auto-resizing circular array
+          from arguments
+
+    """
     __slots__ = '_xs', '_cnt', '_cap', '_front', '_rear'
 
     def __init__(self, *xs: Iterable[X]) -> None:
         """
-        :param xs: Optionally takes a single iterable to initially populate the circular array.
-        :raises TypeError: When ``xs[0]`` not iterable.
-        :raises ValueError: If more than 1 iterable is given.
+        .. admonition:: initializer
+
+            Populate ``CA`` with an optional iterable
+            from front (left) to rear (right).
+
+            :param xs: Takes 0 or 1 iterable parameters.
+            :raises ValueError: When more than one parameter is provided.
+            :raises TypeError: When passed a non-iterable parameter.
 
         """
         if (size := len(xs)) > 1:
-            msg = f'CA expects at most 1 argument, got {size}'
+            msg = f'CA expects at most 1 iterable, got {size}'
             raise ValueError(msg)
         if size:
             values: list[X | NoValue] = list(cast(Iterable[X | NoValue], xs[0]))
@@ -139,7 +145,96 @@ class CA[X]:
                         + [nada],
                     )
 
+    def __bool__(self) -> bool:
+        """
+        .. admonition:: bool
+
+            - falsy when empty
+            - truthy when not empty
+
+            :returns: ``True`` when not empty,
+                      ``False`` otherwise.
+
+        """
+        return self._cnt > 0
+
+    def __len__(self) -> int:
+        """
+        .. admonition:: length
+
+            Number of items in the ``CA``.
+
+            :returns: The number of items in the ``CA``.
+
+        """
+        return self._cnt
+
+    def __eq__(self, other: object) -> bool:
+        """
+        .. admonition:: equality comparison
+
+            Efficiently compare ``CA`` to another object.
+
+            :param other: The object to be compared.
+            :returns: ``True`` if ``other`` is another ``CA`` whose
+                      contents compare as equal to the corresponding
+                      contents of the ``CA``, otherwise ``False``.
+
+        """
+        if self is other:
+            return True
+        if not isinstance(other, type(self)):
+            return False
+
+        (
+            front1,
+            cnt1,
+            capacity1,
+            front2,
+            cnt2,
+            capacity2,
+        ) = (
+            self._front,
+            self._cnt,
+            self._cap,
+            other._front,
+            other._cnt,
+            other._cap,
+        )
+
+        if cnt1 != cnt2:
+            return False
+
+        for nn in range(cnt1):
+            if (
+                self._xs[(front1 + nn) % capacity1]
+                is other._xs[(front2 + nn) % capacity2]
+            ):
+                continue
+            if (
+                self._xs[(front1 + nn) % capacity1]
+                != other._xs[(front2 + nn) % capacity2]
+            ):
+                return False
+        return True
+
     def __iter__(self) -> Iterator[X]:
+        """
+        .. admonition:: iterate
+
+            Iterates circular array, front (left) to rear (right).
+
+            .. warning
+
+                Not thread safe, especially for long living iterators.
+
+                .. tip::
+
+                    Cache contents to make more thread tolerant. Put
+                    a lock around circular array during caching process
+                    to make threadsafe.
+
+        """
         if self._cnt > 0:
             (
                 capacity,
@@ -159,6 +254,22 @@ class CA[X]:
             yield cast(X, current_state[position])
 
     def __reversed__(self) -> Iterator[X]:
+        """
+        .. admonition:: reverse iterate
+
+            Iterates circular array, rear (right) to front (left).
+
+            .. warning
+
+                Not thread safe, especially for long living iterators.
+
+                .. tip::
+
+                    Cache contents to make more thread tolerant. Put
+                    a lock around circular array during caching process
+                    to make threadsafe.
+
+        """
         if self._cnt > 0:
             (
                 capacity,
@@ -177,32 +288,19 @@ class CA[X]:
                 position = (position - 1) % capacity
             yield cast(X, current_state[position])
 
-    def __repr__(self) -> str:
-        """
-        :returns: String of the form ``ca(x1, x2, ..., xn)``.
-
-        """
-        return 'ca(' + ', '.join(map(repr, self)) + ')'
-
-    def __str__(self) -> str:
-        """
-        :returns: String of the form ``(|x1, x2, ..., xn|)``.
-
-        """
-        return '(|' + ', '.join(map(str, self)) + '|)'
-
-    def __bool__(self) -> bool:
-        return self._cnt > 0
-
-    def __len__(self) -> int:
-        return self._cnt
-
     @overload
     def __getitem__(self, idx: int) -> X: ...
     @overload
     def __getitem__(self, idx: slice) -> 'CA[X]': ...
 
     def __getitem__(self, idx: int | slice) -> X | 'CA[X]':
+        """
+        .. admonition:: getitem
+
+            Auto resizing circular arrays are fully indexable
+            and sliceable.
+
+        """
         if isinstance(idx, slice):
             return CA(list(self)[idx])
 
@@ -228,6 +326,13 @@ class CA[X]:
     def __setitem__(self, idx: slice, vals: Iterable[X]) -> None: ...
 
     def __setitem__(self, idx: int | slice, vals: X | Iterable[X]) -> None:
+        """
+        .. admonition:: setitem
+
+            Auto resizing circular arrays are fully indexable
+            and sliceable.
+
+        """
         if isinstance(idx, slice):
             if isinstance(vals, Iterable):
                 item_list = list(self)
@@ -271,6 +376,13 @@ class CA[X]:
     def __delitem__(self, idx: slice) -> None: ...
 
     def __delitem__(self, idx: int | slice) -> None:
+        """
+        .. admonition:: delitem
+
+            Auto resizing circular arrays are fully indexable
+            and sliceable.
+
+        """
         item_list = list(self)
         del item_list[idx]
         _ca = CA(item_list)
@@ -289,62 +401,42 @@ class CA[X]:
         )
         del _ca
 
-    def __eq__(self, other: object) -> bool:
+    def __repr__(self) -> str:
         """
-        :param other: The object to be compared to.
-        :returns: ``True`` if object is another ``CA`` whose items compare
-                  as equal to the corresponding items in the ``CA``,
-                  otherwise ``False``.
+        .. admonition:: repr string
+
+            Construct string 'CA(x₁, x₂, … xₙ)' where
+            x₁, x₂, … xₙ are the contents displayed with ``repr()``.
+
+            :returns: A string to reproduce the ``CA``. 
 
         """
-        if self is other:
-            return True
-        if not isinstance(other, type(self)):
-            return False
+        return 'ca(' + ', '.join(map(repr, self)) + ')'
 
-        (
-            front1,
-            cnt1,
-            capacity1,
-            front2,
-            cnt2,
-            capacity2,
-        ) = (
-            self._front,
-            self._cnt,
-            self._cap,
-            other._front,
-            other._cnt,
-            other._cap,
-        )
+    def __str__(self) -> str:
+        r"""
+        .. admonition:: user string
 
-        if cnt1 != cnt2:
-            return False
+            Construct string '(\| x₁, x₂, … xₙ \|)' where
+            x₁, x₂, ..., xₙ are the contents displayed with ``str()``.
 
-        for nn in range(cnt1):
-            if (
-                self._xs[(front1 + nn) % capacity1]
-                is other._xs[(front2 + nn) % capacity2]
-            ):
-                continue
-            if (
-                self._xs[(front1 + nn) % capacity1]
-                != other._xs[(front2 + nn) % capacity2]
-            ):
-                return False
-        return True
+            :returns: A estring meaningful to an end user.
+
+        """
+        return '(| ' + ', '.join(map(str, self)) + ' |)'
 
     def pushl(self, *xs: X) -> None:
         """
-        .. admonition:: Push left
+        .. admonition:: push left
 
             Push items from the left onto the ``CA`` in the
             order they were iterated.
 
-        :param xs: Items to be pushed onto the front of the circular array from the left.
+            :param xs: Items to be pushed onto the front of the ``CA``
+                       from the left.
 
         """
-        for item in xs:
+        for x in xs:
             if self._cnt == self._cap:
                 self._double_storage_capacity()
             (
@@ -353,18 +445,19 @@ class CA[X]:
                 self._cnt,
             ) = (
                 (self._front - 1) % self._cap,
-                item,
+                x,
                 self._cnt + 1,
             )
 
     def pushr(self, *xs: X) -> None:
         """
-        .. admonition:: Push right
+        .. admonition:: push right
 
             Push items from the right onto the ``CA`` in the
             order they were iterated.
 
-        :param xs: Items to be pushed onto the rear of the ``CA`` from the right.
+            :param xs: Items to be pushed onto the rear of
+                       the ``CA`` from the right.
 
         """
         for item in xs:
@@ -382,17 +475,17 @@ class CA[X]:
 
     def popl(self) -> X:
         """
-        .. admonition:: Pop left
+        .. admonition:: pop left
 
             Pop a single items off the left side of the ``CA``.
 
-        :returns: Item popped from left side (front) of circular array.
-        :raises ValueError: When called on an empty circular array.
+            :returns: Item popped from left side (front) of the ``CA``.
+            :raises ValueError: When called on an empty ``CA``.
 
         """
         if self._cnt > 1:
             (
-                d,
+                x,
                 self._xs[self._front],
                 self._front,
                 self._cnt,
@@ -404,7 +497,7 @@ class CA[X]:
             )
         elif self._cnt == 1:
             (
-                d,
+                x,
                 self._xs[self._front],
                 self._cnt,
                 self._front,
@@ -419,21 +512,21 @@ class CA[X]:
         else:
             msg = 'Method popl called on an empty CA'
             raise ValueError(msg)
-        return cast(X, d)
+        return cast(X, x)
 
     def popr(self) -> X:
         """
-        .. admonition:: Pop right
+        .. admonition:: pop right
 
             Pop a single items off the right side of the ``CA``.
 
-        :returns: Item popped from right side (rear) of circular array.
-        :raises ValueError: When called on an empty circular array.
+            :returns: Item popped from right side (rear) of the ``CA``.
+            :raises ValueError: When called on an empty ``CA``.
 
         """
         if self._cnt > 1:
             (
-                d,
+                x,
                 self._xs[self._rear],
                 self._rear,
                 self._cnt,
@@ -445,7 +538,7 @@ class CA[X]:
             )
         elif self._cnt == 1:
             (
-                d,
+                x,
                 self._xs[self._front],
                 self._cnt,
                 self._front,
@@ -460,18 +553,18 @@ class CA[X]:
         else:
             msg = 'Method popr called on an empty CA'
             raise ValueError(msg)
-        return cast(X, d)
+        return cast(X, x)
 
     def popld(self, default: X) -> X:
         """
-        .. admonition:: Pop Left with default
+        .. admonition:: pop Left with default
 
             Pop a single items off the left side of the ``CA``.
 
-        :param default: Default value to return if ``CA`` is empty.
-        :returns: Item popped from left side (front) of circular array
-                  if not empty, otherwise return the provided default
-                  value.
+            :param default: Default value to return if ``CA`` is empty.
+            :returns: Item popped from left side (front) of the ``CA``
+                      if not empty, otherwise return the provided
+                      default value.
 
         """
         try:
@@ -481,14 +574,14 @@ class CA[X]:
 
     def poprd(self, default: X) -> X:
         """
-        .. admonition:: Pop Right with default
+        .. admonition:: pop Right with default
 
             Pop a single items off the right side of the ``CA``.
 
-        :param default: Default value to return if ``CA`` is empty.
-        :returns: Item popped from right side (rear) of circular array
-                  if not empty, otherwise return the provided default
-                  value.
+            :param default: Default value to return if ``CA`` is empty.
+            :returns: Item popped from right side (rear) of the ``CA``
+                      if not empty, otherwise return the provided
+                      default value.
 
         """
         try:
@@ -502,21 +595,22 @@ class CA[X]:
 
             Pop items off the left side of the ``CA``.
 
-        :param maximum: Maximum number of items to pop, may pop less if not enough items in ``CA``.
-        :returns: A ``tuple`` of the items popped, left to right.
+            :param maximum: Maximum number of items to pop,
+                            may pop less if not enough items in ``CA``.
+            :returns: A ``tuple`` of the items popped, left to right.
 
         """
-        item_list: list[X] = []
+        xs: list[X] = []
 
         while maximum > 0:
             try:
-                item_list.append(self.popl())
+                xs.append(self.popl())
             except ValueError:
                 break
             else:
                 maximum -= 1
 
-        return tuple(item_list)
+        return tuple(xs)
 
     def poprt(self, maximum: int) -> tuple[X, ...]:
         """
@@ -524,8 +618,9 @@ class CA[X]:
 
             Pop items off the right side of the ``CA``.
 
-        :param maximum: Maximum number of items to pop, may pop less if not enough items in ``CA``.
-        :returns: A ``tuple`` of the items popped, right to left.
+            :param maximum: Maximum number of items to pop,
+                            may pop less if not enough items in ``CA``.
+            :returns: A ``tuple`` of the items popped, right to left.
 
         """
         item_list: list[X] = []
@@ -545,7 +640,8 @@ class CA[X]:
             Rotate contents of ``CA`` to the left putting first
             item onto rear.
 
-        :param n: Number of times to shift items left. Default 1 time.
+            :param n: Number of times to shift items left.
+                      Default 1 time.
 
         """
         if self._cnt < 2:
@@ -560,7 +656,8 @@ class CA[X]:
             Rotate contents of ``CA`` to the right putting last
             item onto front.
 
-        :param n: Number of times to shift items right. Default 1 time.
+            :param n: Number of times to shift items right.
+                      Default 1 time.
 
         """
         if self._cnt < 2:
@@ -574,8 +671,8 @@ class CA[X]:
 
             Apply function ``f`` over the circular array's contents.
 
-        :param f: Callable from type ``X`` to type ``Y``.
-        :returns: New auto-resizing circular array instance.
+            :param f: Callable from type ``X`` to type ``Y``.
+            :returns: New auto-resizing circular array instance.
 
         """
         return CA(map(f, self))
@@ -591,10 +688,12 @@ class CA[X]:
 
             Fold ``CA`` 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.
-        :returns: Reduced value produced by the left fold.
-        :raises ValueError: When circular array empty and ``start`` not given.
+            :param f: Folding function, first argument to ``f`` is for
+                      the accumulator.
+            :param start: Optional starting item.
+            :returns: Reduced value produced by the left fold.
+            :raises ValueError: When circular array empty and ``start``
+                                not given.
 
         """
         if self._cnt == 0:
@@ -610,8 +709,8 @@ class CA[X]:
             return acc
 
         acc = cast(L, start)
-        for d in self:
-            acc = f(acc, d)
+        for x in self:
+            acc = f(acc, x)
         return acc
 
     @overload
@@ -625,10 +724,12 @@ class CA[X]:
 
             Fold ``CA`` right with a function and optional starting item.
 
-        :param f: Folding function, second argument to ``f`` is for the accumulator.
-        :param start: Optional starting item.
-        :returns: Reduced value produced by the right fold.
-        :raises ValueError: When circular array empty and ``start`` not given.
+            :param f: Folding function, second argument to ``f`` is for
+                      the accumulator.
+            :param start: Optional starting item.
+            :returns: Reduced value produced by the right fold.
+            :raises ValueError: When circular array empty and ``start``
+                                not given.
 
         """
         if self._cnt == 0:
@@ -644,8 +745,8 @@ class CA[X]:
             return acc
 
         acc = cast(R, start)
-        for d in reversed(self):
-            acc = f(d, acc)
+        for x in reversed(self):
+            acc = f(x, acc)
         return acc
 
     def capacity(self) -> int:
@@ -654,7 +755,7 @@ class CA[X]:
 
             Get the current storage capacity of the circular array.
 
-        :returns: Current storage capacity.
+            :returns: Current storage capacity.
 
         """
         return self._cap
@@ -684,7 +785,7 @@ class CA[X]:
 
             Find fraction of the storage capacity which is filled.
 
-        :returns: The ratio count/capacity.
+            :returns: The ratio count/capacity.
 
         """
         return self._cnt / self._cap
@@ -697,7 +798,8 @@ class CA[X]:
             minimum storage capacity. To just compact the circular
             array, do not provide ``minimum_capacity``.
 
-        :param minimum_capacity: Minimum storage capacity to compact the circular array.
+        :param minimum_capacity: Minimum storage capacity to compact
+                                 the circular array.
 
         """
         self._compact_storage_capacity()
@@ -717,10 +819,11 @@ def ca[T](*ts: T) -> CA[T]:
     """
     .. admonition:: Circular array factory function
 
-        Produce a circular array from a variable number of arguments.
+        Produce a auto resizing circular array from
+        a variable number of arguments.
 
-    :param ts: Initial items for a new auto-resizing circular array.
-    :returns: New variable storage capacity circular array.
+        :param ts: Initial items for a new auto-resizing circular array.
+        :returns: New variable storage capacity circular array.
 
     """
     return CA(ts)

pythonic_fp/circulararray/auto.pyi

@@ -5,10 +5,11 @@ __all__ = ['CA', 'ca']
 
 class CA[X]:
     def __init__(self, *xs: Iterable[X]) -> None: ...
-    def __iter__(self) -> Iterator[X]: ...
-    def __reversed__(self) -> Iterator[X]: ...
     def __bool__(self) -> bool: ...
     def __len__(self) -> int: ...
+    def __eq__(self, other: object) -> bool: ...
+    def __iter__(self) -> Iterator[X]: ...
+    def __reversed__(self) -> Iterator[X]: ...
     @overload
     def __getitem__(self, idx: int) -> X: ...
     @overload
@@ -21,7 +22,6 @@ class CA[X]:
     def __delitem__(self, idx: int) -> None: ...
     @overload
     def __delitem__(self, idx: slice) -> None: ...
-    def __eq__(self, other: object) -> bool: ...
     def pushl(self, *xs: X) -> None: ...
     def pushr(self, *xs: X) -> None: ...
     def popl(self) -> X: ...