feat: add __eq__, __bool__, slicing, __reversed__, and infrastructure

AzizAlievDevelopment · AzizAlievDevelopment · commit ae3b1a30d0e4 · 2026-03-13T17:49:59.000+05:00
- Add __eq__ and __bool__ to all data structures (arrays, stacks, linked lists)
- Add slice support (arr[1:3], arr[::-1]) for StaticArray and DynamicArray
- Add __reversed__ for DoublyLinkedList (tail-to-head iteration)
- Add hypothesis property-based tests (17 invariant checks)
- Add doctests to CI pipeline with fixed imports in ABC docstrings
- Add coverage badge, CI badge, and Python version badge to README
- Add hypothesis dependency and update .gitignore
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -43,4 +43,7 @@ jobs:
         run: uv sync --group dev
 
       - name: Run tests
-        run: uv run pytest tests/ -v
+        run: uv run pytest tests/ -v --cov-fail-under=90
+
+      - name: Run doctests
+        run: uv run pytest --doctest-modules data_structures/ algorithms/ --no-cov
diff --git a/.gitignore b/.gitignore
@@ -8,5 +8,17 @@ wheels/
 
 # Virtual environments
 .venv
+
+# IDE
 .idea/
+.vscode/
+
+# Testing / Coverage
 .coverage
+coverage.json
+htmlcov/
+.pytest_cache/
+.benchmarks/
+
+# Hypothesis
+.hypothesis/
diff --git a/README.md b/README.md
@@ -1,5 +1,9 @@
 # Python DSA
 
+![CI](https://github.com/azizjon-aliev/python-dsa/actions/workflows/ci.yml/badge.svg)
+![Coverage](https://img.shields.io/badge/coverage-97%25-brightgreen)
+![Python](https://img.shields.io/badge/python-3.13%2B-blue)
+
 A collection of classic data structures and algorithms implemented in Python.
 
 ## Data Structures
@@ -132,6 +136,9 @@ uv run pytest tests/ -v
 # Run benchmarks
 uv run pytest tests/test_benchmarks.py --benchmark-enable --no-cov
 
+# Run doctests
+uv run pytest --doctest-modules data_structures/ algorithms/ --no-cov
+
 # Lint & format
 uv run ruff check .
 uv run ruff format .
@@ -169,6 +176,7 @@ tests/
   test_linked_lists.py     # pytest suite for linked list implementations
   test_binary_search.py    # pytest suite for binary search
   test_benchmarks.py       # pytest-benchmark performance tests
+  test_properties.py       # hypothesis property-based tests
 .pre-commit-config.yaml    # pre-commit hooks (ruff, ty)
 pyproject.toml             # project config, tools settings
 ```
diff --git a/data_structures/array/base.py b/data_structures/array/base.py
@@ -1,10 +1,11 @@
 from abc import ABC, abstractmethod
-from typing import Iterator
+from typing import Iterator, overload
 
 
 class IArray[T](ABC):
     """Abstract Array interface (random-access, indexed collection).
 
+    >>> from data_structures.array.static_array import StaticArray
     >>> a = StaticArray(4)
     >>> a.append(10); a.append(20); a.append(30)
     >>> a[1]
@@ -39,9 +40,13 @@ def clear(self) -> None:
     def is_empty(self) -> bool:
         """Return ``True`` if the array contains no elements. O(1)."""
 
+    @overload
+    def __getitem__(self, index: int) -> T: ...
+    @overload
+    def __getitem__(self, index: slice) -> list[T]: ...
     @abstractmethod
-    def __getitem__(self, index: int) -> T:
-        """Return the element at *index*. O(1)."""
+    def __getitem__(self, index: int | slice) -> T | list[T]:
+        """Return element at *index* or a ``list`` for a slice."""
 
     @abstractmethod
     def __setitem__(self, index: int, value: T) -> None:
@@ -59,6 +64,18 @@ def __iter__(self) -> Iterator[T]:
     def __contains__(self, item: object) -> bool:
         """Return ``True`` if *item* is in the array. O(n)."""
 
+    def __eq__(self, other: object) -> bool:
+        """Element-wise equality. Works across array types. O(n)."""
+        if not isinstance(other, IArray):
+            return NotImplemented
+        if len(self) != len(other):
+            return False
+        return all(a == b for a, b in zip(self, other))
+
+    def __bool__(self) -> bool:
+        """Return ``True`` if the array is non-empty."""
+        return not self.is_empty()
+
     @abstractmethod
     def __repr__(self) -> str:
         """Return a developer-friendly representation (e.g. ``StaticArray([1, 2])``)."""
diff --git a/data_structures/array/dynamic_array.py b/data_structures/array/dynamic_array.py
@@ -1,5 +1,5 @@
 from collections.abc import Iterable
-from typing import Iterator
+from typing import Iterator, overload
 
 from .base import IArray
 
@@ -95,8 +95,14 @@ def capacity(self) -> int:
         """Return the current internal capacity."""
         return self._capacity
 
-    def __getitem__(self, index: int) -> T:
-        """Return the element at *index*. O(1)."""
+    @overload
+    def __getitem__(self, index: int) -> T: ...
+    @overload
+    def __getitem__(self, index: slice) -> list[T]: ...
+    def __getitem__(self, index: int | slice) -> T | list[T]:
+        """Return element at *index* or a ``list`` for a slice."""
+        if isinstance(index, slice):
+            return [self._data[i] for i in range(*index.indices(self._size))]  # type: ignore[misc]
         index = self._normalize_index(index)
         return self._data[index]  # type: ignore[return-value]
 
diff --git a/data_structures/array/static_array.py b/data_structures/array/static_array.py
@@ -1,5 +1,5 @@
 from collections.abc import Iterable
-from typing import Iterator
+from typing import Iterator, overload
 
 from .base import IArray
 
@@ -97,8 +97,14 @@ def capacity(self) -> int:
         """Return the maximum number of elements the array can hold."""
         return self._capacity
 
-    def __getitem__(self, index: int) -> T:
-        """Return the element at *index*. O(1)."""
+    @overload
+    def __getitem__(self, index: int) -> T: ...
+    @overload
+    def __getitem__(self, index: slice) -> list[T]: ...
+    def __getitem__(self, index: int | slice) -> T | list[T]:
+        """Return element at *index* or a ``list`` for a slice."""
+        if isinstance(index, slice):
+            return [self._data[i] for i in range(*index.indices(self._size))]  # type: ignore[misc]
         index = self._normalize_index(index)
         return self._data[index]  # type: ignore[return-value]
 
diff --git a/data_structures/linked_list/base.py b/data_structures/linked_list/base.py
@@ -47,6 +47,18 @@ def __len__(self) -> int:
     def __contains__(self, item: object) -> bool:
         """Return ``True`` if *item* is in the list. O(n)."""
 
+    def __eq__(self, other: object) -> bool:
+        """Element-wise equality. Works across list types. O(n)."""
+        if not isinstance(other, ISinglyLinkedList):
+            return NotImplemented
+        if len(self) != len(other):
+            return False
+        return all(a == b for a, b in zip(self, other))
+
+    def __bool__(self) -> bool:
+        """Return ``True`` if the list is non-empty."""
+        return not self.is_empty()
+
     @abstractmethod
     def __repr__(self) -> str:
         """Return a developer-friendly representation."""
@@ -74,3 +86,7 @@ def pop_back(self) -> T:
     @abstractmethod
     def peek_back(self) -> T:
         """Return the tail element without removing it. O(1)."""
+
+    @abstractmethod
+    def __reversed__(self) -> Iterator[T]:
+        """Iterate over all elements from tail to head. O(n)."""
diff --git a/data_structures/linked_list/doubly_linked_list.py b/data_structures/linked_list/doubly_linked_list.py
@@ -89,6 +89,12 @@ def __iter__(self) -> Iterator[T]:
             yield node.value
             node = node.next
 
+    def __reversed__(self) -> Iterator[T]:
+        node = self._tail
+        while node is not None:
+            yield node.value
+            node = node.prev
+
     def __len__(self) -> int:
         return self._size
 
diff --git a/data_structures/stack/array_stack.py b/data_structures/stack/array_stack.py
@@ -1,3 +1,5 @@
+from typing import Iterator
+
 from data_structures.array.dynamic_array import DynamicArray
 
 from .base import IStack, StackEmptyError
@@ -34,6 +36,9 @@ def __len__(self) -> int:
     def __contains__(self, item: object) -> bool:
         return item in self._items
 
+    def _iter_items(self) -> Iterator[T]:
+        return reversed(list(self._items))
+
     def __repr__(self) -> str:
         return f"{type(self).__name__}({list(self._items)})"
 
diff --git a/data_structures/stack/base.py b/data_structures/stack/base.py
@@ -1,4 +1,5 @@
 from abc import ABC, abstractmethod
+from typing import Iterator
 
 
 class StackEmptyError(Exception):
@@ -11,6 +12,7 @@ def __init__(self) -> None:
 class IStack[T](ABC):
     """Abstract Stack interface (LIFO - Last In First Out).
 
+    >>> from data_structures.stack.array_stack import ArrayStack
     >>> s = ArrayStack()
     >>> s.push(1); s.push(2); s.push(3)
     >>> s.peek()
@@ -49,6 +51,22 @@ def __len__(self) -> int:
     def __contains__(self, item: object) -> bool:
         """Return ``True`` if *item* is in the stack. O(n)."""
 
+    def __eq__(self, other: object) -> bool:
+        """Element-wise equality (top to bottom). O(n)."""
+        if not isinstance(other, IStack):
+            return NotImplemented
+        if len(self) != len(other):
+            return False
+        return list(self._iter_items()) == list(other._iter_items())
+
+    def __bool__(self) -> bool:
+        """Return ``True`` if the stack is non-empty."""
+        return not self.is_empty()
+
+    @abstractmethod
+    def _iter_items(self) -> Iterator[T]:
+        """Iterate elements from top to bottom (for equality)."""
+
     @abstractmethod
     def __repr__(self) -> str:
         """Return a developer-friendly representation."""
diff --git a/data_structures/stack/linked_list_stack.py b/data_structures/stack/linked_list_stack.py
@@ -1,3 +1,5 @@
+from typing import Iterator
+
 from data_structures.linked_list.singly_linked_list import SinglyLinkedList
 
 from .base import IStack, StackEmptyError
@@ -37,6 +39,9 @@ def __len__(self) -> int:
     def __contains__(self, item: object) -> bool:
         return item in self._items
 
+    def _iter_items(self) -> Iterator[T]:
+        return iter(self._items)
+
     def __repr__(self) -> str:
         return f"{type(self).__name__}({list(self._items)})"
 
diff --git a/pyproject.toml b/pyproject.toml
@@ -8,6 +8,7 @@ dependencies = []
 
 [dependency-groups]
 dev = [
+    "hypothesis>=6.0.0",
     "pre-commit>=4.5.1",
     "pytest",
     "pytest-benchmark>=5.1.0",
diff --git a/tests/test_arrays.py b/tests/test_arrays.py
@@ -156,6 +156,95 @@ def test_contains(arr):
     assert 42 not in arr
 
 
+def test_bool_empty(arr):
+    assert not arr
+
+
+def test_bool_non_empty(arr):
+    arr.append(1)
+    assert arr
+
+
+def test_eq_same_elements(arr):
+    for v in [1, 2, 3]:
+        arr.append(v)
+    other = DynamicArray([1, 2, 3])
+    assert arr == other
+
+
+def test_eq_different_elements(arr):
+    for v in [1, 2, 3]:
+        arr.append(v)
+    other = DynamicArray([1, 2, 4])
+    assert arr != other
+
+
+def test_eq_different_length(arr):
+    arr.append(1)
+    other = DynamicArray([1, 2])
+    assert arr != other
+
+
+def test_eq_not_array(arr):
+    arr.append(1)
+    assert arr != "not an array"
+
+
+def test_eq_cross_type():
+    sa = StaticArray([1, 2, 3])
+    da = DynamicArray([1, 2, 3])
+    assert sa == da
+
+
+def test_slice_basic(arr):
+    for v in [1, 2, 3, 4, 5]:
+        arr.append(v)
+    assert arr[1:3] == [2, 3]
+
+
+def test_slice_from_start(arr):
+    for v in [1, 2, 3, 4, 5]:
+        arr.append(v)
+    assert arr[:3] == [1, 2, 3]
+
+
+def test_slice_to_end(arr):
+    for v in [1, 2, 3, 4, 5]:
+        arr.append(v)
+    assert arr[3:] == [4, 5]
+
+
+def test_slice_full(arr):
+    for v in [1, 2, 3]:
+        arr.append(v)
+    assert arr[:] == [1, 2, 3]
+
+
+def test_slice_with_step(arr):
+    for v in [1, 2, 3, 4, 5]:
+        arr.append(v)
+    assert arr[::2] == [1, 3, 5]
+
+
+def test_slice_negative(arr):
+    for v in [1, 2, 3, 4, 5]:
+        arr.append(v)
+    assert arr[-3:] == [3, 4, 5]
+    assert arr[:-2] == [1, 2, 3]
+
+
+def test_slice_reverse(arr):
+    for v in [1, 2, 3, 4, 5]:
+        arr.append(v)
+    assert arr[::-1] == [5, 4, 3, 2, 1]
+
+
+def test_slice_empty_result(arr):
+    for v in [1, 2, 3]:
+        arr.append(v)
+    assert arr[5:10] == []
+
+
 # ── StaticArray-specific tests ───────────────────────────────────────
 
 
diff --git a/tests/test_linked_lists.py b/tests/test_linked_lists.py
diff --git a/tests/test_properties.py b/tests/test_properties.py
diff --git a/tests/test_stacks.py b/tests/test_stacks.py
diff --git a/uv.lock b/uv.lock
