feat: add CI/CD, dev tooling, and Pythonic dunder methods

- Add GitHub Actions CI with lint and test jobs
- Add ruff (linter/formatter), ty (type checker), pytest-cov
- Add pre-commit hooks for ruff and ty
- Add __repr__, __len__, __contains__ to all data structures
- Add Comparable type bound to MinStack for type safety
- Update README with new tooling commands and requirements

Author: AzizAlievDevelopment

.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Ruff check
+        run: uv run ruff check .
+
+      - name: Ruff format check
+        run: uv run ruff format --check .
+
+      - name: Type check with ty
+        run: uv run ty check
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Run tests
+        run: uv run pytest tests/ -v

.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: local
+    hooks:
+      - id: ty
+        name: ty type check
+        entry: uv run ty check
+        language: system
+        types: [python]
+        pass_filenames: false

README.md

@@ -12,8 +12,8 @@ A collection of classic algorithms and data structures implemented in Python.
 | `MinStack` | Extends `ArrayStack` with O(1) `get_min()` tracking via an auxiliary stack. |
 
 ```python
-from data_structures.stacks.array_stack import ArrayStack
-from data_structures.stacks.min_stack import MinStack
+from data_structures.stack.array_stack import ArrayStack
+from data_structures.stack.min_stack import MinStack
 
 s = ArrayStack()
 s.push(1)
@@ -59,15 +59,28 @@ list(dll)         # [1, 2]
 
 - Python >= 3.13
 - [uv](https://docs.astral.sh/uv/) (package manager)
+- [ruff](https://docs.astral.sh/ruff/) (linter & formatter)
+- [ty](https://docs.astral.sh/ty/) (type checker)
+- [pre-commit](https://pre-commit.com/) (git hooks)
 
 ## Getting Started
 
 ```bash
 # Install dependencies
 uv sync --group dev
 
-# Run tests
+# Run tests (with coverage)
 uv run pytest tests/ -v
+
+# Lint & format
+uv run ruff check .
+uv run ruff format .
+
+# Type check
+uv run ty check
+
+# Run all pre-commit hooks
+uv run pre-commit run --all-files
 ```
 
 ## Project Structure
@@ -85,4 +98,6 @@ data_structures/
 tests/
   test_stacks.py           # pytest suite for stack implementations
   test_linked_lists.py     # pytest suite for linked list implementations
+.pre-commit-config.yaml    # pre-commit hooks (ruff, ty)
+pyproject.toml             # project config, tools settings
 ```

data_structures/linked_list/base.py

@@ -39,6 +39,18 @@ def size(self) -> int:
     def __iter__(self) -> Iterator[T]:
         """Iterate over all elements from head to tail."""
 
+    @abstractmethod
+    def __len__(self) -> int:
+        """Return the number of elements. O(1)."""
+
+    @abstractmethod
+    def __contains__(self, item: object) -> bool:
+        """Return ``True`` if *item* is in the list. O(n)."""
+
+    @abstractmethod
+    def __repr__(self) -> str:
+        """Return a string representation."""
+
 
 class IDoublyLinkedList[T](ISinglyLinkedList[T]):
     """Abstract Doubly Linked List interface.

data_structures/linked_list/doubly_linked_list.py

@@ -88,3 +88,12 @@ def __iter__(self) -> Iterator[T]:
         while node is not None:
             yield node.value
             node = node.next
+
+    def __len__(self) -> int:
+        return self._size
+
+    def __contains__(self, item: object) -> bool:
+        return any(v == item for v in self)
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({list(self)})"

data_structures/linked_list/singly_linked_list.py

@@ -46,3 +46,12 @@ def __iter__(self) -> Iterator[T]:
         while node is not None:
             yield node.value
             node = node.next
+
+    def __len__(self) -> int:
+        return self._size
+
+    def __contains__(self, item: object) -> bool:
+        return any(v == item for v in self)
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({list(self)})"

data_structures/stack/array_stack.py

@@ -25,3 +25,12 @@ def is_empty(self) -> bool:
 
     def size(self) -> int:
         return len(self._items)
+
+    def __len__(self) -> int:
+        return self.size()
+
+    def __contains__(self, item: object) -> bool:
+        return item in self._items
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({list(self._items)})"

data_structures/stack/base.py

@@ -40,3 +40,15 @@ def is_empty(self) -> bool:
     @abstractmethod
     def size(self) -> int:
         """Return the number of elements. O(1)."""
+
+    @abstractmethod
+    def __len__(self) -> int:
+        """Return the number of elements. O(1)."""
+
+    @abstractmethod
+    def __contains__(self, item: object) -> bool:
+        """Return ``True`` if *item* is in the stack. O(n)."""
+
+    @abstractmethod
+    def __repr__(self) -> str:
+        """Return a string representation."""

data_structures/stack/min_stack.py

@@ -1,8 +1,15 @@
+from typing import Protocol, runtime_checkable
+
 from .array_stack import ArrayStack
 from .base import StackEmptyError
 
 
-class MinStack[T](ArrayStack):
+@runtime_checkable
+class Comparable(Protocol):
+    def __lt__(self, other: "Comparable") -> bool: ...
+
+
+class MinStack[T: Comparable](ArrayStack):
     """ArrayStack that also tracks the minimum element in O(1)."""
 
     def __init__(self) -> None:

pyproject.toml

@@ -7,7 +7,20 @@ requires-python = ">=3.13"
 dependencies = []
 
 [dependency-groups]
-dev = ["pytest"]
+dev = [
+    "pre-commit>=4.5.1",
+    "pytest",
+    "pytest-cov>=7.0.0",
+    "ruff>=0.15.6",
+    "ty>=0.0.22",
+]
+
+[tool.ruff]
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]
 
 [tool.pytest.ini_options]
 pythonpath = ["."]
+addopts = "--cov=data_structures --cov-report=term-missing"