dtools.circular-array 3.13.0__tar.gz → 3.15.0__tar.gz

{dtools_circular_array-3.13.0 → dtools_circular_array-3.15.0}/CHANGELOG.md

@@ -2,12 +2,29 @@
 
 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
+- Strict 3 digit semantic versioning (adopted 2025-05-19)
+  - MAJOR version for incompatible API changes
+  - MINOR version for backward compatible added functionality
+  - PATCH version for backward compatible bug fixes
 
 ## Releases and Important Milestones
 
+### Adapting strict Semantic from this point on - date 2025-05-19
+
+- [Semantic Versioning 2.0.0](https://semver.org/)
+- see top of file
+- previous versioning scheme used
+  - first digit - major event, epoch, or paradigm shift
+  - second digit - breaking API changes, major changes
+  - third digit - bug fixes, API additions
+
+### Version 3.14.0 - PyPI release date 2025-05-10
+
+- Made package just a single module
+  - dtools.circular_array.ca -> dtools.circular_array
+    - dtools/circular_array.ca.py -> dtools/circular_array.py
+  - docstring consolidations/updates
+
 ### Version 3.13.0 - PyPI release date 2025-05-06
 
 - version no longer determined dynamically

{dtools_circular_array-3.13.0 → dtools_circular_array-3.15.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: dtools.circular-array
-Version: 3.13.0
-Summary: ### Developer Tools - Circular Array Data Structure
+Version: 3.15.0
+Summary: An indexable circular array data structure.
 Keywords: circular array,dequeue,pop,push,indexable,auto resizing
 Author-email: "Geoffrey R. Scheller" <geoffrey@scheller.com>
 Requires-Python: >=3.12
@@ -16,15 +16,16 @@ 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: Homepage, https://github.com/grscheller/dtools-docs
+Project-URL: Documentation, https://grscheller.github.io/dtools-namespace-projects/circular-array
+Project-URL: Homepage, https://github.com/grscheller/dtools-namespace-projects/blob/main/README.md
 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,
+structure, This project is part of the [Developer Tools for Python][4]
+**dtools** namespace projects.
 
 - **Repositories**
   - [dtools.circular-array][1] project on *PyPI*
@@ -32,29 +33,27 @@ structure,
 - **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 over previous state
-
-### Module circular_array
-
 A full featured auto resizing circular array data structure. Double
 sided, indexable, sliceable, and iterable. When iterated, uses cached
 copies of its present state so that the circular array itself can safely
 be mutated.
 
+- O(1) amortized pushes and pops either end.
+- O(1) indexing
+- fully supports slicing
+- safely mutates over previous state
+
 Useful either if used directly like 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
+  - *class* `CA:` circular array data structure
+    - initializer takes 1 or 0 iterators
+      - like `list` or `set` does
+  - *function* `ca`: produces a `CA` from the function's arguments
+    - similar use case as syntactic constructs `[]` or `{}`
 
 Above nomenclature modeled after builtin data types like `list`, where
 `CA` and `ca` correspond respectfully to `list` and  `[]` in their use
@@ -63,7 +62,7 @@ cases.
 #### Usage
 
 ```python
-    from dtools.circular_array.ca import CA, ca
+    from dtools.circular_array import CA, ca
     
     ca1 = ca(1, 2, 3)
     assert ca1.popl() == 1
@@ -81,8 +80,8 @@ cases.
     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 ca2 == ca(4, 5, 6)
+    four, *rest = ca2.poplt(1000)
     assert four == 4
     assert rest == [5, 6]
     assert len(ca2) == 0
@@ -96,10 +95,8 @@ cases.
     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
+[3]: https://grscheller.github.io/dtools-namespace-projects/circular-array
+[4]: https://github.com/grscheller/dtools-namespace-projects/blob/main/README.md
 

{dtools_circular_array-3.13.0 → dtools_circular_array-3.15.0}/README.md

@@ -1,7 +1,8 @@
 # Developer Tools - Circular Array
 
 Python package containing a module implementing a circular array data
-structure,
+structure, This project is part of the [Developer Tools for Python][4]
+**dtools** namespace projects.
 
 - **Repositories**
   - [dtools.circular-array][1] project on *PyPI*
@@ -9,29 +10,27 @@ structure,
 - **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 over previous state
-
-### Module circular_array
-
 A full featured auto resizing circular array data structure. Double
 sided, indexable, sliceable, and iterable. When iterated, uses cached
 copies of its present state so that the circular array itself can safely
 be mutated.
 
+- O(1) amortized pushes and pops either end.
+- O(1) indexing
+- fully supports slicing
+- safely mutates over previous state
+
 Useful either if used directly like 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
+  - *class* `CA:` circular array data structure
+    - initializer takes 1 or 0 iterators
+      - like `list` or `set` does
+  - *function* `ca`: produces a `CA` from the function's arguments
+    - similar use case as syntactic constructs `[]` or `{}`
 
 Above nomenclature modeled after builtin data types like `list`, where
 `CA` and `ca` correspond respectfully to `list` and  `[]` in their use
@@ -40,7 +39,7 @@ cases.
 #### Usage
 
 ```python
-    from dtools.circular_array.ca import CA, ca
+    from dtools.circular_array import CA, ca
     
     ca1 = ca(1, 2, 3)
     assert ca1.popl() == 1
@@ -58,8 +57,8 @@ cases.
     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 ca2 == ca(4, 5, 6)
+    four, *rest = ca2.poplt(1000)
     assert four == 4
     assert rest == [5, 6]
     assert len(ca2) == 0
@@ -73,9 +72,7 @@ cases.
     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
+[3]: https://grscheller.github.io/dtools-namespace-projects/circular-array
+[4]: https://github.com/grscheller/dtools-namespace-projects/blob/main/README.md

{dtools_circular_array-3.13.0 → dtools_circular_array-3.15.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "flit_core.buildapi"
 
 [project]
 name = "dtools.circular-array"
-version = "3.13.0"
+version = "3.15.0"
 authors = [{ name = "Geoffrey R. Scheller", email = "geoffrey@scheller.com" }]
 license = { file = "LICENSE" }
 readme = "README.md"
@@ -35,10 +35,10 @@ test = [
 ]
 
 [project.urls]
-Homepage = "https://github.com/grscheller/dtools-docs"
+Homepage = "https://github.com/grscheller/dtools-namespace-projects/blob/main/README.md"
 Source = "https://github.com/grscheller/dtools-circular-array"
 Changelog = "https://github.com/grscheller/dtools-circular-array/blob/main/CHANGELOG.md"
-Documentation = "https://grscheller.github.io/dtools-docs/circular-array"
+Documentation = "https://grscheller.github.io/dtools-namespace-projects/circular-array"
 
 [tool.flit.sdist]
 exclude = ["dist", "tests", ".gitignore", ".mypy_cache", ".pytest_cache"]

dtools_circular_array-3.13.0/src/dtools/circular_array/ca.py → dtools_circular_array-3.15.0/src/dtools/circular_array.py

@@ -12,10 +12,27 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""### An indexable circular array data structure."""
+"""An indexable circular array data structure.
+
+- generic, stateful, invariant data structure
+- amortized O(1) pushing and popping from either end
+- O(1) random access any element
+- will resize itself as needed
+- sliceable
+- makes defensive copies of contents for the purposes of iteration
+- in boolean context returns
+    - `True` when not empty
+    - `False` when empty
+- in comparisons compare identity before equality, like builtins do
+
+"""
 
 from __future__ import annotations
 
+__author__ = 'Geoffrey R. Scheller'
+__copyright__ = 'Copyright (c) 2023-2025 Geoffrey R. Scheller'
+__license__ = 'Apache License 2.0'
+
 from collections.abc import Callable, Iterable, Iterator
 from typing import cast, Never, overload, TypeVar
 
@@ -27,7 +44,6 @@ D = TypeVar('D')
 class CA[D]:
     """Indexable circular array data structure
 
-    - generic, stateful data structure
     - amortized O(1) pushing and popping from either end
     - O(1) random access any element
     - will resize itself as needed

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

@@ -1,32 +0,0 @@
-# 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
-  - *class* dtools.circular_array.ca.CA
-    - initializer takes up to 1 iterable
-  - *function* dtools.circular_array.ca.ca
-    - constructs a `CA` from a variable number of arguments
-
-"""
-
-__author__ = 'Geoffrey R. Scheller'
-__copyright__ = 'Copyright (c) 2023-2025 Geoffrey R. Scheller'
-__license__ = 'Apache License 2.0'