feat: add linked list implementations and rename stack module

- Add SinglyLinkedList and DoublyLinkedList abstract interfaces
- Add SinglyLinkedListImpl and DoublyLinkedListImpl implementations
- Add tests for both linked list types (32 tests)
- Rename stacks/ to stack/ for consistency
- Update README with linked list docs and project structure

Author: AzizAlievDevelopment

README.md

@@ -29,6 +29,32 @@ ms.push(7)
 ms.get_min()  # 3
 ```
 
+### Linked Lists
+
+| Implementation | Description |
+|---|---|
+| `SinglyLinkedListImpl` | Singly linked list with O(1) push/pop at the head. |
+| `DoublyLinkedListImpl` | Doubly linked list with O(1) push/pop at both head and tail. |
+
+```python
+from data_structures.linked_list import SinglyLinkedListImpl, DoublyLinkedListImpl
+
+sll = SinglyLinkedListImpl()
+sll.push_front(1)
+sll.push_front(2)
+sll.peek_front()  # 2
+sll.pop_front()   # 2
+list(sll)         # [1]
+
+dll = DoublyLinkedListImpl()
+dll.push_front(1)
+dll.push_back(2)
+dll.push_back(3)
+dll.peek_back()   # 3
+dll.pop_back()    # 3
+list(dll)         # [1, 2]
+```
+
 ## Requirements
 
 - Python >= 3.13
@@ -48,10 +74,15 @@ uv run pytest tests/ -v
 
 ```
 data_structures/
-  stacks/
+  stack/
     base.py          # Stack ABC and StackEmptyError
     array_stack.py   # ArrayStack implementation
     min_stack.py     # MinStack implementation
+  linked_list/
+    base.py                # SinglyLinkedList & DoublyLinkedList ABCs
+    singly_linked_list.py  # SinglyLinkedListImpl
+    doubly_linked_list.py  # DoublyLinkedListImpl
 tests/
-  test_stacks.py     # pytest suite for all stack implementations
+  test_stacks.py           # pytest suite for stack implementations
+  test_linked_lists.py     # pytest suite for linked list implementations
 ```

data_structures/linked_list/__init__.py

@@ -0,0 +1,11 @@
+from .base import DoublyLinkedList, LinkedListEmptyError, SinglyLinkedList
+from .doubly_linked_list import DoublyLinkedListImpl
+from .singly_linked_list import SinglyLinkedListImpl
+
+__all__ = [
+    "DoublyLinkedList",
+    "DoublyLinkedListImpl",
+    "LinkedListEmptyError",
+    "SinglyLinkedList",
+    "SinglyLinkedListImpl",
+]

data_structures/linked_list/base.py

@@ -0,0 +1,60 @@
+from abc import ABC, abstractmethod
+from typing import Iterator
+
+
+class LinkedListEmptyError(Exception):
+    """Raised when attempting to access an element from an empty linked list."""
+
+    def __init__(self) -> None:
+        super().__init__("Linked list is empty")
+
+
+class SinglyLinkedList[T](ABC):
+    """Abstract Singly Linked List interface.
+
+    Each node holds a reference only to the *next* node.
+    """
+
+    @abstractmethod
+    def push_front(self, item: T) -> None:
+        """Insert *item* at the head. O(1)."""
+
+    @abstractmethod
+    def pop_front(self) -> T:
+        """Remove and return the head element. O(1)."""
+
+    @abstractmethod
+    def peek_front(self) -> T:
+        """Return the head element without removing it. O(1)."""
+
+    @abstractmethod
+    def is_empty(self) -> bool:
+        """Return ``True`` if the list contains no elements. O(1)."""
+
+    @abstractmethod
+    def size(self) -> int:
+        """Return the number of elements. O(1)."""
+
+    @abstractmethod
+    def __iter__(self) -> Iterator[T]:
+        """Iterate over all elements from head to tail."""
+
+
+class DoublyLinkedList[T](SinglyLinkedList[T]):
+    """Abstract Doubly Linked List interface.
+
+    Each node holds references to both *next* and *prev* nodes.
+    Adds O(1) tail operations on top of ``SinglyLinkedList``.
+    """
+
+    @abstractmethod
+    def push_back(self, item: T) -> None:
+        """Insert *item* at the tail. O(1)."""
+
+    @abstractmethod
+    def pop_back(self) -> T:
+        """Remove and return the tail element. O(1)."""
+
+    @abstractmethod
+    def peek_back(self) -> T:
+        """Return the tail element without removing it. O(1)."""

data_structures/linked_list/doubly_linked_list.py

@@ -0,0 +1,90 @@
+from typing import Iterator
+
+from .base import DoublyLinkedList, LinkedListEmptyError
+
+
+class _Node[T]:
+    __slots__ = ("value", "prev", "next")
+
+    def __init__(
+        self,
+        value: T,
+        prev: "_Node[T] | None" = None,
+        next: "_Node[T] | None" = None,
+    ) -> None:
+        self.value = value
+        self.prev = prev
+        self.next = next
+
+
+class DoublyLinkedListImpl[T](DoublyLinkedList[T]):
+    """Doubly linked list backed by ``_Node`` objects."""
+
+    def __init__(self) -> None:
+        self._head: _Node[T] | None = None
+        self._tail: _Node[T] | None = None
+        self._size: int = 0
+
+    def push_front(self, item: T) -> None:
+        node = _Node(item, next=self._head)
+        if self._head is not None:
+            self._head.prev = node
+        else:
+            self._tail = node
+        self._head = node
+        self._size += 1
+
+    def pop_front(self) -> T:
+        if self._head is None:
+            raise LinkedListEmptyError
+        value = self._head.value
+        self._head = self._head.next
+        if self._head is not None:
+            self._head.prev = None
+        else:
+            self._tail = None
+        self._size -= 1
+        return value
+
+    def peek_front(self) -> T:
+        if self._head is None:
+            raise LinkedListEmptyError
+        return self._head.value
+
+    def push_back(self, item: T) -> None:
+        node = _Node(item, prev=self._tail)
+        if self._tail is not None:
+            self._tail.next = node
+        else:
+            self._head = node
+        self._tail = node
+        self._size += 1
+
+    def pop_back(self) -> T:
+        if self._tail is None:
+            raise LinkedListEmptyError
+        value = self._tail.value
+        self._tail = self._tail.prev
+        if self._tail is not None:
+            self._tail.next = None
+        else:
+            self._head = None
+        self._size -= 1
+        return value
+
+    def peek_back(self) -> T:
+        if self._tail is None:
+            raise LinkedListEmptyError
+        return self._tail.value
+
+    def is_empty(self) -> bool:
+        return self._size == 0
+
+    def size(self) -> int:
+        return self._size
+
+    def __iter__(self) -> Iterator[T]:
+        node = self._head
+        while node is not None:
+            yield node.value
+            node = node.next

data_structures/linked_list/singly_linked_list.py

@@ -0,0 +1,48 @@
+from typing import Iterator
+
+from .base import LinkedListEmptyError, SinglyLinkedList
+
+
+class _Node[T]:
+    __slots__ = ("value", "next")
+
+    def __init__(self, value: T, next: "_Node[T] | None" = None) -> None:
+        self.value = value
+        self.next = next
+
+
+class SinglyLinkedListImpl[T](SinglyLinkedList[T]):
+    """Singly linked list backed by ``_Node`` objects."""
+
+    def __init__(self) -> None:
+        self._head: _Node[T] | None = None
+        self._size: int = 0
+
+    def push_front(self, item: T) -> None:
+        self._head = _Node(item, self._head)
+        self._size += 1
+
+    def pop_front(self) -> T:
+        if self._head is None:
+            raise LinkedListEmptyError
+        value = self._head.value
+        self._head = self._head.next
+        self._size -= 1
+        return value
+
+    def peek_front(self) -> T:
+        if self._head is None:
+            raise LinkedListEmptyError
+        return self._head.value
+
+    def is_empty(self) -> bool:
+        return self._size == 0
+
+    def size(self) -> int:
+        return self._size
+
+    def __iter__(self) -> Iterator[T]:
+        node = self._head
+        while node is not None:
+            yield node.value
+            node = node.next