core-data-structures 1.2.1__tar.gz → 1.4.0__tar.gz

{core_data_structures-1.2.1 → core_data_structures-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: core-data-structures
-Version: 1.2.1
+Version: 1.4.0
 Summary: This project/library contains commons data structures...
 Author-email: Alejandro Cora González <alek.cora.glez@gmail.com>
 Maintainer: Alejandro Cora González
@@ -35,8 +35,8 @@ Dynamic: license-file
 core-data-structures
 ===============================================================================
 
-A Python library providing common data structures including graphs and trees,
-with built-in traversal and path-finding algorithms.
+A Python library providing common data structures including graphs, trees, and
+lists, with built-in traversal, path-finding, and search algorithms.
 
 ===============================================================================
 
@@ -82,6 +82,15 @@ Features
   - Recursive and iterative variants
   - Tree depth calculation
 
+- **Lists** — singly and doubly linked lists sharing a common ``IList``/``ILinkedList`` interface.
+
+  - Value-based CRUD: ``append``, ``prepend``, ``insert``, ``get``/``__getitem__``,
+    ``index``, ``pop``/``pop_front``/``pop_back``, ``remove`` (single or all occurrences)
+  - ``reverse``, ``extend``, ``clear``, ``to_list``/``from_list``
+  - ``__iter__``/``__contains__`` support, plus O(1) ``head``/``end`` node access
+  - ``DoubleLinkedList`` additionally maintains ``.prev`` links for backward traversal
+    and locates positions from whichever end (``head``/``end``) is closer
+
 
 Quick Start
 ===============================================================================

{core_data_structures-1.2.1 → core_data_structures-1.4.0}/README.rst

@@ -1,8 +1,8 @@
 core-data-structures
 ===============================================================================
 
-A Python library providing common data structures including graphs and trees,
-with built-in traversal and path-finding algorithms.
+A Python library providing common data structures including graphs, trees, and
+lists, with built-in traversal, path-finding, and search algorithms.
 
 ===============================================================================
 
@@ -48,6 +48,15 @@ Features
   - Recursive and iterative variants
   - Tree depth calculation
 
+- **Lists** — singly and doubly linked lists sharing a common ``IList``/``ILinkedList`` interface.
+
+  - Value-based CRUD: ``append``, ``prepend``, ``insert``, ``get``/``__getitem__``,
+    ``index``, ``pop``/``pop_front``/``pop_back``, ``remove`` (single or all occurrences)
+  - ``reverse``, ``extend``, ``clear``, ``to_list``/``from_list``
+  - ``__iter__``/``__contains__`` support, plus O(1) ``head``/``end`` node access
+  - ``DoubleLinkedList`` additionally maintains ``.prev`` links for backward traversal
+    and locates positions from whichever end (``head``/``end``) is closer
+
 
 Quick Start
 ===============================================================================

{core_data_structures-1.2.1 → core_data_structures-1.4.0}/core_data_structures.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: core-data-structures
-Version: 1.2.1
+Version: 1.4.0
 Summary: This project/library contains commons data structures...
 Author-email: Alejandro Cora González <alek.cora.glez@gmail.com>
 Maintainer: Alejandro Cora González
@@ -35,8 +35,8 @@ Dynamic: license-file
 core-data-structures
 ===============================================================================
 
-A Python library providing common data structures including graphs and trees,
-with built-in traversal and path-finding algorithms.
+A Python library providing common data structures including graphs, trees, and
+lists, with built-in traversal, path-finding, and search algorithms.
 
 ===============================================================================
 
@@ -82,6 +82,15 @@ Features
   - Recursive and iterative variants
   - Tree depth calculation
 
+- **Lists** — singly and doubly linked lists sharing a common ``IList``/``ILinkedList`` interface.
+
+  - Value-based CRUD: ``append``, ``prepend``, ``insert``, ``get``/``__getitem__``,
+    ``index``, ``pop``/``pop_front``/``pop_back``, ``remove`` (single or all occurrences)
+  - ``reverse``, ``extend``, ``clear``, ``to_list``/``from_list``
+  - ``__iter__``/``__contains__`` support, plus O(1) ``head``/``end`` node access
+  - ``DoubleLinkedList`` additionally maintains ``.prev`` links for backward traversal
+    and locates positions from whichever end (``head``/``end``) is closer
+
 
 Quick Start
 ===============================================================================

{core_data_structures-1.2.1 → core_data_structures-1.4.0}/core_data_structures.egg-info/SOURCES.txt

@@ -14,7 +14,10 @@ data_structures/graphs/__init__.py
 data_structures/graphs/graphs.py
 data_structures/graphs/vertex.py
 data_structures/lists/__init__.py
+data_structures/lists/base.py
+data_structures/lists/double_linked_list.py
 data_structures/lists/singly_linked_list.py
 data_structures/trees/__init__.py
+data_structures/trees/base.py
 data_structures/trees/binary_tree.py
 data_structures/trees/simple_tree.py

core_data_structures-1.4.0/data_structures/lists/base.py

@@ -0,0 +1,233 @@
+# -*- coding: utf-8 -*-
+
+"""Abstract interface shared by every list implementation in this package."""
+
+from abc import ABC
+from abc import abstractmethod
+from contextlib import suppress
+from typing import Generic, Iterator, Optional, TypeVar, cast
+
+from core_mixins.compatibility import Self
+
+from data_structures.base import Node as BaseNode
+from data_structures.base import T
+
+
+class Node(BaseNode[T]):
+    """Node with a reference to the next node, shared by every linked list."""
+
+    def __init__(
+        self,
+        value: Optional[T] = None,
+        next_node: Optional[Self] = None,
+    ) -> None:
+        super().__init__(value=value)
+        self._next = next_node
+
+    @property
+    def next(self) -> Optional[Self]:
+        """The next node in the list, if any."""
+        return self._next
+
+    @next.setter
+    def next(self, next_node: Optional[Self]) -> None:
+        self._next = next_node
+
+
+NodeT = TypeVar("NodeT", bound=Node)
+
+
+class IList(Generic[T], ABC):
+    """Abstract base class (interface) for all list implementations."""
+
+    def __init__(self, length: int = 0):
+        self._length = length
+
+    def __len__(self) -> int:
+        """Returns the length of the list."""
+        return self._length
+
+    def __getitem__(self, item: int) -> T:
+        """Returns the value at the given position."""
+        return self.get(item)
+
+    @abstractmethod
+    def __iter__(self) -> Iterator[T]:
+        """Iterates over the values in the list, starting from the head."""
+
+    def __contains__(self, item: T) -> bool:
+        """Returns whether the value is present in the list."""
+
+        with suppress(ValueError):
+            self.index(item)
+            return True
+
+        return False
+
+    @property
+    def length(self) -> int:
+        """The number of elements in the list."""
+        return self._length
+
+    @property
+    def is_empty(self) -> bool:
+        """Whether the list is empty."""
+        return self._length == 0
+
+    @classmethod
+    def from_list(cls, a_list: list) -> Self:
+        """Creates the list from a python list."""
+
+        new_list = cls()
+        for value in a_list:
+            new_list.append(value)
+
+        return new_list
+
+    def to_list(self) -> list:
+        """Materializes the list's values into a python list."""
+        return list(self)
+
+    def index(self, value: T) -> int:
+        """Returns the position of the first occurrence of the given value."""
+
+        for pos, value_ in enumerate(self):
+            if value_ == value:
+                return pos
+
+        raise ValueError(f"{value!r} is not in list")
+
+    @abstractmethod
+    def get(self, pos: int) -> T:
+        """Returns the value at the given position."""
+
+    @abstractmethod
+    def clear(self) -> None:
+        """Removes all nodes from the list."""
+
+    @abstractmethod
+    def prepend(self, value: T) -> None:
+        """Adds a value to the front of the list."""
+
+    @abstractmethod
+    def append(self, value: T) -> None:
+        """Adds a value to the end of the list."""
+
+    @abstractmethod
+    def insert(self, value: T, pos: int) -> None:
+        """Inserts a value at the given position."""
+
+    def extend(self, a_list: Self) -> None:
+        """Appends a copy of each value from another list."""
+
+        for value in list(a_list):
+            self.append(value)
+
+    def pop_front(self) -> T:
+        """Removes and returns the value at the front of the list."""
+
+        if self.is_empty:
+            raise IndexError("Empty list!")
+
+        return self._pop_front()
+
+    @abstractmethod
+    def _pop_front(self) -> T:
+        """Removes and returns the value at the front of a non-empty list."""
+
+    def pop_back(self) -> T:
+        """Removes and returns the value at the end of the list."""
+
+        if self.is_empty:
+            raise IndexError("Empty list!")
+
+        return self._pop_back()
+
+    @abstractmethod
+    def _pop_back(self) -> T:
+        """Removes and returns the value at the end of a non-empty list."""
+
+    def pop(self, index: int) -> T:
+        """Removes and returns the value at the given position."""
+
+        if index < 0 or index >= self._length:
+            raise IndexError("Index error!")
+
+        if index == 0:
+            return self.pop_front()
+
+        if index == self._length - 1:
+            return self.pop_back()
+
+        return self._pop_middle(index)
+
+    @abstractmethod
+    def _pop_middle(self, index: int) -> T:
+        """Removes and returns the value at an interior position (not the first or last)."""
+
+    @abstractmethod
+    def remove(self, value: T, all_values: bool = False) -> None:
+        """
+        Removes the first occurrence of the value, or all occurrences
+        if `all_values` is set.
+        """
+
+    @abstractmethod
+    def reverse(self) -> None:
+        """Reverses the list in place."""
+
+
+class ILinkedList(IList[T], Generic[T, NodeT], ABC):
+    """Interface for linked list implementations, parametrized by their node type."""
+
+    def __init__(self, value: Optional[T] = None) -> None:
+        self._head: Optional[NodeT] = (
+            None if value is None else self._create_node(value)
+        )
+
+        super().__init__(0 if value is None else 1)
+        self._end = self._head
+
+    def __iter__(self) -> Iterator[T]:
+        """Iterates over the values in the list, starting from the head."""
+
+        pointer = self._head
+        while pointer:
+            yield cast(T, pointer.value)
+            pointer = pointer.next
+
+    @classmethod
+    @abstractmethod
+    def _create_node(cls, value: T) -> NodeT:
+        """Creates a new, unlinked node of the concrete node type used by this list."""
+
+    @property
+    def head(self) -> Optional[NodeT]:
+        """The first node in the list."""
+        return self._head
+
+    @property
+    def end(self) -> Optional[NodeT]:
+        """The end node in the list."""
+        return self._end
+
+    def get(self, pos: int) -> T:
+        """Returns the value at the given position."""
+        return cast(T, self._node_at(pos).value)
+
+    def _node_at(self, pos: int) -> NodeT:
+        """Returns the actual node at the given position."""
+
+        if pos < 0 or pos >= self._length:
+            raise IndexError("Invalid position!")
+
+        return self._locate(pos)
+
+    @abstractmethod
+    def _locate(self, pos: int) -> NodeT:
+        """Returns the node at an already-validated position."""
+
+    def clear(self) -> None:
+        """Removes all nodes from the list."""
+        self._head = self._end = None
+        self._length = 0

core_data_structures-1.4.0/data_structures/lists/double_linked_list.py

@@ -0,0 +1,231 @@
+# -*- coding: utf-8 -*-
+
+"""
+A doubly linked list is a linear data structure composed of a sequence
+of nodes where each node contains data and pointers (or references) to
+both the next and the previous node, allowing traversal in either
+direction.
+"""
+
+# pylint: disable=duplicate-code
+# SinglyLinkedList and DoubleLinkedList are independent siblings under
+# ILinkedList rather than parent/child, so their mutators intentionally
+# don't share an implementation, even where the resulting code overlaps.
+
+from typing import Optional
+from typing import cast
+
+from core_mixins.compatibility import Self
+
+from data_structures.base import T
+from data_structures.lists.base import ILinkedList
+from data_structures.lists.base import Node as LinkedNode
+
+
+class Node(LinkedNode[T]):
+    """
+    Node in a double linked list, holding a value and the
+    references to the next and previous nodes.
+    """
+
+    def __init__(
+        self,
+        value: Optional[T] = None,
+        next_node: Optional[Self] = None,
+        prev_node: Optional[Self] = None,
+    ) -> None:
+        super().__init__(value=value, next_node=next_node)
+        self._prev = prev_node
+
+    @property
+    def prev(self) -> Optional[Self]:
+        """The previous node in the list, if any."""
+        return self._prev
+
+    @prev.setter
+    def prev(self, prev_node: Optional[Self]) -> None:
+        self._prev = prev_node
+
+
+class DoubleLinkedList(ILinkedList[T, Node[T]]):
+    """
+    Double linked list that tracks its head node and supports
+    forward and backward iteration. Positions are 0-indexed.
+    """
+
+    @classmethod
+    def _create_node(cls, value: T) -> Node[T]:
+        return Node(value)
+
+    def _locate(self, pos: int) -> Node[T]:
+        """Returns the node at an already-validated position."""
+
+        if self._length - 1 - pos <= pos:
+            pointer = cast(Node[T], self._end)
+            index = self._length - 1
+
+            while index > pos:
+                pointer = cast(Node[T], pointer.prev)
+                index -= 1
+
+        else:
+            pointer = cast(Node[T], self._head)
+            index = 0
+
+            while index < pos:
+                pointer = cast(Node[T], pointer.next)
+                index += 1
+
+        return pointer
+
+    def prepend(self, value: T) -> None:
+        """Adds a value to the front of the list."""
+
+        if self._head is None:
+            self.append(value)
+
+        else:
+            new_head = self._create_node(value)
+            new_head.next = self._head
+            self._head.prev = new_head
+            self._head = new_head
+            self._length += 1
+
+    def append(self, value: T) -> None:
+        """Adds a value to the end of the list."""
+
+        new_node = self._create_node(value)
+
+        if self._end is None:
+            self._head = new_node
+        else:
+            self._end.next = new_node
+            new_node.prev = self._end
+
+        self._end = new_node
+        self._length += 1
+
+    def insert(self, value: T, pos: int) -> None:
+        """Inserts a value at the given position."""
+
+        if pos == 0:
+            self.prepend(value)
+
+        elif pos == self._length:
+            self.append(value)
+
+        else:
+            pointer = self._node_at(pos - 1)
+            old_next = pointer.next
+
+            new_node = self._create_node(value)
+            new_node.next = old_next
+            new_node.prev = pointer
+            cast(Node[T], old_next).prev = new_node
+
+            pointer.next = new_node
+            self._length += 1
+
+    def _pop_front(self) -> T:
+        """Removes and returns the value at the front of a non-empty list."""
+
+        head = cast(Node[T], self._head)
+        value = cast(T, head.value)
+
+        if self._length == 1:
+            self._head = None
+            self._end = None
+        else:
+            self._head = head.next
+            cast(Node[T], self._head).prev = None
+
+        self._length -= 1
+        return value
+
+    def _pop_back(self) -> T:
+        """Removes and returns the value at the end of a non-empty list."""
+
+        end = cast(Node[T], self._end)
+        value = cast(T, end.value)
+
+        if self._length == 1:
+            self.clear()
+            return value
+
+        self._end = end.prev
+        cast(Node[T], self._end).next = None
+        self._length -= 1
+        return value
+
+    def _pop_middle(self, index: int) -> T:
+        """Removes and returns the value at an interior position (not the first or last)."""
+
+        removed = self._node_at(index)
+        prev_node = cast(Node[T], removed.prev)
+        next_node = cast(Node[T], removed.next)
+
+        prev_node.next = next_node
+        next_node.prev = prev_node
+
+        self._length -= 1
+        return cast(T, removed.value)
+
+    def remove(self, value: T, all_values: bool = False) -> None:
+        """
+        Removes the first occurrence of the value, or all occurrences
+        if `all_values` is set.
+        """
+
+        was_found = False
+
+        while self._head is not None and self._head.value == value:
+            self._head = self._head.next
+            self._length -= 1
+            was_found = True
+
+            if self._head is None:
+                self._end = None
+            else:
+                self._head.prev = None
+
+            if not all_values:
+                return
+
+        pointer = self._head
+        while pointer is not None:
+            if pointer.value == value:
+                prev_node = cast(Node[T], pointer.prev)
+                next_node = pointer.next
+
+                prev_node.next = next_node
+                if next_node is not None:
+                    next_node.prev = prev_node
+
+                if pointer is self._end:
+                    self._end = prev_node
+
+                self._length -= 1
+                was_found = True
+                pointer = next_node
+
+                if not all_values:
+                    return
+
+            else:
+                pointer = pointer.next
+
+        if not was_found:
+            raise ValueError(f"{value!r} is not in list")
+
+    def reverse(self) -> None:
+        """Reverses the list in place."""
+
+        if self.is_empty or self._length == 1:
+            return
+
+        pointer = self._head
+        while pointer is not None:
+            pointer.next, pointer.prev = pointer.prev, pointer.next
+            pointer = pointer.prev
+
+        self._head, self._end = self._end, self._head