PyPI - pythonic-fp-circulararray - Versions diffs - 5.3.2__tar.gz → 5.3.3__tar.gz - Mend

pythonic-fp-circulararray 5.3.2tar.gz → 5.3.3tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (19) hide show

{pythonic_fp_circulararray-5.3.2 → pythonic_fp_circulararray-5.3.3}/CHANGELOG.rst RENAMED Viewed

@@ -1,9 +1,7 @@
 CHANGELOG
 =========
-Latest version of
-`PyPI pythonic-fp.circulararray project changelog
-<https://github.com/grscheller/pythonic-fp-circulararray/blob/main/README.rst>`_.
+PyPI pythonic-fp-circulararray project.
 Semantic Versioning
 -------------------
@@ -19,27 +17,30 @@ See `Semantic Versioning 2.0.0 <https://semver.org>`_.
 Releases and Important Milestones
 ---------------------------------
-5.3.2 - TBD
-~~~~~~~~~~~
+PyPI 5.3.3 - 2025-09-21
+~~~~~~~~~~~~~~~~~~~~~~~
+Polished up docstrings. PyPI documentation link now goes to root, not releases.
+PyPI 5.3.2 - 2025-09-04
+~~~~~~~~~~~~~~~~~~~~~~~
 - removed TypeVar declarations
 - removed Never from union return types
   - seems Never is now interpreted as a bottom
 - regenerated .pyi files with mypy's stubgen
 - updated docstrings for Sphinx documentation
-5.3.1 - 2025-08-02
-~~~~~~~~~~~~~~~~~~
+PyPI 5.3.1 - 2025-08-02
+~~~~~~~~~~~~~~~~~~~~~~~
 Added a second version of circulararray which has a fixed capacity.
 Also, significant docstring changes as the maintainer irons out
 how best to leverage Sphinx.
-5.2.0 - 2025-07-13
-~~~~~~~~~~~~~~~~~~
+PyPI 5.2.0 - 2025-07-13
+~~~~~~~~~~~~~~~~~~~~~~~
 API addition, removed position only parameters from API `/`
@@ -49,72 +50,63 @@ API addition, removed position only parameters from API `/`
   - pythonic_fp.circulararray docstrings still a bit rough
 - fixed broken PyPI links
-5.1.2 - 2025-07-06
-~~~~~~~~~~~~~~~~~~
+PyPI 5.1.2 - 2025-07-06
+~~~~~~~~~~~~~~~~~~~~~~~
 Documentation across pythonic-fp namespace projects brought closer into agreement.
-5.1.1 - 2025-07-06
-~~~~~~~~~~~~~~~~~~
+PyPI 5.1.1 - 2025-07-06
+~~~~~~~~~~~~~~~~~~~~~~~
 Devel environment and documentation changes only.
 - documentation improvements
 - forgot to updated changelog.rst before PyPI release
 - Pythonic FP homepage now points to its GitHub README.md
   - used to point to its GH-Pages
-5.1.0 - 2025-07-04
-~~~~~~~~~~~~~~~~~~
+PyPI 5.1.0 - 2025-07-04
+~~~~~~~~~~~~~~~~~~~~~~~
 First PyPI Release with Sphinx replacing pdoc.
 - switched from ``pdoc`` to ``sphinx`` for document generation
   - no longer source code controlling generated HTML (too wasteful)
   - using ``sphinx.ext.githubpages`` extension to publish from this repo
   - using ``sphinx.ext.autodoc`` to generate detailed API documentation
   - using the ``piccolo-theme at https://pypi.org/project/piccolo-theme/``
     - beautiful dark mode
     - plays nice with ``autodoc`` and ``DarkReader``
 - some formatting changes
   - no actual code changes
   - did remove TypeVar hack used for pdoc
 - made pyproject.toml improvements
   - better tooling configurations
   - removed all version caps from pyproject.toml, see this
     `blog post <https://iscinumpy.dev/post/bound-version-constraints>`_.
-5.0.0 - 2025-05-23
-~~~~~~~~~~~~~~~~~~
+PyPI 5.0.0 - 2025-05-23
+~~~~~~~~~~~~~~~~~~~~~~~
 First PyPI release as ``pythonic-fp.circular-array``.
 - there was already a PyPI project with the dtools name
 - the name pythonic-fp was not taken
   - using it as the namespace name for the entire group
   - does exist as an "skeleton" project just to claim the name
   - installing it will break all the namespace packages
   - didn't want any confusion caused by someone else claiming the name
-3.14.0 - 2025-05-10
-~~~~~~~~~~~~~~~~~~~
+PyPI 3.14.0 - 2025-05-10
+~~~~~~~~~~~~~~~~~~~~~~~~
 Made package just a single module.
 - dtools.circular_array.ca -> dtools.circular_array
 - docstring consolidations/updates
-3.13.0 - 2025-05-06
-~~~~~~~~~~~~~~~~~~~
+PyPI 3.13.0 - 2025-05-06
+~~~~~~~~~~~~~~~~~~~~~~~~
 Version no longer determined dynamically.
@@ -122,31 +114,28 @@ Version no longer determined dynamically.
 - version now set in pyproject.toml
 - no longer doing 4 part development versioning
 - version will either denote
   - the current PyPI release - if no substantive changes made
   - the next PyPI release - what development is working toward
-3.12.1 - 2025-04-22
-~~~~~~~~~~~~~~~~~~~
+PyPI 3.12.1 - 2025-04-22
+~~~~~~~~~~~~~~~~~~~~~~~~
-- docstring changes
-- pyproject.toml standardization
+Docstring changes and pyproject.toml standardization.
-3.12.0 - 2025-04-07
-~~~~~~~~~~~~~~~~~~~
+PyPI 3.12.0 - 2025-04-07
+~~~~~~~~~~~~~~~~~~~~~~~~
 API change.
 - class CA[D] no longer inherits from Sequence[D]
 - typing improvements
-3.11.0 - 2025-04-06
-~~~~~~~~~~~~~~~~~~~
+PyPI 3.11.0 - 2025-04-06
+~~~~~~~~~~~~~~~~~~~~~~~~
 Major API change.
 - swapped names `ca` and `CA`
   - class name now `CA`
   - factory function taking variable number of arguments is now `ca`
@@ -155,77 +144,65 @@ Major API change.
   - still want this class to behave like a builtin
   - but got tired fighting linters
   - maybe being "Pythonic" means
     - that only builtins should break naming conventions
     - naming conventions being
       - snake_case for functions and method names
       - CamelCase for class names
     - perhaps a visual distinction is useful to tell when you
       - are dealing with user/library Python code
       - C code presenting itself as a Python class
   - typing improvements
-3.10.1 - 2025-04-03
-~~~~~~~~~~~~~~~~~~~
+PyPI 3.10.1 - 2025-04-03
+~~~~~~~~~~~~~~~~~~~~~~~~
 Major API changes.
 - class name still `ca`
   - initializer takes 1 or 0 iterables
     - like Python builtin types `list` or `tuple`
   - factory function `CA` provided to create a `ca` from mult args
     - like `[]` or `{}`
 - otherwise, method names are all snake_case compatible
   - examples
     - popL -> popl
     - pushR -> pushr
     - fractionFilled -> fraction_filled
 - updated pyproject.toml
   - to better match other dtools namespace projects
-3.9.1 - 2025-02-16
-~~~~~~~~~~~~~~~~~~
+PyPI 3.9.1 - 2025-02-16
+~~~~~~~~~~~~~~~~~~~~~~~
 Fixed pdoc issues with new typing notation.
 - updated docstrings
 - had to add TypeVars
-3.9.0 - 2025-01-16
-~~~~~~~~~~~~~~~~~~
+PyPI 3.9.0 - 2025-01-16
+~~~~~~~~~~~~~~~~~~~~~~~
 First release as dtools.circular-array,
 was previously grscheller.circular-array.
-3.8.0 - 2025-01-03
-~~~~~~~~~~~~~~~~~~
+PyPI 3.8.0 - 2025-01-03
+~~~~~~~~~~~~~~~~~~~~~~~
 Now circular-array indexing methods fully support slicing, also added
 the rotL(n) and rotR(n) methods.
-3.7.1 - 2024-11-18
-~~~~~~~~~~~~~~~~~~
+PyPI 3.7.1 - 2024-11-18
+~~~~~~~~~~~~~~~~~~~~~~~
 For internal changes. Mostly for consistency across PyPI namespace projects
-3.7.0 - 2024-10-26
-~~~~~~~~~~~~~~~~~~
+PyPI 3.7.0 - 2024-10-26
+~~~~~~~~~~~~~~~~~~~~~~~
 Regenerated docs for PyPI release.
-3.6.3.2 - 2024-10-20
-~~~~~~~~~~~~~~~~~~~~
+Version 3.6.3.2 - 2024-10-20
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Just a commit, preparing for a 3.7.0 PyPI release.
@@ -233,20 +210,20 @@ Just a commit, preparing for a 3.7.0 PyPI release.
 - created factory function for original constructor use case
 - generated docs in docs repo
-3.6.2 - 2024-10-20
-~~~~~~~~~~~~~~~~~~
+PyPI 3.6.2 - 2024-10-20
+~~~~~~~~~~~~~~~~~~~~~~~
 Removed docs from repo, now docs for all grscheller namespace projects located
 [here](https://grscheller.github.io/grscheller-pypi-namespace-docs/).
-3.6.1 - 2024-10-18
-~~~~~~~~~~~~~~~~~~
+PyPI 3.6.1 - 2024-10-18
+~~~~~~~~~~~~~~~~~~~~~~~
 Infrastructure and minor docstring changes. Should be compatible with
 version 3.6.0.
-3.6.0 - 2024-09-21
-~~~~~~~~~~~~~~~~~~
+PyPI 3.6.0 - 2024-09-21
+~~~~~~~~~~~~~~~~~~~~~~~
 No future changes planned for the foreseeable future
@@ -257,8 +234,8 @@ No future changes planned for the foreseeable future
 - several more pytest tests added
 - made the `compact` method private, now called `_compact_storage_capacity`
-3.5.0 - 2024-09-21
-~~~~~~~~~~~~~~~~~~
+PyPI 3.5.0 - 2024-09-21
+~~~~~~~~~~~~~~~~~~~~~~~
 - made the `double` method
 - O(1) amortized pushes and pops either end.
@@ -268,33 +245,30 @@ No future changes planned for the foreseeable future
 - major docstring improvements
 - improved indentation and code alignment, now much more Pythonic
-3.4.1 - 2024-08-17
-~~~~~~~~~~~~~~~~~~
+PyPI 3.4.1 - 2024-08-17
+~~~~~~~~~~~~~~~~~~~~~~~
 - updated README.md to reflect name changes of CA methods
 - docstring improvements
-3.4.0 - 2024-08-15
-~~~~~~~~~~~~~~~~~~
+PyPI 3.4.0 - 2024-08-15
+~~~~~~~~~~~~~~~~~~~~~~~
 Updated `__eq__` comparisons.
 - first compare elements by identity before equality
   - I noticed that is what Python builtins do
   - makes dealing with grscheller.fp.nada module easier
 - standardizing docstrings across grscheller PyPI projects
-3.3.0.1 - 2024-08-05
-~~~~~~~~~~~~~~~~~~~~
+Version 3.3.0.1 - 2024-08-05
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Just a commit, made a paradigm "regression".
 - made a paradigm "regression", preparing for a 3.4.0 release
 - felt CA was becoming way too complicated
 - grscheller.datastructures needed it to fully embrace type annotations
   - but I was shifting too many features back into grscheller.circular-array
   - want ca to be useful for non-functional applications
@@ -308,34 +282,29 @@ The changes made were
 - changed nomenclature from "left/right" to "front/rear"
 - unsafe and safe versions of pop & fold functionality
 - left and right folds improvements
   - consolidated `foldL, foldL1, foldR, foldR1` into `foldL` & `foldR`
 - tests working
   - basically I changed pops to unsafe pops and added `try except` blocks
   - safe versions tests needed
     - safe pops return multiple values in tuples
     - will take a `default` value to return
       - if only asked to return 1 value and CA is empty
       - seems to work properly from iPython
-3.2.0 - 2024-07-26
-~~~~~~~~~~~~~~~~~~
+PyPI 3.2.0 - 2024-07-26
+~~~~~~~~~~~~~~~~~~~~~~~
 The class name was changed ``CircularArray -> CA`` Now takes a "sentinel" or "fallback" value in its
 initializer, formally used ``None`` for this.
-3.1.0 - 2024-07-11
-~~~~~~~~~~~~~~~~~~
+PyPI 3.1.0 - 2024-07-11
+~~~~~~~~~~~~~~~~~~~~~~~
 Generic typing now being used, first PyPI release where multiple values can be
 pushed on CircularArray.
-3.0.0 - 2024-06-28
-~~~~~~~~~~~~~~~~~~
+Version 3.0.0 - 2024-06-28
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 Just a commit, not a PyPI release.
 CircularArray class now using Generic Type Parameter. new epoch in development,
@@ -348,8 +317,8 @@ API changes:
 - ``foldL1(self, f: Callable[[S, T], S], initial: S) -> S``
 - ``foldR1(self, f: Callable[[T, S], S], initial: S) -> S``
-2.0.0 - 2024-03-08
-~~~~~~~~~~~~~~~~~~
+PyPI 2.0.0 - 2024-03-08
+~~~~~~~~~~~~~~~~~~~~~~~
 New "epoch" due to resizing bug fixed on previous commit.
@@ -358,59 +327,56 @@ New "epoch" due to resizing bug fixed on previous commit.
 - method `_double()` made "public" and renamed `double()`
 - method `resize(new_size)` now resizes to at least new_size
-1.1.0.0 - 2024-03-08
-~~~~~~~~~~~~~~~~~~~~
+Version 1.1.0.0 - 2024-03-08
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Just a commit to prepare for PyPI release 2.0.0!!!
 - BUGFIX: Fixed a subtle resizing bug
   - bug probably present in all previous versions
   - not previously identified due to inadequate test coverage
   - test coverage improved vastly
 - made some major code API changes
   - upon initialization minimizing size of the CircularArray
   - have some ideas on how to improve API for resizing CircularArrays
   - need to test my other 2 PyPI projects, both use circular-array as a dependency
-1.0.1 - 2024-03-01
-~~~~~~~~~~~~~~~~~~
+PyPI 1.0.1 - 2024-03-01
+~~~~~~~~~~~~~~~~~~~~~~~
 Docstring updates to match other grscheller PyPI repos.
-1.0.0 - 2024-02-10
-~~~~~~~~~~~~~~~~~~
+PyPI 1.0.0 - 2024-02-10
+~~~~~~~~~~~~~~~~~~~~~~~
 First stable PyPI release, dropped minimum Python requirement to 3.10.
-0.1.1 - 2024-01-30
-~~~~~~~~~~~~~~~~~~
+PyPI 0.1.1 - 2024-01-30
+~~~~~~~~~~~~~~~~~~~~~~~
 Changed circular-array from a package to just a module, actually a breaking API
 change. Version number should have been 0.2.0 Also, gave CircularArray class
 `foldL` & `foldR` methods.
-0.1.0 - 2024-01-28
-~~~~~~~~~~~~~~~~~~
+PyPI 0.1.0 - 2024-01-28
+~~~~~~~~~~~~~~~~~~~~~~~
 - initial PyPI grscheller.circular-array release
 - migrated Circulararray class from grscheller.datastructures
 - update docstrings to reflect current nomenclature
-0.0.3 - 2024-01-28
-~~~~~~~~~~~~~~~~~~
+Version 0.0.3 - 2024-01-28
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 Got gh-pages working for the repo.
-0.0.2 - 2024-01-28
-~~~~~~~~~~~~~~~~~~
+Version 0.0.2 - 2024-01-28
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 Pushed repo up to GitHub, created README.md file for project.
-0.0.1 - 2024-01-28
-~~~~~~~~~~~~~~~~~~
+Version 0.0.1 - 2024-01-28
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 Decided to split Circulararray class out of grscheller.datastructures, will make it its own PyPI
 project. Got it working with datastructures locally.

{pythonic_fp_circulararray-5.3.2 → pythonic_fp_circulararray-5.3.3}/PKG-INFO RENAMED Viewed

@@ -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.2 → pythonic_fp_circulararray-5.3.3}/pyproject.toml RENAMED Viewed

@@ -1,6 +1,6 @@
 [project]
 name = "pythonic-fp-circulararray"
-version = "5.3.2"
+version = "5.3.3"
 readme = "README.rst"
 requires-python = ">=3.13"
 license = { file = "LICENSE" }
@@ -28,7 +28,7 @@ dynamic = ["description"]
 [project.urls]
 Changelog = "https://github.com/grscheller/pythonic-fp-circulararray/blob/main/CHANGELOG.rst"
-Documentation = "https://grscheller.github.io/pythonic-fp/circulararray/development/build/html/releases.html"
+Documentation = "https://grscheller.github.io/pythonic-fp/circulararray/development/build/html/index.html"
 Homepage = "https://github.com/grscheller/pythonic-fp/blob/main/README.md"
 Source = "https://github.com/grscheller/pythonic-fp-circulararray"

{pythonic_fp_circulararray-5.3.2 → pythonic_fp_circulararray-5.3.3}/src/pythonic_fp/circulararray/__init__.py RENAMED Viewed

@@ -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-5.3.2 → pythonic_fp_circulararray-5.3.3}/src/pythonic_fp/circulararray/auto.py RENAMED Viewed

@@ -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-5.3.2 → pythonic_fp_circulararray-5.3.3}/src/pythonic_fp/circulararray/fixed.py RENAMED Viewed

@@ -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)