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

pythonic_fp/circulararray/fixed.py

@@ -12,19 +12,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""
-.. admonition:: Fixed storage capacity circular array CAF
-
-    - O(1) pops and pushes either end
-    - O(1) indexing, does not support slicing
-    - fixed total storage capacity
-    - iterable, safely mutates while iterators iterating over previous state
-    - comparisons compare identity before equality, like builtins
-    - in boolean context, falsy when either empty or full, otherwise truthy
-    - function ``caf`` produces fixed capacity 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
@@ -35,19 +22,38 @@ nada: Final[NoValue] = NoValue()
 
 
 class CAF[X]:
+
+    """
+    .. admonition:: Fixed storage capacity circular array CAF
+
+        - O(1) pops and pushes either end
+        - O(1) indexing, does not support slicing
+        - fixed total storage capacity
+        - iterable but not threadsafe
+        - comparisons compare identity before equality, like builtins
+        - in boolean context, falsy when either empty or full,
+          otherwise truthy
+        - function ``caf`` produces fixed capacity circular array
+          from arguments
+
+    """
     __slots__ = '_xs', '_cnt', '_cap', '_front', '_rear'
 
     def __init__(self, *xs: Iterable[X], cap: int = 2) -> None:
         """
-        :param xs: Optionally takes a single iterable to initially populate the circular array.
-        :param cap: Minimum fixed storage capacity of circular array.
-        :raises TypeError: When ``xs[0]`` not iterable,
-        :raises ValueError: If more than 1 iterable is given.
+        .. admonition:: initializer
+
+            Populate ``CAF`` 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.
 
         """
         cap = max(2, cap)
         if (size := len(xs)) > 1:
-            msg = f'CAF expects at most 1 argument, got {size}'
+            msg = f'CAF expects at most 1 iterable, got {size}'
             raise ValueError(msg)
         if size:
             values: list[X | NoValue] = list(cast(Iterable[X | NoValue], xs[0]))
@@ -66,7 +72,96 @@ class CAF[X]:
             self._front = 0
             self._rear = cnt - 1
 
+    def __bool__(self) -> bool:
+        """
+        .. admonition:: bool
+
+            - falsy if either empty or full
+            - truthy otherwise
+
+            :returns: ``True`` when partially filled,
+                      ``False`` otherwise.
+
+        """
+        return 0 < self._cnt < self._cap
+
+    def __len__(self) -> int:
+        """
+        .. admonition:: length
+
+            Number of items in the ``CAF``.
+
+            :returns: The number of items in the ``CAF``.
+
+        """
+        return self._cnt
+
+    def __eq__(self, other: object) -> bool:
+        """
+        .. admonition:: equality comparison
+
+            Efficiently compare ``CAF`` to another object.
+
+            :param other: The object to be compared.
+            :returns: ``True`` if ``other`` is another ``CAF`` whose
+                      contents compare as equal to the corresponding
+                      contents of the ``CAF``, otherwise ``False``.
+
+        """
+        if self is other:
+            return True
+        if not isinstance(other, type(self)):
+            return False
+
+        (
+            front1,
+            cnt1,
+            cap1,
+            front2,
+            cnt2,
+            cap2,
+        ) = (
+            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) % cap1]
+                is other._xs[(front2 + nn) % cap2]
+            ):
+                continue
+            if (
+                self._xs[(front1 + nn) % cap1]
+                != other._xs[(front2 + nn) % cap2]
+            ):
+                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:
             (
                 cap,
@@ -86,6 +181,22 @@ class CAF[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:
             (
                 cap,
@@ -104,27 +215,14 @@ class CAF[X]:
                 position = (position - 1) % cap
             yield cast(X, current_state[position])
 
-    def __repr__(self) -> str:
+    def __getitem__(self, idx: int) -> X:
         """
-        :returns: String of the form ``caf(x1, x2, ..., xn)``.
+        .. admonition:: getitem
 
-        """
-        return 'caf(' + ', '.join(map(repr, self)) + ')'
+            Fixed capacity circular arrays are indexable but
+            not sliceable.
 
-    def __str__(self) -> str:
         """
-        :returns: String of the form ``(|x1, x2, ..., xn|)``.
-
-        """
-        return '(|' + ', '.join(map(str, self)) + '|)'
-
-    def __bool__(self) -> bool:
-        return 0 < self._cnt < self._cap
-
-    def __len__(self) -> int:
-        return self._cnt
-
-    def __getitem__(self, idx: int) -> X:
         cnt = self._cnt
         if 0 <= idx < cnt:
             return cast(X, self._xs[(self._front + idx) % self._cap])
@@ -142,6 +240,13 @@ class CAF[X]:
         raise IndexError(msg1 + msg2 + msg3)
 
     def __setitem__(self, idx: int, val: X) -> None:
+        """
+        .. admonition:: setitem
+
+            Fixed capacity circular arrays are indexable but
+            not sliceable.
+
+        """
         cnt = self._cnt
         if 0 <= idx < cnt:
             self._xs[(self._front + idx) % self._cap] = val
@@ -157,6 +262,13 @@ class CAF[X]:
             raise IndexError(msg1 + msg2 + msg3)
 
     def __delitem__(self, idx: int) -> None:
+        """
+        .. admonition:: delitem
+
+            Fixed capacity circular arrays are indexable but
+            not sliceable.
+
+        """
         item_list = list(self)
         del item_list[idx]
         _ca = CAF(item_list, cap = self._cap)
@@ -173,59 +285,39 @@ class CAF[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 ``CAF`` whose items compare
-                  as equal to the corresponding items in the ``CAF``,
-                  otherwise ``False``.
+        .. admonition:: repr string
+
+            Construct string 'CAF(x₁, x₂, … xₙ)' where
+            x₁, x₂, … xₙ are the contents displayed with ``repr()``.
+
+            :returns: A string to reproduce the ``CAF``.
 
         """
-        if self is other:
-            return True
-        if not isinstance(other, type(self)):
-            return False
+        return 'caf(' + ', '.join(map(repr, self)) + ')'
 
-        (
-            front1,
-            cnt1,
-            cap1,
-            front2,
-            cnt2,
-            cap2,
-        ) = (
-            self._front,
-            self._cnt,
-            self._cap,
-            other._front,
-            other._cnt,
-            other._cap,
-        )
+    def __str__(self) -> str:
+        r"""
+        .. admonition:: user string
+            Construct string '(\|x₁, x₂, … xₙ\|)' where
+            x₁, x₂, ..., xₙ are the contents displayed with ``str()``.
 
-        if cnt1 != cnt2:
-            return False
+            :returns: A string meaningful to an end user.
 
-        for nn in range(cnt1):
-            if (
-                self._xs[(front1 + nn) % cap1]
-                is other._xs[(front2 + nn) % cap2]
-            ):
-                continue
-            if (
-                self._xs[(front1 + nn) % cap1]
-                != other._xs[(front2 + nn) % cap2]
-            ):
-                return False
-        return True
+        """
+        return '(|' + ', '.join(map(str, self)) + '|)'
 
-    def pushl(self, item: X) -> None:
+    def pushl(self, x: X) -> None:
         """
-        .. admonition:: Push left
+        .. admonition:: push left
 
             Push single item from the left onto the ``CAF``.
 
-        :param x: Single item to be pushed onto the front of the circular array from the left.
-        :raises ValueError: When called on a full fixed storage capacity circular array.
+            :param x: Single item to be pushed onto the front of
+                      the ``CAF`` from the left.
+            :raises ValueError: When called on a full fixed storage
+                                capacity circular array.
 
         """
         if self._cnt == self._cap:
@@ -238,18 +330,20 @@ class CAF[X]:
             self._cnt,
         ) = (
             (self._front - 1) % self._cap,
-            item,
+            x,
             self._cnt + 1,
         )
 
-    def pushr(self, item: X) -> None:
+    def pushr(self, x: X) -> None:
         """
-        .. admonition:: Push right
+        .. admonition:: push right
 
             Push single item from the right onto the ``CAF``.
 
-        :param x: Single item to be pushed onto the rear of the circular array from the right.
-        :raises ValueError: When called on a full fixed storage capacity circular array.
+            :param x: Single item to be pushed onto the rear of
+                      the ``CAF`` from the right.
+            :raises ValueError: When called on a full fixed
+                                storage capacity circular array.
 
         """
         if self._cnt == self._cap:
@@ -262,23 +356,23 @@ class CAF[X]:
             self._cnt,
         ) = (
             (self._rear + 1) % self._cap,
-            item,
+            x,
             self._cnt + 1,
         )
 
     def popl(self) -> X:
         """
-        .. admonition:: Pop left
+        .. admonition:: pop left
 
             Pop a single items off the left side of the ``CAF``.
 
-        :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 ``CAF``.
+            :raises ValueError: When called on an empty ``CAF``.
 
         """
         if self._cnt > 1:
             (
-                d,
+                x,
                 self._xs[self._front],
                 self._front,
                 self._cnt,
@@ -290,7 +384,7 @@ class CAF[X]:
             )
         elif self._cnt == 1:
             (
-                d,
+                x,
                 self._xs[self._front],
                 self._cnt,
                 self._front,
@@ -305,21 +399,21 @@ class CAF[X]:
         else:
             msg = 'Method popl called on an empty CAF'
             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 ``CAF``.
 
-        :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 ``CAF``.
+            :raises ValueError: When called on an empty ``CAF``.
 
         """
         if self._cnt > 1:
             (
-                d,
+                x,
                 self._xs[self._rear],
                 self._rear,
                 self._cnt,
@@ -331,7 +425,7 @@ class CAF[X]:
             )
         elif self._cnt == 1:
             (
-                d,
+                x,
                 self._xs[self._front],
                 self._cnt,
                 self._front,
@@ -346,18 +440,18 @@ class CAF[X]:
         else:
             msg = 'Method popr called on an empty CAF'
             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 ``CAF``.
 
-        :param default: Default value to return if ``CAF`` 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 ``CAF`` is empty.
+            :returns: Item popped from left side (front) of the ``CAF``
+                      if not empty, otherwise return the provided
+                      default value.
 
         """
         try:
@@ -367,14 +461,14 @@ class CAF[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 ``CAF``.
 
-        :param default: Default value to return if ``CAF`` 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 ``CAF`` is empty.
+            :returns: Item popped from right side (rear) of the ``CAF``
+                      if not empty, otherwise return the provided
+                      default value.
 
         """
         try:
@@ -388,21 +482,22 @@ class CAF[X]:
 
             Pop items off the left side of the ``CAF``.
 
-        :param maximum: Maximum number of items to pop, may pop less if not enough items in ``CAF``.
-        :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 ``CAF``.
+            :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, ...]:
         """
@@ -410,19 +505,20 @@ class CAF[X]:
 
             Pop items off the right side of the ``CAF``.
 
-        :param maximum: Maximum number of items to pop, may pop less if not enough items in ``CAF``.
-        :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 ``CAF``.
+            :returns: A ``tuple`` of the items popped, right to left.
 
         """
-        item_list: list[X] = []
+        xs: list[X] = []
         while maximum > 0:
             try:
-                item_list.append(self.popr())
+                xs.append(self.popr())
             except ValueError:
                 break
             else:
                 maximum -= 1
-        return tuple(item_list)
+        return tuple(xs)
 
     def rotl(self, n: int = 1) -> None:
         """
@@ -431,7 +527,8 @@ class CAF[X]:
             Rotate contents of ``CAF`` 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:
@@ -446,7 +543,8 @@ class CAF[X]:
             Rotate contents of ``CAF`` 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:
@@ -460,8 +558,8 @@ class CAF[X]:
 
             Apply function ``f`` over the circular array's contents.
 
-        :param f: Callable from type ``X`` to type ``Y``.
-        :returns: New fixed capacity circular array instance.
+            :param f: Callable from type ``X`` to type ``Y``.
+            :returns: New fixed capacity circular array instance.
 
         """
         return CAF(map(f, self), cap = self._cap)
@@ -477,10 +575,12 @@ class CAF[X]:
 
             Fold ``CAF`` 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:
@@ -496,8 +596,8 @@ class CAF[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
@@ -511,10 +611,12 @@ class CAF[X]:
 
             Fold ``CAF`` right left 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:
@@ -530,8 +632,8 @@ class CAF[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:
@@ -540,8 +642,7 @@ class CAF[X]:
 
             Get the fixed storage capacity of the circular array.
 
-
-        :returns: Fixed storage capacity.
+            :returns: Fixed storage capacity.
 
         """
         return self._cap
@@ -571,7 +672,7 @@ class CAF[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
@@ -581,11 +682,12 @@ def caf[T](*ts: T, cap: int = 2) -> CAF[T]:
     """
     .. admonition:: Circular array factory function
 
-        Produce a circular array from a variable number of arguments.
+        Produce a fixed capacity circular array from
+        a variable number of arguments.
 
-    :param ts: Initial items for a new fixed capacity circular array.
-    :param cap: The minimum storage capacity to set.
-    :returns: New fixed storage capacity circular array.
+        :param ts: Initial items for a new fixed capacity circular array.
+        :param cap: The minimum storage capacity to set.
+        :returns: New fixed storage capacity circular array.
 
     """
     return CAF(ts, cap=cap)

pythonic_fp/circulararray/fixed.pyi

@@ -5,16 +5,16 @@ __all__ = ['CAF', 'caf']
 
 class CAF[X]:
     def __init__(self, *xs: Iterable[X], cap: int = 2) -> 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]: ...
     def __getitem__(self, idx: int) -> X: ...
     def __setitem__(self, idx: int, val: X) -> None: ...
     def __delitem__(self, idx: int) -> None: ...
-    def __eq__(self, other: object) -> bool: ...
-    def pushl(self, item: X) -> None: ...
-    def pushr(self, item: X) -> None: ...
+    def pushl(self, x: X) -> None: ...
+    def pushr(self, x: X) -> None: ...
     def popl(self) -> X: ...
     def popr(self) -> X: ...
     def popld(self, default: X) -> X: ...