feat: add __str__ methods and pytest-benchmark support

AzizAlievDevelopment · AzizAlievDevelopment · commit c3ddebaf5558 · 2026-03-13T16:51:41.000+05:00
Add human-friendly __str__ to all data structures (arrow notation for
linked lists and stacks, plain list for arrays) and integrate
pytest-benchmark for performance testing.
diff --git a/README.md b/README.md
@@ -23,6 +23,8 @@ s.push(2)
 s.peek()   # 2
 s.pop()    # 2
 s.size()   # 1
+repr(s)    # "ArrayStack([1])"
+str(s)     # "1"
 
 ms = MinStack()
 ms.push(5)
@@ -43,6 +45,8 @@ from data_structures.array.static_array import StaticArray
 from data_structures.array.dynamic_array import DynamicArray
 
 sa = StaticArray([1, 2, 3])   # or StaticArray(3) for empty
+repr(sa)       # "StaticArray([1, 2, 3])"
+str(sa)        # "[1, 2, 3]"
 list(sa)       # [1, 2, 3]
 sa.pop()       # 3
 sa.insert(0, 0)
@@ -70,13 +74,15 @@ sll = SinglyLinkedList()
 sll.push_front(1)
 sll.push_front(2)
 sll.peek_front()  # 2
+str(sll)          # "2 -> 1"
 sll.pop_front()   # 2
 list(sll)         # [1]
 
 dll = DoublyLinkedList()
 dll.push_front(1)
 dll.push_back(2)
 dll.push_back(3)
+str(dll)          # "1 <-> 2 <-> 3"
 dll.peek_back()   # 3
 dll.pop_back()    # 3
 list(dll)         # [1, 2]
@@ -123,6 +129,9 @@ uv sync --group dev
 # Run tests (with coverage)
 uv run pytest tests/ -v
 
+# Run benchmarks
+uv run pytest tests/test_benchmarks.py --benchmark-enable --no-cov
+
 # Lint & format
 uv run ruff check .
 uv run ruff format .
@@ -159,6 +168,7 @@ tests/
   test_stacks.py           # pytest suite for stack implementations
   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
 .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
@@ -61,4 +61,8 @@ def __contains__(self, item: object) -> bool:
 
     @abstractmethod
     def __repr__(self) -> str:
-        """Return a string representation."""
+        """Return a developer-friendly representation (e.g. ``StaticArray([1, 2])``)."""
+
+    @abstractmethod
+    def __str__(self) -> str:
+        """Return a human-friendly string (e.g. ``[1, 2]``)."""
diff --git a/data_structures/array/dynamic_array.py b/data_structures/array/dynamic_array.py
@@ -119,9 +119,13 @@ def __contains__(self, item: object) -> bool:
         return any(v == item for v in self)
 
     def __repr__(self) -> str:
-        """Return a string representation."""
+        """Developer-friendly representation (e.g. ``DynamicArray([1, 2])``)."""
         return f"{type(self).__name__}({list(self)})"
 
+    def __str__(self) -> str:
+        """Return a human-friendly string (e.g. ``[1, 2]``)."""
+        return str(list(self))
+
     def _normalize_index(self, index: int) -> int:
         """Translate negative indices and validate bounds."""
         if index < 0:
diff --git a/data_structures/array/static_array.py b/data_structures/array/static_array.py
@@ -121,9 +121,13 @@ def __contains__(self, item: object) -> bool:
         return any(v == item for v in self)
 
     def __repr__(self) -> str:
-        """Return a string representation."""
+        """Return a developer-friendly representation (e.g. ``StaticArray([1, 2])``)."""
         return f"{type(self).__name__}({list(self)})"
 
+    def __str__(self) -> str:
+        """Return a human-friendly string (e.g. ``[1, 2]``)."""
+        return str(list(self))
+
     def _normalize_index(self, index: int) -> int:
         """Translate negative indices and validate bounds."""
         if index < 0:
diff --git a/data_structures/linked_list/base.py b/data_structures/linked_list/base.py
@@ -49,7 +49,11 @@ def __contains__(self, item: object) -> bool:
 
     @abstractmethod
     def __repr__(self) -> str:
-        """Return a string representation."""
+        """Return a developer-friendly representation."""
+
+    @abstractmethod
+    def __str__(self) -> str:
+        """Return a human-friendly string (e.g. ``1 -> 2 -> 3``)."""
 
 
 class IDoublyLinkedList[T](ISinglyLinkedList[T]):
diff --git a/data_structures/linked_list/doubly_linked_list.py b/data_structures/linked_list/doubly_linked_list.py
@@ -97,3 +97,6 @@ def __contains__(self, item: object) -> bool:
 
     def __repr__(self) -> str:
         return f"{type(self).__name__}({list(self)})"
+
+    def __str__(self) -> str:
+        return " <-> ".join(str(v) for v in self) if self._head else "empty"
diff --git a/data_structures/linked_list/singly_linked_list.py b/data_structures/linked_list/singly_linked_list.py
@@ -55,3 +55,6 @@ def __contains__(self, item: object) -> bool:
 
     def __repr__(self) -> str:
         return f"{type(self).__name__}({list(self)})"
+
+    def __str__(self) -> str:
+        return " -> ".join(str(v) for v in self) if self._head else "empty"
diff --git a/data_structures/stack/array_stack.py b/data_structures/stack/array_stack.py
@@ -36,3 +36,7 @@ def __contains__(self, item: object) -> bool:
 
     def __repr__(self) -> str:
         return f"{type(self).__name__}({list(self._items)})"
+
+    def __str__(self) -> str:
+        items = list(self._items)
+        return " -> ".join(str(v) for v in reversed(items)) if items else "empty"
diff --git a/data_structures/stack/base.py b/data_structures/stack/base.py
@@ -51,4 +51,8 @@ def __contains__(self, item: object) -> bool:
 
     @abstractmethod
     def __repr__(self) -> str:
-        """Return a string representation."""
+        """Return a developer-friendly representation."""
+
+    @abstractmethod
+    def __str__(self) -> str:
+        """Return a human-friendly string (top → bottom)."""
diff --git a/data_structures/stack/linked_list_stack.py b/data_structures/stack/linked_list_stack.py
@@ -39,3 +39,7 @@ def __contains__(self, item: object) -> bool:
 
     def __repr__(self) -> str:
         return f"{type(self).__name__}({list(self._items)})"
+
+    def __str__(self) -> str:
+        items = list(self._items)
+        return " -> ".join(str(v) for v in items) if items else "empty"
diff --git a/pyproject.toml b/pyproject.toml
@@ -10,6 +10,7 @@ dependencies = []
 dev = [
     "pre-commit>=4.5.1",
     "pytest",
+    "pytest-benchmark>=5.1.0",
     "pytest-cov>=7.0.0",
     "ruff>=0.15.6",
     "ty>=0.0.22",
@@ -23,4 +24,4 @@ select = ["E", "F", "W", "I"]
 
 [tool.pytest.ini_options]
 pythonpath = ["."]
-addopts = "--cov=data_structures --cov=algorithms --cov-report=term-missing"
+addopts = "--cov=data_structures --cov=algorithms --cov-report=term-missing --benchmark-disable"
diff --git a/tests/test_arrays.py b/tests/test_arrays.py
@@ -201,6 +201,15 @@ def test_static_repr_empty():
     assert repr(StaticArray(5)) == "StaticArray([])"
 
 
+def test_static_str():
+    arr = StaticArray([1, 2, 3])
+    assert str(arr) == "[1, 2, 3]"
+
+
+def test_static_str_empty():
+    assert str(StaticArray(5)) == "[]"
+
+
 def test_static_init_from_list():
     arr = StaticArray([10, 20, 30])
     assert list(arr) == [10, 20, 30]
@@ -289,6 +298,15 @@ def test_dynamic_repr_empty():
     assert repr(DynamicArray()) == "DynamicArray([])"
 
 
+def test_dynamic_str():
+    arr = DynamicArray([1, 2, 3])
+    assert str(arr) == "[1, 2, 3]"
+
+
+def test_dynamic_str_empty():
+    assert str(DynamicArray()) == "[]"
+
+
 def test_dynamic_init_from_list():
     arr = DynamicArray([10, 20, 30])
     assert list(arr) == [10, 20, 30]
diff --git a/tests/test_benchmarks.py b/tests/test_benchmarks.py
@@ -0,0 +1,144 @@
+"""Benchmarks for data structures and algorithms.
+
+Run with:  uv run pytest tests/test_benchmarks.py --benchmark-enable -v
+"""
+
+import pytest
+
+from algorithms.searching.binary_search import binary_search
+from data_structures.array.dynamic_array import DynamicArray
+from data_structures.array.static_array import StaticArray
+from data_structures.linked_list.doubly_linked_list import DoublyLinkedList
+from data_structures.linked_list.singly_linked_list import SinglyLinkedList
+from data_structures.stack.array_stack import ArrayStack
+from data_structures.stack.linked_list_stack import LinkedListStack
+
+N = 1_000
+
+
+# ── Array: append ────────────────────────────────────────────────────
+
+
+def test_static_array_append(benchmark):
+    def run():
+        arr = StaticArray(N)
+        for i in range(N):
+            arr.append(i)
+
+    benchmark(run)
+
+
+def test_dynamic_array_append(benchmark):
+    def run():
+        arr = DynamicArray()
+        for i in range(N):
+            arr.append(i)
+
+    benchmark(run)
+
+
+def test_python_list_append(benchmark):
+    def run():
+        lst = []
+        for i in range(N):
+            lst.append(i)
+
+    benchmark(run)
+
+
+# ── Array: random access ─────────────────────────────────────────────
+
+
+@pytest.fixture
+def static_filled():
+    return StaticArray(range(N))
+
+
+@pytest.fixture
+def dynamic_filled():
+    return DynamicArray(range(N))
+
+
+@pytest.fixture
+def list_filled():
+    return list(range(N))
+
+
+def test_static_array_getitem(benchmark, static_filled):
+    benchmark(lambda: [static_filled[i] for i in range(N)])
+
+
+def test_dynamic_array_getitem(benchmark, dynamic_filled):
+    benchmark(lambda: [dynamic_filled[i] for i in range(N)])
+
+
+def test_python_list_getitem(benchmark, list_filled):
+    benchmark(lambda: [list_filled[i] for i in range(N)])
+
+
+# ── Stack: push/pop ──────────────────────────────────────────────────
+
+
+def test_array_stack_push_pop(benchmark):
+    def run():
+        s = ArrayStack()
+        for i in range(N):
+            s.push(i)
+        for _ in range(N):
+            s.pop()
+
+    benchmark(run)
+
+
+def test_linked_list_stack_push_pop(benchmark):
+    def run():
+        s = LinkedListStack()
+        for i in range(N):
+            s.push(i)
+        for _ in range(N):
+            s.pop()
+
+    benchmark(run)
+
+
+# ── Linked list: push_front ──────────────────────────────────────────
+
+
+def test_singly_push_front(benchmark):
+    def run():
+        ll = SinglyLinkedList()
+        for i in range(N):
+            ll.push_front(i)
+
+    benchmark(run)
+
+
+def test_doubly_push_front(benchmark):
+    def run():
+        ll = DoublyLinkedList()
+        for i in range(N):
+            ll.push_front(i)
+
+    benchmark(run)
+
+
+def test_doubly_push_back(benchmark):
+    def run():
+        ll = DoublyLinkedList()
+        for i in range(N):
+            ll.push_back(i)
+
+    benchmark(run)
+
+
+# ── Binary search ────────────────────────────────────────────────────
+
+SORTED = list(range(10_000))
+
+
+def test_binary_search_hit(benchmark):
+    benchmark(binary_search, SORTED, 7_777)
+
+
+def test_binary_search_miss(benchmark):
+    benchmark(binary_search, SORTED, -1)
diff --git a/tests/test_linked_lists.py b/tests/test_linked_lists.py
@@ -72,6 +72,10 @@ def test_iter_empty(ll):
     assert list(ll) == []
 
 
+def test_str_empty(ll):
+    assert str(ll) == "empty"
+
+
 def test_push_pop_until_empty(ll):
     for v in range(10):
         ll.push_front(v)
@@ -81,6 +85,13 @@ def test_push_pop_until_empty(ll):
     assert ll.size() == 0
 
 
+def test_singly_str():
+    ll = SinglyLinkedList()
+    for v in [3, 2, 1]:
+        ll.push_front(v)
+    assert str(ll) == "1 -> 2 -> 3"
+
+
 # ── DoublyLinkedList-specific tests ──────────────────────────────────
 
 
@@ -165,3 +176,10 @@ def test_single_element_pop_back_clears_head(dll):
     assert dll.is_empty()
     with pytest.raises(LinkedListEmptyError):
         dll.peek_front()
+
+
+def test_doubly_str(dll):
+    dll.push_back(1)
+    dll.push_back(2)
+    dll.push_back(3)
+    assert str(dll) == "1 <-> 2 <-> 3"
diff --git a/tests/test_stacks.py b/tests/test_stacks.py
@@ -50,6 +50,16 @@ def test_peek_on_empty_raises(stack):
         stack.peek()
 
 
+def test_str(stack):
+    for v in [1, 2, 3]:
+        stack.push(v)
+    assert str(stack) == "3 -> 2 -> 1"
+
+
+def test_str_empty(stack):
+    assert str(stack) == "empty"
+
+
 # ── MinStack-specific tests ─────────────────────────────────────────
 
 
diff --git a/uv.lock b/uv.lock
