pythonic-fp-circulararray 6.1.0__py3-none-any.whl → 6.2.0__py3-none-any.whl

pythonic_fp/circulararray/auto.py

@@ -13,7 +13,8 @@
 # limitations under the License.
 
 from collections.abc import Callable, Iterable, Iterator
-from typing import cast, Final, overload
+from typing import Final, cast, overload
+
 from pythonic_fp.gadgets.sentinels.novalue import NoValue
 
 __all__ = ['CA', 'ca']
@@ -23,26 +24,33 @@ nada: Final[NoValue] = NoValue()
 
 class CA[X]:
     """
-    .. admonition:: Variable storage capacity circular array CA
+    .. 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
+        - auto-resizing more storage capacity when necessary,
+          manually compatible
+        - iterable (see __iter__ method below)
         - comparisons compare identity before equality, like builtins
         - in boolean context, falsy when empty, otherwise truthy
-        - function ``ca`` produces auto-resizing circular array from arguments
+        - function ``ca`` produces auto-resizing circular array
+          from arguments
 
     """
+
     __slots__ = '_xs', '_cnt', '_cap', '_front', '_rear'
 
     def __init__(self, *xs: Iterable[X]) -> None:
         """
-        :param xs: Takes 0 or 1 iterable parameters to initially
-                   populate the ``CA`` left (front) to right (back).
-        :raises ValueError: When more than one iterable is provided.
-        :raises TypeError: When passed a non-iterable parameter.
+        .. admonition:: initializer
+
+            Populate ``CA`` with an optional iterable
+            from front (left) to rear (right).
+
+            :param xs: Takes an optional iterable parameter.
+            :raises ValueError: When more than one parameter is provided.
+            :raises TypeError: When passed a non-iterable parameter.
 
         """
         if (size := len(xs)) > 1:
@@ -77,9 +85,7 @@ class CA[X]:
                 self._front,
                 self._cap,
             ) = (
-                self._xs[: self._front]
-                + [nada] * self._cap
-                + self._xs[self._front :],
+                self._xs[: self._front] + [nada] * self._cap + self._xs[self._front :],
                 self._front + self._cap,
                 2 * self._cap,
             )
@@ -140,61 +146,48 @@ class CA[X]:
                     )
 
     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:
+    def __iter__(self) -> Iterator[X]:
         """
-        .. admonition:: Equality comparison
+        .. admonition:: iterate
 
-            Efficiently compare ``CA`` to another object.
+            Iterates circular array, left (front) to right (rear).
 
-        :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``.
+            :yields: The ``CA`` contents front to rear.
 
-        """
-        if self is other:
-            return True
-        if not isinstance(other, type(self)):
-            return False
+            .. warning::
 
-        (
-            front1,
-            cnt1,
-            capacity1,
-            front2,
-            cnt2,
-            capacity2,
-        ) = (
-            self._front,
-            self._cnt,
-            self._cap,
-            other._front,
-            other._cnt,
-            other._cap,
-        )
+                Not threadsafe, especially for long living iterators.
 
-        if cnt1 != cnt2:
-            return False
+                .. tip::
 
-        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
+                    Cache contents to make more thread tolerant. Put
+                    a lock around circular array during caching process
+                    to make threadsafe.
 
-    def __iter__(self) -> Iterator[X]:
+        """
         if self._cnt > 0:
             (
                 capacity,
@@ -214,6 +207,24 @@ class CA[X]:
             yield cast(X, current_state[position])
 
     def __reversed__(self) -> Iterator[X]:
+        """
+        .. admonition:: reverse iterate
+
+            Iterates circular array, right (rear) to left (front).
+
+            :yields: The ``CA`` contents right to 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,
@@ -232,12 +243,68 @@ class CA[X]:
                 position = (position - 1) % capacity
             yield cast(X, current_state[position])
 
+    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
+
     @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])
 
@@ -263,6 +330,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)
@@ -306,6 +380,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)
@@ -326,38 +407,37 @@ class CA[X]:
 
     def __repr__(self) -> str:
         """
-        .. admonition:: String representation
+        .. admonition:: repr string
 
-            Return 'CA("repr(x1)", "repr(x2)", ..., "repr(xn)")'
-            where x1, x2, ..., xn are the circular array's
-            contents and "repr(xi)" is the repr-string for xi.
+            Construct string 'CA(x₁, x₂, … xₙ)' where
+            x₁, x₂, … xₙ are the contents displayed with ``repr()``.
 
-        :returns: A string to reproduce the ``CA``. 
+            :returns: A string to reproduce the ``CA``.
 
         """
         return 'ca(' + ', '.join(map(repr, self)) + ')'
 
     def __str__(self) -> str:
         r"""
-        .. admonition:: User string
+        .. admonition:: user string
 
-            Return string '(\| x1, x2, ..., xn \|)'
-            where x1, x2, ..., xn are the circular array's
-            contents displayed as strings.
+            Construct string '(\| x₁, x₂, … xₙ \|)' where
+            x₁, x₂, ..., xₙ are the contents displayed with ``str()``.
 
-        :returns: A string meaningful to an end user.
+            :returns: A string 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 x in xs:
@@ -375,12 +455,13 @@ class CA[X]:
 
     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:
@@ -398,12 +479,12 @@ 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:
@@ -439,12 +520,12 @@ class CA[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:
@@ -480,14 +561,14 @@ class CA[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:
@@ -497,14 +578,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:
@@ -518,8 +599,9 @@ 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.
 
         """
         xs: list[X] = []
@@ -540,8 +622,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] = []
@@ -561,7 +644,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:
@@ -576,7 +660,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:
@@ -590,8 +675,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))
@@ -607,10 +692,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:
@@ -641,10 +728,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:
@@ -670,7 +759,7 @@ class CA[X]:
 
             Get the current storage capacity of the circular array.
 
-        :returns: Current storage capacity.
+            :returns: Current storage capacity.
 
         """
         return self._cap
@@ -700,7 +789,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
@@ -713,7 +802,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()
@@ -733,10 +823,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 __iter__(self) -> Iterator[X]: ...
+    def __reversed__(self) -> Iterator[X]: ...
+    def __eq__(self, other: object) -> bool: ...
     @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: ...