dtools.circular-array 3.9.1__tar.gz → 3.11.0__tar.gz

dtools_circular_array-3.11.0/CHANGELOG.md

@@ -0,0 +1,234 @@
+# CHANGELOG
+
+PyPI grscheller.circular-array project.
+
+- first digit - major event, epoch, or paradigm shift
+- second digit - breaking API changes, major changes
+- third digit - bug fixes, API additions, breaking API in dev env
+- forth digit - commit count changes/regressions (dev environment only)
+
+## Releases and Important Milestones
+
+### Version 3.11.0 - PyPI release date 2025-04-TBD
+
+- Major API change 
+  - swapped names `ca` and `CA`
+    - class name now `CA`
+    - factory function taking variable number of arguments is now `ca`
+  - class initializer still takes `1` or `0` iterables
+    - 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
+  
+### Version 3.10.1 - PyPI release date 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
+
+### Version 3.9.1 - PyPI release date 2025-02-16
+
+- Fixed pdoc issues with new typing notation
+  - updated docstrings
+  - had to add TypeVars
+
+### Version 3.9.0 - PyPI release date 2025-01-16
+
+- Final release as dtools.circular-array
+  - was previously grscheller.circular-array
+
+### Version 3.8.0 - PyPI release date 2025-01-03
+
+- now circular-array indexing methods fully support slicing
+  - `__getitem__`
+  - `__setitem__`
+  - `__delitem__`
+- added rotL(n) and rotR(n) methods
+
+### Version 3.7.1 - PyPI release date 2024-11-18
+
+- for internal changes
+  - mostly for consistency across PyPI namespace projects
+
+### Version 3.7.0 - PyPI release date 2024-10-26
+
+- regenerated docs for PyPI release
+
+### Version 3.6.3.2 - Commit date 2024-10-20
+
+- preparing for a 3.7.0 PyPI release
+  - renamed class ca -> CA
+    - ca now takes 0 or 1 iterables
+  - created factory function for original constructor use case
+    - `CA[D](*ds: D) -> ca[D]`
+- generated docs in docs repo - 2024-10-23
+
+### Version 3.6.2 - PyPI release date 2024-10-20
+
+- removed docs from repo
+- docs for all grscheller namespace projects located
+  [here](https://grscheller.github.io/grscheller-pypi-namespace-docs/).
+
+### Version 3.6.1 - PyPI release date 2024-10-18
+
+- infrastructure and minor docstring changes
+  - should be compatible with version 3.6.0
+
+### Version 3.6.0 - PyPI release date 2024-09-21
+
+- no future changes planned for the foreseeable future
+  - feature complete
+  - no external dependencies
+  - well tested with other grscheller namespace packages
+- final API tweaks made
+- several more pytest tests added
+- made the `compact` method private
+  - now called `_compact_storage_capacity`
+
+### Version 3.5.0 - PyPI release date 2024-09-21
+
+- made the `double` method private
+  - now called `_double_storage_capacity`
+- major docstring improvements
+- improved indentation and code alignment
+  - now much more Pythonic
+
+### Version 3.4.1 - PyPI release date 2024-08-17
+
+- updated README.md to reflect name changes of CA methods
+- docstring improvements
+
+### Version 3.4.0 - PyPI release date 2024-08-15
+
+- updated `__eq__` comparisons
+  - first compare elements by identity before equality
+    - noticed that is what Python builtins do
+    - makes dealing with grscheller.fp.nada module easier
+- standardizing docstrings across grscheller PyPI projects
+
+### Version 3.3.0.1 - commit date 2024-08-05
+
+- 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
+- changes made
+  - removed grscheller.fp dependency
+  - remove `_sentinel` and `_storable` slots from CA class
+  - remove copy method, just use `ca2 = CA(*ca1)` to make a shallow copy
+  - adjust `__repr__` and `__str__` methods
+  - experimenting with Spinx syntax in docstrings (still using pdoc3)
+  - 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`
+    - TODO: rename `foldL` to `fold_forward` & `foldR` to `fold_backward`
+  - 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
+
+### Version 3.2.0 - PyPI release date 2024-07-26
+
+- class name changed CircularArray -> CA
+- Now takes a "sentinel" or "fallback" value in its initializer
+  - formally used None for this
+
+### Version 3.1.0 - PyPI release date 2024-07-11
+
+- generic typing now being used
+- first PyPI release where mult values can be pushed on CircularArray
+
+### Version 3.0.0 - commit date 2024-06-28
+
+- CircularArray class now using Generic Type Parameter
+
+- new epoch in development, start of 3.0 series
+
+- now using TypeVars
+
+- API changes
+
+  - `foldL(self, f: Callable[[T, T], T]) -> T|None`
+  - `foldR(self, f: Callable[[T, T], T]) -> T|None`
+  - `foldL1(self, f: Callable[[S, T], S], initial: S) -> S`
+  - `foldR1(self, f: Callable[[T, S], S], initial: S) -> S`
+
+### Version 2.0.0 - PyPI release date 2024-03-08
+
+- new epoch due to resizing bug fixed on previous commit
+  - much improved and cleaned up
+  - much better test suite
+- method `_double()` made "public" and renamed `double()`
+- method `resize(new_size)` now resizes to at least new_size
+
+### Version 1.1.0.0 - commit date 2024-03-08
+
+- NEXT PyPI RELEASE WILL BE 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 to improve API for resizing CircularArrays
+  - need to test my other 2 PyPI projects
+    - both use circular-array as a dependency
+
+### Version 1.0.1 - PyPI release date 2024-03-01
+
+- docstring updates to match other grscheller PyPI repos
+
+### Version 1.0.0 - PyPI release date 2024-02-10
+
+- first stable release
+- dropped minimum Python requirement to 3.10
+
+### Version 0.1.1 - PyPI release date 2024-01-30
+
+- changed circular-array from a package to just a module
+  - actually breaking API change
+  - version number should have been 0.2.0
+- gave CircularArray class `foldL` & `foldR` methods
+
+### Version 0.1.0 - PyPI release date 2024-01-28
+
+- initial PyPI grscheller.circular-array release
+- migrated Circulararray class from grscheller.datastructures
+- update docstrings to reflect current nomenclature
+
+### Version 0.0.3 - commit date 2024-01-28
+
+- got gh-pages working for the repo
+
+### Version 0.0.2 - commit date 2024-01-28
+
+- pushed repo up to GitHub
+- created README.md file for project
+
+### Version 0.0.1 - commit date 2024-01-28
+
+- decided to split Circulararray class out of datastructures
+  - will make it its own PyPI project
+- got working with datastructures locally

dtools_circular_array-3.11.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: dtools.circular-array
+Version: 3.11.0
+Summary: ### Developer Tools - circular array data structure
+Keywords: circular array,circle array,CA,dequeue,dqueue,FIFO,LIFO,pop,push,indexable,auto-resizing,auto resizing,resizing
+Author-email: "Geoffrey R. Scheller" <geoffrey@scheller.com>
+Requires-Python: >=3.12
+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.13
+Classifier: Typing :: Typed
+License-File: LICENSE
+Requires-Dist: pytest >=8.3.5 ; extra == "test"
+Project-URL: Changelog, https://github.com/grscheller/dtools-circular-array/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://grscheller.github.io/dtools-docs/circular-array
+Project-URL: Source, https://github.com/grscheller/dtools-circular-array
+Provides-Extra: test
+
+# Developer Tools - Circular Array
+
+Python package containing a module implementing a circular array data
+structure,
+
+- **Repositories**
+  - [dtools.circular-array][1] project on *PyPI*
+  - [Source code][2] on *GitHub*
+- **Detailed documentation**
+  - [Detailed API documentation][3] on *GH-Pages*
+
+This project is part of the [Developer Tools for Python][4] **dtools.**
+namespace project.
+
+## Overview
+
+- O(1) amortized pushes and pops either end.
+- O(1) indexing
+- fully supports slicing
+- safely mutates while iterating over copies of previous state
+
+### Module circular_array
+
+A full featured, auto resizing circular array. Python package containing
+a module implementing a full featured, indexable, sliceable, double
+sided, auto-resizing circular array data structure.
+
+Useful either if used directly as an improved version of a Python List
+or in a "has-a" relationship when implementing other data structures.
+
+- *module* dtools.circular_array
+  - *class* ca: circular array data structure
+  - *function* CA: factory function to produce a ca from data
+
+Above nomenclature modeled after of a builtin data type like `list`, where
+`ca` takes an optional iterator as an argument and CA is all caps to represent
+syntactic sugar like `[]` or `{}`.
+
+#### Usage
+
+```python
+    from dtools.circular_array.ca import CA
+    
+    ca1 = ca(1, 2, 3)
+    assert ca1.popl() == 1
+    assert ca1.popr() == 3
+    ca1.pushr(42, 0)
+    ca1.pushl(0, 1)
+    assert repr(ca1) == 'ca(1, 0, 2, 42, 0)'
+    assert str(ca1) == '(|1, 0, 2, 42, 0|)'
+    
+    ca2 = CA(range(1,11))
+    assert repr(ca2) == 'ca(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)'
+    assert str(ca2) == '(|1, 2, 3, 4, 5, 6, 7, 8, 9, 10|)'
+    assert len(ca2) == 10
+    tup3 = ca2.poplt(3)
+    tup4 = ca2.poprt(4)
+    assert tup3 == (1, 2, 3)
+    assert tup4 == (10, 9, 8, 7)
+    assert ca2 == CA(4, 5, 6)
+    four, *rest = ca.popft(1000)
+    assert four == 4
+    assert rest == [5, 6]
+    assert len(ca2) == 0
+    
+    ca3 = CA([1, 2, 3])
+    assert ca3.popld(42) == 1
+    assert ca3.poprd(42) == 3
+    assert ca3.popld(42) == 2
+    assert ca3.poprd(42) == 42
+    assert ca3.popld(42) == 42
+    assert len(ca2) == 0
+```
+
+______________________________________________________________________
+
+[1]: https://pypi.org/project/dtools.circular-array
+[2]: https://github.com/grscheller/dtools-circular-array
+[3]: https://grscheller.github.io/dtools-docs/circular-array
+[4]: https://github.com/grscheller/dtools-docs
+

dtools_circular_array-3.11.0/README.md

@@ -0,0 +1,80 @@
+# Developer Tools - Circular Array
+
+Python package containing a module implementing a circular array data
+structure,
+
+- **Repositories**
+  - [dtools.circular-array][1] project on *PyPI*
+  - [Source code][2] on *GitHub*
+- **Detailed documentation**
+  - [Detailed API documentation][3] on *GH-Pages*
+
+This project is part of the [Developer Tools for Python][4] **dtools.**
+namespace project.
+
+## Overview
+
+- O(1) amortized pushes and pops either end.
+- O(1) indexing
+- fully supports slicing
+- safely mutates while iterating over copies of previous state
+
+### Module circular_array
+
+A full featured, auto resizing circular array. Python package containing
+a module implementing a full featured, indexable, sliceable, double
+sided, auto-resizing circular array data structure.
+
+Useful either if used directly as an improved version of a Python List
+or in a "has-a" relationship when implementing other data structures.
+
+- *module* dtools.circular_array
+  - *class* ca: circular array data structure
+  - *function* CA: factory function to produce a ca from data
+
+Above nomenclature modeled after of a builtin data type like `list`, where
+`ca` takes an optional iterator as an argument and CA is all caps to represent
+syntactic sugar like `[]` or `{}`.
+
+#### Usage
+
+```python
+    from dtools.circular_array.ca import CA
+    
+    ca1 = ca(1, 2, 3)
+    assert ca1.popl() == 1
+    assert ca1.popr() == 3
+    ca1.pushr(42, 0)
+    ca1.pushl(0, 1)
+    assert repr(ca1) == 'ca(1, 0, 2, 42, 0)'
+    assert str(ca1) == '(|1, 0, 2, 42, 0|)'
+    
+    ca2 = CA(range(1,11))
+    assert repr(ca2) == 'ca(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)'
+    assert str(ca2) == '(|1, 2, 3, 4, 5, 6, 7, 8, 9, 10|)'
+    assert len(ca2) == 10
+    tup3 = ca2.poplt(3)
+    tup4 = ca2.poprt(4)
+    assert tup3 == (1, 2, 3)
+    assert tup4 == (10, 9, 8, 7)
+    assert ca2 == CA(4, 5, 6)
+    four, *rest = ca.popft(1000)
+    assert four == 4
+    assert rest == [5, 6]
+    assert len(ca2) == 0
+    
+    ca3 = CA([1, 2, 3])
+    assert ca3.popld(42) == 1
+    assert ca3.poprd(42) == 3
+    assert ca3.popld(42) == 2
+    assert ca3.poprd(42) == 42
+    assert ca3.popld(42) == 42
+    assert len(ca2) == 0
+```
+
+______________________________________________________________________
+
+[1]: https://pypi.org/project/dtools.circular-array
+[2]: https://github.com/grscheller/dtools-circular-array
+[3]: https://grscheller.github.io/dtools-docs/circular-array
+[4]: https://github.com/grscheller/dtools-docs

{dtools_circular_array-3.9.1 → dtools_circular_array-3.11.0}/pyproject.toml

@@ -4,9 +4,7 @@ build-backend = "flit_core.buildapi"
 
 [project]
 name = "dtools.circular-array"
-authors = [
-    { name = "Geoffrey R. Scheller", email = "geoffrey@scheller.com" },
-]
+authors = [{ name = "Geoffrey R. Scheller", email = "geoffrey@scheller.com" }]
 license = { file = "LICENSE" }
 readme = "README.md"
 requires-python = ">=3.12"
@@ -17,19 +15,28 @@ classifiers = [
     "License :: OSI Approved :: Apache Software License",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3.13",
-    "Typing :: Typed"
+    "Typing :: Typed",
 ]
 dependencies = []
 dynamic = ["version", "description"]
 keywords = [
-    "circular array", "circle array", "CA",
-    "double ended queue", "dequeue", "dqueue",
-    "pop", "push", "popL", "popR", "pushL", "pushR", "indexable",
-    "auto-resizing", "auto resizing", "resizing"
+    "circular array",
+    "circle array",
+    "CA",
+    "dequeue",
+    "dqueue",
+    "FIFO",
+    "LIFO",
+    "pop",
+    "push",
+    "indexable",
+    "auto-resizing",
+    "auto resizing",
+    "resizing",
 ]
 
 [project.optional-dependencies]
-test = ["pytest >=8.3.2"]
+test = ["pytest >=8.3.5"]
 
 [project.urls]
 Source = "https://github.com/grscheller/dtools-circular-array"
@@ -37,7 +44,10 @@ Changelog = "https://github.com/grscheller/dtools-circular-array/blob/main/CHANG
 Documentation = "https://grscheller.github.io/dtools-docs/circular-array"
 
 [tool.flit.sdist]
-exclude = ["dist", "docs", ".gitignore", ".mypy_cache"]
+exclude = ["dist", "tests", ".gitignore", ".mypy_cache", ".pytest_cache"]
+
+[tool.pytest.ini_options]
+consider_namespace_packages = true
 
 [tool.pylsp-mypy]
 enabled = true
@@ -47,10 +57,11 @@ report_progress = true
 
 [tool.mypy]
 enable_incomplete_feature = ["NewGenericSyntax"]
-
-[tool.pytest.ini_options]
-testpaths = ["tests"]
-consider_namespace_packages = true
+implicit_reexport = false
+local_partial_types = true
+warn_redundant_casts = true
+warn_return_any = true
+warn_unused_configs = true
 
 [tool.ruff]
 target-version = "py313"
@@ -58,8 +69,9 @@ target-version = "py313"
 [tool.ruff.lint.per-file-ignores]
 "__init__.py" = ["F401"]
 
-[tool.ruff.format]
-quote-style = "single"
-
 [tool.ruff.lint.flake8-quotes]
 docstring-quotes = "double"
+
+[tool.ruff.format]
+quote-style = "single"
+docstring-code-line-length = 72

dtools_circular_array-3.11.0/src/dtools/circular_array/__init__.py

@@ -0,0 +1,34 @@
+# Copyright 2023-2025 Geoffrey R. Scheller
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""### Developer Tools - circular array data structure
+
+Package for an indexable, sliceable, auto-resizing circular array
+data structure with amortized O(1) pushes and pops either end.
+
+#### Circular Array Data Structure
+
+* *module* dtools.circular_array.ca
+  * circular array data structure
+* *class* dtools.circular_array.ca.CA
+  * initializer takes 1 or 0 iterables
+* *function* dtools.circular_array.ca.ca
+  * factory function taking a variable number of arguments
+
+"""
+
+__version__ = '3.11.0'
+__author__ = 'Geoffrey R. Scheller'
+__copyright__ = 'Copyright (c) 2023-2025 Geoffrey R. Scheller'
+__license__ = 'Apache License 2.0'