Enhance CircularQueue to support first entry

Author: pronovic

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "apologies"
-version = "0.1.11"
+version = "0.1.12"
 description = "Python code to play a game similar to Sorry"
 authors = ["Kenneth J. Pronovici <pronovic@ieee.org>"]
 license = "Apache-2.0"

src/apologies/util.py

@@ -5,7 +5,7 @@
 Utility functionality.
 """
 
-from typing import Generic, List, TypeVar
+from typing import Any, Generic, List, TypeVar
 
 import attr
 import cattr
@@ -24,27 +24,39 @@ def __init__(self) -> None:
         self.register_structure_hook(DateTime, lambda string, _: parse(string) if string else None)
 
 
-Type = TypeVar("Type")
+T = TypeVar("T")  # pylint: disable=invalid-name
 """Generic type"""
 
 
 @attr.s
-class CircularQueue(Generic[Type]):
+class CircularQueue(Generic[T]):
     """A circular queue that keeps returning the original entries repeatedly, in order."""
 
-    entries = attr.ib(type=List[Type])
-    _working = attr.ib(type=List[Type])
+    entries = attr.ib(type=List[T])
+    first = attr.ib(type=Any)
+    _working = attr.ib(type=List[T])
+
+    @first.default
+    def _default_first(self) -> Any:
+        return None if not self.entries else self.entries[0]
 
     @_working.default
-    def _default_working(self) -> List[Type]:
-        return self.entries[:]
+    def _default_working(self) -> List[T]:
+        if self.first not in self.entries:
+            raise ValueError("First entry not found")
+        temp = self.entries[:]
+        popped = temp.pop(0)
+        while popped != self.first:
+            popped = temp.pop(0)
+        temp.insert(0, popped)
+        return temp
 
     @entries.validator
     def _check_entries(self, attribute: str, value: int) -> None:
         if not value:
             raise ValueError("Entries must not be empty")
 
-    def next(self) -> Type:
+    def next(self) -> T:
         """Get the next entry from the queue."""
         if len(self._working) == 0:
             self._working.extend(self.entries)

tests/test_util.py

@@ -22,12 +22,83 @@ def test_constructor_single(self):
         assert queue.next() == "a"
         assert queue.next() == "a"
 
+    def test_constructor_single_none(self):
+        queue = CircularQueue([None])
+        assert queue.entries == [None]
+        assert queue.next() is None
+        assert queue.next() is None
+        assert queue.next() is None
+        assert queue.next() is None
+        assert queue.next() is None
+        assert queue.next() is None
+
     def test_constructor_multiple(self):
-        queue = CircularQueue(["a", "b", "c"])
-        assert queue.entries == ["a", "b", "c"]
+        queue = CircularQueue(["a", "b", "c", "d", "e", None])
+        assert queue.entries == ["a", "b", "c", "d", "e", None]
+        assert queue.next() == "a"
+        assert queue.next() == "b"
+        assert queue.next() == "c"
+        assert queue.next() == "d"
+        assert queue.next() == "e"
+        assert queue.next() is None
+        assert queue.next() == "a"
+        assert queue.next() == "b"
+        assert queue.next() == "c"
+        assert queue.next() == "d"
+        assert queue.next() == "e"
+        assert queue.next() is None
+        assert queue.next() == "a"
+
+    def test_constructor_multiple_first(self):
+        queue = CircularQueue(["a", "b", "c", "d", "e", None], first="c")
+        assert queue.entries == ["a", "b", "c", "d", "e", None]
+        assert queue.next() == "c"
+        assert queue.next() == "d"
+        assert queue.next() == "e"
+        assert queue.next() is None
         assert queue.next() == "a"
         assert queue.next() == "b"
         assert queue.next() == "c"
+        assert queue.next() == "d"
+        assert queue.next() == "e"
+        assert queue.next() is None
+        assert queue.next() == "a"
+        assert queue.next() == "b"
+        assert queue.next() == "c"
+
+    def test_constructor_multiple_first_none(self):
+        queue = CircularQueue(["a", "b", "c", "d", "e", None], first=None)
+        assert queue.entries == ["a", "b", "c", "d", "e", None]
+        assert queue.next() is None
         assert queue.next() == "a"
         assert queue.next() == "b"
         assert queue.next() == "c"
+        assert queue.next() == "d"
+        assert queue.next() == "e"
+        assert queue.next() is None
+        assert queue.next() == "a"
+        assert queue.next() == "b"
+        assert queue.next() == "c"
+        assert queue.next() == "d"
+        assert queue.next() == "e"
+        assert queue.next() is None
+
+    def test_constructor_first_invalid(self):
+        with pytest.raises(ValueError):
+            CircularQueue([], first=None)
+        with pytest.raises(ValueError):
+            CircularQueue([], first="")
+        with pytest.raises(ValueError):
+            CircularQueue([], first="f")
+        with pytest.raises(ValueError):
+            CircularQueue(["a"], first=None)
+        with pytest.raises(ValueError):
+            CircularQueue(["a"], first="")
+        with pytest.raises(ValueError):
+            CircularQueue(["a"], first="f")
+        with pytest.raises(ValueError):
+            CircularQueue(["a", "b", "c", "d", "e"], first=None)
+        with pytest.raises(ValueError):
+            CircularQueue(["a", "b", "c", "d", "e"], first="")
+        with pytest.raises(ValueError):
+            CircularQueue(["a", "b", "c", "d", "e"], first="f")