pythonic-fp-circulararray 5.3.2__py3-none-any.whl → 5.3.3__py3-none-any.whl

pythonic_fp/circulararray/__init__.py

@@ -14,7 +14,7 @@
 
 """
 Circular Array
-==============
+--------------
 
 Package implementing stateful circular array data structures.
 
@@ -29,7 +29,6 @@ Package implementing stateful circular array data structures.
 +-------------------------------------+-------------------------------------------+
 | **pythonic_fp.circulararray.fixed** | Fixed storage capacity circular array.    |
 +-------------------------------------+-------------------------------------------+
-
 """
 
 __author__ = 'Geoffrey R. Scheller'

pythonic_fp/circulararray/auto.py

@@ -16,7 +16,7 @@
 Variable Storage Capacity
 =========================
 
-Circular array with variable storage capacity.
+**Circular array with variable storage capacity.**
 
 - O(1) pops either end 
 - O(1) amortized pushes either end 
@@ -25,7 +25,7 @@ Circular array with variable storage capacity.
 - iterable, can safely mutate while iterators continue iterating over previous state
 - comparisons compare identity before equality, like builtins
 - in boolean context, falsy when empty, otherwise truthy
-- factory function ca produces a variable storage capacity circular array from its arguments
+- factory function ``ca`` produces a variable storage capacity circular array from its arguments
 
 """
 from collections.abc import Callable, Iterable, Iterator
@@ -43,12 +43,8 @@ class CA[I]():
             items: Iterable[I] | None = None
         ) -> None:
         """
-        Basically a list that can be grown from both ends
-        in O(1) time and space complexity.
-
-        :param items: optional iterable to initial populate circular array
-        :raises TypeError: if items is not Iterable
-
+        :param items: Optional iterable to initial populate circular array.
+        :raises TypeError: When ``items`` not Iterable.
         """
         if items is None:
             self._items: list[I | None] = [None, None]
@@ -310,11 +306,9 @@ class CA[I]():
         return True
 
     def pushl(self, *items: I) -> None:
-        """
-        Push items onto left side (front) of circular array.
-
-        :param items: items pushed onto circular array from left
+        """Push ``items`` on from left.
 
+        :param items: Items pushed onto circular array from left (front).
         """
         for item in items:
             if self._cnt == self._cap:
@@ -330,11 +324,9 @@ class CA[I]():
                 )
 
     def pushr(self, *items: I) -> None:
-        """
-        Push items onto right side (rear) of circular array.
-
-        :param items: items pushed onto circular array from right
+        """Push ``items`` on from right.
 
+        :param items: Items pushed onto circular array from right (rear).
         """
         for item in items:
             if self._cnt == self._cap:
@@ -350,12 +342,10 @@ class CA[I]():
                 )
 
     def popl(self) -> I:
-        """
-        Pop item off left side (front) of circular array.
-
-        :returns: item popped from left side of circular array
-        :raises ValueError: when called on an empty circular array
+        """Pop single item off from left side.
 
+        :returns: Item popped from left side (front) of circular array.
+        :raises ValueError: When called on an empty circular array.
         """
         if self._cnt > 1:
             (
@@ -389,12 +379,10 @@ class CA[I]():
         return cast(I, d)
 
     def popr(self) -> I:
-        """
-        Pop item off right side (rear) of circular array.
-
-        :return: item popped from right side of circular array
-        :raises ValueError: when called on an empty circular array
+        """Pop single item off from right.
 
+        :returns: Item popped from right side (rear) of circular array.
+        :raises ValueError: When called on an empty circular array.
         """
         if self._cnt > 1:
             (
@@ -428,13 +416,11 @@ class CA[I]():
         return cast(I, d)
 
     def popld(self, default: I) -> I:
-        """
-        Pop one item from left side of the circular array, provide
-        a mandatory default value. "Safe" version of popl.
-
-        :param default: item returned if circular array is empty
-        :return: item popped from left side or default item if empty
+        """Pop one item from left side of the circular array, provide
+        a mandatory default value. "Safe" version of ``popl``.
 
+        :param default: Item returned if circular array is empty.
+        :returns: Item popped from left side or default item if empty.
         """
         try:
             return self.popl()
@@ -442,13 +428,11 @@ class CA[I]():
             return default
 
     def poprd(self, default: I) -> I:
-        """
-        Pop one item from right side of the circular array, provide
-        a mandatory default value. "Safe" version of popr.
-
-        :param default: item returned if circular array is empty
-        :return: item popped from right side or default item if empty
+        """Pop one item from right side of the circular array, provide
+        a mandatory default value. "Safe" version of ``popr``.
 
+        :param default: Item returned if circular array is empty.
+        :returns: Item popped from right side or default item if empty.
         """
         try:
             return self.popr()
@@ -456,12 +440,10 @@ class CA[I]():
             return default
 
     def poplt(self, maximum: int) -> tuple[I, ...]:
-        """
-        Pop multiple items from left side of circular array.
-
-        :param maximum: maximum number of items to pop, may pop less if not enough items
-        :return: items in the order popped, left to right
+        """Pop multiple items from left side of circular array.
 
+        :param maximum: Maximum number of items to pop, may pop less if not enough items.
+        :returns: Tuple of items in the order popped, left to right.
         """
         item_list: list[I] = []
 
@@ -476,12 +458,10 @@ class CA[I]():
         return tuple(item_list)
 
     def poprt(self, maximum: int) -> tuple[I, ...]:
-        """
-        Pop multiple items from right side of circular array.
-
-        :param maximum: maximum number of items to pop, may pop less if not enough items
-        :return: items in the order popped, right to left
+        """Pop multiple items from right side of circular array.
 
+        :param maximum: Maximum number of items to pop, may pop less if not enough items.
+        :returns: Tuple of items in the order popped, right to left.
         """
         item_list: list[I] = []
         while maximum > 0:
@@ -494,11 +474,9 @@ class CA[I]():
         return tuple(item_list)
 
     def rotl(self, n: int = 1) -> None:
-        """
-        Rotate items to the left.
-
-        :param n: number of times to shift elements to the left
+        """Rotate items to the left.
 
+        :param n: Number of times to shift elements to the left.
         """
         if self._cnt < 2:
             return
@@ -506,11 +484,9 @@ class CA[I]():
             self.pushr(self.popl())
 
     def rotr(self, n: int = 1) -> None:
-        """
-        Rotate items to the right.
-
-        :param n: number of times to shift elements to the right
+        """Rotate items to the right.
 
+        :param n: Number of times to shift elements to the right.
         """
         if self._cnt < 2:
             return
@@ -518,24 +494,20 @@ class CA[I]():
             self.pushl(self.popr())
 
     def map[U](self, f: Callable[[I], U]) -> "CA[U]":
-        """
-        Apply function f over the circular array's contents,
-
-        :param f: callable from type I to type U
-        :returns: new circular array instance
+        """Apply function ``f`` over the circular array's contents.
 
+        :param f: Callable from type ``I`` to type ``U``.
+        :returns: New auto-resizing circular array instance.
         """
         return CA(map(f, self))
 
     def foldl[L](self, f: Callable[[L, I], L], start: L | None = None) -> L:
-        """
-        Fold left with a function and optional starting item.
-
-        :param f: 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 no starting item given
+        """Fold 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 no starting item given.
         """
         if self._cnt == 0:
             if start is None:
@@ -555,14 +527,12 @@ class CA[I]():
         return acc
 
     def foldr[R](self, f: Callable[[I, R], R], start: R | None = None) -> R:
-        """
-        Fold right with a function and an optional starting item.
-
-        :param f: 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 no starting item given
+        """Fold right with a function and an 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 no starting item given.
         """
         if self._cnt == 0:
             if start is None:
@@ -582,17 +552,14 @@ class CA[I]():
         return acc
 
     def capacity(self) -> int:
-        """
-        Return current storage capacity of the circular array.
-
-        :returns: current storage capacity
+        """Return current storage capacity of the circular array.
 
+        :returns: Current storage capacity.
         """
         return self._cap
 
     def empty(self) -> None:
-        """
-        Empty the circular array, keep current storage capacity."""
+        """Empty the circular array, keep current storage capacity."""
         (
                 self._items,
                 self._front,
@@ -606,22 +573,18 @@ class CA[I]():
             )
 
     def fraction_filled(self) -> float:
-        """
-        Find fraction of the storage capacity which is filled.
-
-        :returns: the ratio count/capacity
+        """Find fraction of the storage capacity which is filled.
 
+        :returns: The ratio count/capacity.
         """
         return self._cnt / self._cap
 
     def resize(self, minimum_capacity: int = 2) -> None:
-        """
-        Compact circular array and, if necessary, resize to a minimum
+        """Compact circular array and, if necessary, resize to a 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()
         if (min_cap := minimum_capacity) > self._cap:
@@ -637,11 +600,9 @@ class CA[I]():
 
 
 def ca[T](*items: T) -> CA[T]:
-    """
-    Produce circular array from a variable number of arguments.
-
-    :param items: initial items for a new circular array
-    :returns: new variable storage capacity circular array
+    """Produce circular array from a variable number of arguments.
 
+    :param items: Initial items for a new auto-resizing circular array.
+    :returns: New variable storage capacity circular array.
     """
     return CA(items)

pythonic_fp/circulararray/fixed.py

@@ -16,7 +16,7 @@
 Fixed Storage Capacity
 ======================
 
-Circular array with fixed storage capacity.
+**Circular array with fixed storage capacity.**
 
 - O(1) pops and pushes either end 
 - O(1) indexing, does not support slicing
@@ -24,7 +24,7 @@ Circular array with fixed storage capacity.
 - iterable, can safely mutate while iterators continue iterating over previous state
 - comparisons compare identity before equality, like builtins
 - in boolean context, falsy when either empty or full, otherwise truthy
-- factory function caf produces a fixed storage capacity circular array from its arguments
+- factory function ``caf`` produces a fixed storage capacity circular array from its arguments
 
 """
 from collections.abc import Callable, Iterable, Iterator
@@ -43,13 +43,9 @@ class CAF[I]():
             capacity: int = 2
         ) -> None:
         """
-        Basically a list that can be grown from both ends
-        in O(1) time and space complexity.
-
-        :param items: optional iterable to initial populate circular array
-        :param capacity: fixed storage capacity of circular array
-        :raises TypeError: if items is not Iterable
-
+        :param items: Optional iterable to initial populate circular array.
+        :param capacity: Fixed storage capacity of circular array.
+        :raises TypeError: When ``items`` not Iterable,
         """
         capacity = max(2, capacity)
         if items is None:
@@ -201,12 +197,10 @@ class CAF[I]():
         return True
 
     def pushl(self, item: I) -> None:
-        """
-        Push single item onto left side (front) of circular array.
-
-        :param item: single item pushed onto circular array from left
-        :raises ValueError: when called on a full CAF
+        """Push ``item`` on from left.
 
+        :param item: Single item pushed onto circular array from left (front).
+        :raises ValueError: When called on a full ``CAF``.
         """
         if self._cnt == self._cap:
             msg = 'Method pushl called on a full CAF'
@@ -223,12 +217,10 @@ class CAF[I]():
             )
 
     def pushr(self, item: I) -> None:
-        """
-        Push a single item onto right side (rear) of circular array.
-
-        :param item: single item pushed onto circular array from right
-        :raises ValueError: when called on a full fixed storage capacity circular array
+        """Push ``item`` on from Right.
 
+        :param item: Single ``item`` pushed onto circular array from right (rear).
+        :raises ValueError: When called on a full fixed storage capacity circular array.
         """
         if self._cnt == self._cap:
             msg = 'Method pushr called on a full CAF'
@@ -245,12 +237,10 @@ class CAF[I]():
             )
 
     def popl(self) -> I:
-        """
-        Pop item off left side (front) of circular array.
-
-        :returns: item popped from left side of circular array
-        :raises ValueError: when called on an empty circular array
+        """Pop single item off from left side.
 
+        :returns: Item popped from left side (front) of circular array.
+        :raises ValueError: When called on an empty circular array.
         """
         if self._cnt > 1:
             (
@@ -284,12 +274,10 @@ class CAF[I]():
         return cast(I, d)
 
     def popr(self) -> I:
-        """
-        Pop item off right side (rear) of circular array.
-
-        :returns: item popped from right side of circular array
-        :raises ValueError: when called on an empty circular array
+        """Pop single item off from right side.
 
+        :returns: Item popped from right side (rear) of circular array.
+        :raises ValueError: When called on an empty circular array.
         """
         if self._cnt > 1:
             (
@@ -323,13 +311,11 @@ class CAF[I]():
         return cast(I, d)
 
     def popld(self, default: I) -> I:
-        """
-        Pop one item from left side of the circular array, provide
+        """Pop one item from left side of the circular array, provide
         a mandatory default value. "Safe" version of popl.
 
-        :param default: item returned if circular array is empty
-        :returns: item popped from left side or default item if empty
-
+        :param default: Item returned if circular array is empty.
+        :returns: Item popped from left side or default item if empty.
         """
         try:
             return self.popl()
@@ -337,13 +323,11 @@ class CAF[I]():
             return default
 
     def poprd(self, default: I) -> I:
-        """
-        Pop one item from right side of the circular array, provide
+        """Pop one item from right side of the circular array, provide
         a mandatory default value. "Safe" version of popr.
 
-        :param default: item returned if circular array is empty
-        :returns: item popped from right side or default item if empty
-
+        :param default: Item returned if circular array is empty.
+        :returns: Item popped from right side or default item if empty.
         """
         try:
             return self.popr()
@@ -351,12 +335,10 @@ class CAF[I]():
             return default
 
     def poplt(self, maximum: int) -> tuple[I, ...]:
-        """
-        Pop multiple items from left side of circular array.
-
-        :param maximum: maximum number of items to pop, may pop less if not enough items
-        :returns: items in the order popped, left to right
+        """Pop multiple items from left side of circular array.
 
+        :param maximum: Maximum number of items to pop, may pop less if not enough items.
+        :returns: Tuple of items in the order popped, left to right.
         """
         item_list: list[I] = []
 
@@ -371,12 +353,10 @@ class CAF[I]():
         return tuple(item_list)
 
     def poprt(self, maximum: int) -> tuple[I, ...]:
-        """
-        Pop multiple items from right side of circular array.
-
-        :param maximum: maximum number of items to pop, may pop less if not enough items
-        :returns: items in the order popped, right to left
+        """Pop multiple items from right side of circular array.
 
+        :param maximum: Maximum number of items to pop, may pop less if not enough items.
+        :returns: Tuple of items in the order popped, right to left.
         """
         item_list: list[I] = []
         while maximum > 0:
@@ -389,11 +369,9 @@ class CAF[I]():
         return tuple(item_list)
 
     def rotl(self, n: int = 1) -> None:
-        """
-        Rotate items to the left.
-
-        :param n: number of times to shift elements to the left
+        """Rotate items to the left.
 
+        :param n: Number of times to shift elements to the left.
         """
         if self._cnt < 2:
             return
@@ -401,11 +379,9 @@ class CAF[I]():
             self.pushr(self.popl())
 
     def rotr(self, n: int = 1) -> None:
-        """
-        Rotate items to the right.
-
-        :param n: number of times to shift elements to the right
+        """Rotate items to the right.
 
+        :param n: Number of times to shift elements to the right.
         """
         if self._cnt < 2:
             return
@@ -413,24 +389,20 @@ class CAF[I]():
             self.pushl(self.popr())
 
     def map[U](self, f: Callable[[I], U]) -> "CAF[U]":
-        """
-        Apply function ``f`` over the circular array's contents,
-
-        :param f: callable from type I to type U
-        :returns: new fixed circular array instance
+        """Apply function ``f`` over the circular array's contents,
 
+        :param f: Callable from type ``I`` to type ``U``.
+        :returns: New fixed capacity circular array instance.
         """
         return CAF(map(f, self), self._cap)
 
     def foldl[L](self, f: Callable[[L, I], L], start: L | None = None) -> L:
-        """
-        Fold left with a function and optional stating item.
-
-        :param f: 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 no starting item given
+        """Fold left with a function and optional stating 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 no starting item given.
         """
         if self._cnt == 0:
             if start is None:
@@ -450,14 +422,12 @@ class CAF[I]():
         return acc
 
     def foldr[R](self, f: Callable[[I, R], R], start: R | None = None) -> R:
-        """
-        Fold right with a function and an optional starting item.
-
-        :param f: 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 no starting item given
+        """Fold right with a function and an 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 no starting item given.
         """
         if self._cnt == 0:
             if start is None:
@@ -477,17 +447,14 @@ class CAF[I]():
         return acc
 
     def capacity(self) -> int:
-        """
-        Return fixed storage capacity of the circular array.
-
-        :returns: fixed storage capacity
+        """Return fixed storage capacity of the circular array.
 
+        :returns: Fixed storage capacity.
         """
         return self._cap
 
     def empty(self) -> None:
-        """
-        Empty the circular array."""
+        """Empty the circular array."""
         (
                 self._items,
                 self._front,
@@ -501,22 +468,18 @@ class CAF[I]():
             )
 
     def fraction_filled(self) -> float:
-        """
-        Find fraction of the storage capacity which is filled.
-
-        :returns: the ratio count/capacity
+        """Find fraction of the storage capacity which is filled.
 
+        :returns: The ratio count/capacity.
         """
         return self._cnt / self._cap
 
 
 def caf[T](*items: T, capacity: int = 2) -> CAF[T]:
-    """
-    Produce a circular array from a variable number of arguments.
-
-    :param items: initial items for a new circular array
-    :param capacity: the minimum storage capacity to set
-    :returns: new fixed storage capacity circular array
+    """Produce a circular array from a variable number of arguments.
 
+    :param items: Initial items for a new fixed capacity :circular array.
+    :param capacity: The minimum storage capacity to set.
+    :returns: New fixed storage capacity circular array.
     """
     return CAF(items, capacity = capacity)

{pythonic_fp_circulararray-5.3.2.dist-info → pythonic_fp_circulararray-5.3.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythonic-fp-circulararray
-Version: 5.3.2
+Version: 5.3.3
 Summary: Circular Array
 Keywords: auto resizing,circular array,circulararray,dequeue,indexable,pop,push
 Author-email: "Geoffrey R. Scheller" <geoffrey@scheller.com>
@@ -16,7 +16,7 @@ Classifier: Typing :: Typed
 License-File: LICENSE
 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/circulararray/development/build/html/releases.html
+Project-URL: Documentation, https://grscheller.github.io/pythonic-fp/circulararray/development/build/html/index.html
 Project-URL: Homepage, https://github.com/grscheller/pythonic-fp/blob/main/README.md
 Project-URL: Source, https://github.com/grscheller/pythonic-fp-circulararray
 Provides-Extra: test

pythonic_fp_circulararray-5.3.3.dist-info/RECORD

@@ -0,0 +1,11 @@
+pythonic_fp/circulararray/__init__.py,sha256=uR0KASmw1Zraz9l3VPbqPm9WUKzWk-0_tUGT0opabzQ,1515
+pythonic_fp/circulararray/__init__.pyi,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pythonic_fp/circulararray/auto.py,sha256=_rZhOsC3PGs97j15qM4vXpkpRDTfVkxEGwYyBi9uAQU,19334
+pythonic_fp/circulararray/auto.pyi,sha256=yfQ2kzIiXFb2Bpg3cMwHwv2oSlyOUMTgmdPZM_-oU_8,1669
+pythonic_fp/circulararray/fixed.py,sha256=nzwPnaVOh-KKv503_c--f_m0SkOaUI6mSe1Bo5WACCA,15316
+pythonic_fp/circulararray/fixed.pyi,sha256=y_7eMvH18B1lpLPp2P-VkN-xcQVKJn6cOisp9LSBBRk,1362
+pythonic_fp/circulararray/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pythonic_fp_circulararray-5.3.3.dist-info/licenses/LICENSE,sha256=psuoW8kuDP96RQsdhzwOqi6fyWv0ct8CR6Jr7He_P_k,10173
+pythonic_fp_circulararray-5.3.3.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+pythonic_fp_circulararray-5.3.3.dist-info/METADATA,sha256=rdgGmosD6wF1Cfye7QBuZJXGnjs3uDgPzmYYvVpUx-M,2180
+pythonic_fp_circulararray-5.3.3.dist-info/RECORD,,

pythonic_fp_circulararray-5.3.2.dist-info/RECORD

@@ -1,10 +0,0 @@
-pythonic_fp/circulararray/__init__.py,sha256=4RaMexsQxHwp80j3Z75_td8PGRqLoz1yMvK_ZZ07vi8,1516
-pythonic_fp/circulararray/auto.py,sha256=YIBKvnjerpCg8hmcAS-HSSjGRZSD4C7S_RyCNH4FwoE,19502
-pythonic_fp/circulararray/auto.pyi,sha256=yfQ2kzIiXFb2Bpg3cMwHwv2oSlyOUMTgmdPZM_-oU_8,1669
-pythonic_fp/circulararray/fixed.py,sha256=G58qee_2Rl9e-4hG3vZrQIJTDbpqoECpT-d2M98BcgY,15494
-pythonic_fp/circulararray/fixed.pyi,sha256=y_7eMvH18B1lpLPp2P-VkN-xcQVKJn6cOisp9LSBBRk,1362
-pythonic_fp/circulararray/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pythonic_fp_circulararray-5.3.2.dist-info/licenses/LICENSE,sha256=psuoW8kuDP96RQsdhzwOqi6fyWv0ct8CR6Jr7He_P_k,10173
-pythonic_fp_circulararray-5.3.2.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
-pythonic_fp_circulararray-5.3.2.dist-info/METADATA,sha256=DJnFE-yTJU7yhdQNjXA4lTc4tsWWp1zULxsBlN5e46w,2183
-pythonic_fp_circulararray-5.3.2.dist-info/RECORD,,