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

pythonic_fp/circulararray/fixed.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__ = ['CAF', 'caf']
@@ -22,28 +23,33 @@ 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
+        - iterable (see __iter__ method below)
         - 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
+        - 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: Takes 0 or 1 iterable parameters to initially
-                   populate the ``CAF`` left (front) to right (back).
-        :param cap: Minimum fixed storage capacity of circular array.
-        :raises ValueError: When more than one iterable is provided.
-        :raises TypeError: When passed a non-iterable positional parameter.
+        .. admonition:: initializer
+
+            Populate ``CAF`` 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.
 
         """
         cap = max(2, cap)
@@ -68,61 +74,48 @@ class CAF[X]:
             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:
+    def __iter__(self) -> Iterator[X]:
         """
-        .. admonition:: Equality comparison
+        .. admonition:: iterate
 
-            Efficiently compare ``CAF`` to another object.
+            Iterates circular array, left (front) to right (rear).
 
-        :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``.
+            :yields: The ``CA`` contents front to rear.
 
-        """
-        if self is other:
-            return True
-        if not isinstance(other, type(self)):
-            return False
+            .. warning::
 
-        (
-            front1,
-            cnt1,
-            cap1,
-            front2,
-            cnt2,
-            cap2,
-        ) = (
-            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) % cap1]
-                is other._xs[(front2 + nn) % cap2]
-            ):
-                continue
-            if (
-                self._xs[(front1 + nn) % cap1]
-                != other._xs[(front2 + nn) % cap2]
-            ):
-                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:
             (
                 cap,
@@ -142,6 +135,24 @@ class CAF[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 ``CAF`` contents rear to front.
+
+            .. 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,
@@ -160,7 +171,57 @@ class CAF[X]:
                 position = (position - 1) % cap
             yield cast(X, current_state[position])
 
+    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 __getitem__(self, idx: int) -> X:
+        """
+        .. admonition:: getitem
+
+            Fixed capacity circular arrays are indexable but
+            not sliceable.
+
+        """
         cnt = self._cnt
         if 0 <= idx < cnt:
             return cast(X, self._xs[(self._front + idx) % self._cap])
@@ -178,6 +239,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
@@ -193,9 +261,16 @@ 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)
+        _ca = CAF(item_list, cap=self._cap)
         (
             self._xs,
             self._cnt,
@@ -211,38 +286,37 @@ class CAF[X]:
 
     def __repr__(self) -> str:
         """
-        .. admonition:: String representation
+        .. admonition:: repr string
 
-            Return 'CAF("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 'CAF(x₁, x₂, … xₙ)' where
+            x₁, x₂, … xₙ are the contents displayed with ``repr()``.
 
-        :returns: A string to reproduce the ``CAF``.
+            :returns: A string to reproduce the ``CAF``.
 
         """
         return 'caf(' + ', '.join(map(repr, self)) + ')'
 
     def __str__(self) -> str:
         r"""
-        .. admonition:: User string
-
-            Return '(\|x1, x2, ..., xn\|)'
-            where x1, x2, ..., xn are the circular array's
-            contents displayed as strings.
+        .. admonition:: user string
+            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, 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:
@@ -261,12 +335,14 @@ class CAF[X]:
 
     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:
@@ -285,12 +361,12 @@ class CAF[X]:
 
     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:
@@ -326,12 +402,12 @@ class CAF[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:
@@ -367,14 +443,14 @@ class CAF[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:
@@ -384,14 +460,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:
@@ -405,8 +481,9 @@ 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.
 
         """
         xs: list[X] = []
@@ -427,8 +504,9 @@ 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.
 
         """
         xs: list[X] = []
@@ -448,7 +526,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:
@@ -463,7 +542,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:
@@ -477,11 +557,11 @@ 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)
+        return CAF(map(f, self), cap=self._cap)
 
     @overload
     def foldl[L](self, f: Callable[[X, X], X]) -> X: ...
@@ -494,10 +574,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:
@@ -528,10 +610,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:
@@ -557,8 +641,7 @@ class CAF[X]:
 
             Get the fixed storage capacity of the circular array.
 
-
-        :returns: Fixed storage capacity.
+            :returns: Fixed storage capacity.
 
         """
         return self._cap
@@ -588,7 +671,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
@@ -598,11 +681,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 __iter__(self) -> Iterator[X]: ...
+    def __reversed__(self) -> Iterator[X]: ...
+    def __eq__(self, other: object) -> bool: ...
     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: ...

{pythonic_fp_circulararray-6.1.0.dist-info → pythonic_fp_circulararray-6.2.0.dist-info}/METADATA

@@ -1,38 +1,39 @@
 Metadata-Version: 2.4
 Name: pythonic-fp-circulararray
-Version: 6.1.0
-Summary: Circular Array
+Version: 6.2.0
+Summary: Circular array datastructures.
 Keywords: auto resizing,circular array,circulararray,dequeue,indexable,pop,push
 Author-email: "Geoffrey R. Scheller" <geoffrey@scheller.com>
-Requires-Python: >=3.13
-Description-Content-Type: text/x-rst
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Framework :: Pytest
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Typing :: Typed
 License-File: LICENSE
 Requires-Dist: pythonic-fp-gadgets>=4.0.2
-Requires-Dist: pytest>=8.4.1 ; extra == "test"
-Project-URL: Changelog, https://github.com/grscheller/pythonic-fp-circulararray/blob/main/CHANGELOG.rst
-Project-URL: Documentation, https://grscheller.github.io/pythonic-fp/projects/circulararray.html
+Project-URL: Changelog, https://github.com/grscheller/pythonic-fp-circulararray/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://grscheller.github.io/pythonic-fp-circulararray/release/html/
 Project-URL: Homepage, https://grscheller.github.io/pythonic-fp/
 Project-URL: Source, https://github.com/grscheller/pythonic-fp-circulararray
-Provides-Extra: test
 
-Pythonic FP - Circular Array
-============================
+# Pythonic FP - Circular Array
+
+Stateful circular array data structures.
 
 PyPI project
-`pythonic-fp-circulararray
-<https://pypi.org/project/pythonic-fp-circulararray>`_.
+[pythonic-fp-circulararray](https://pypi.org/project/pythonic-fp-circulararray).
+Part of the
+[pythonic-fp](https://grscheller.github.io/pythonic-fp/)
+PyPI projects.
 
-Python module implementing stateful circular array data structures.
+## Description
 
 - variable storage capacity circular array
-
   - O(1) pops either end 
   - O(1) amortized pushes either end 
   - O(1) indexing, fully supports slicing
@@ -41,9 +42,7 @@ Python module implementing stateful circular array data structures.
   - comparisons compare identity before equality, like builtins
   - in boolean context, falsy when empty, otherwise truthy
   - function ``ca`` produces auto-resizing circular array from arguments
-
 - fixed storage capacity circular array
-
   - O(1) pops and pushes either end 
   - O(1) indexing, does not support slicing
   - fixed total storage capacity
@@ -52,20 +51,7 @@ Python module implementing stateful circular array data structures.
   - in boolean context, falsy when either empty or full, otherwise truthy
   - function ``caf`` produces fixed capacity circular array from arguments
 
-Part of the
-`pythonic-fp
-<https://grscheller.github.io/pythonic-fp/>`_
-PyPI projects.
-
-Documentation
--------------
-
-Documentation and other links for this project are hosted on
-`GitHub Pages
-<https://grscheller.github.io/pythonic-fp/projects/circulararray.html>`_.
-
-Copyright and License
----------------------
+## Copyright and License
 
 Copyright (c) 2023-2026 Geoffrey R. Scheller. Licensed under the Apache
 License, Version 2.0. See the LICENSE file for details.