pure-python-ds 1.0.0__py3-none-any.whl

pure_python_ds/algorithms/__init__.py

@@ -0,0 +1,3 @@
+from .sorting import merge_sort
+from .searching import binary_search
+from .dp import fibonacci

pure_python_ds/algorithms/dp.py

@@ -0,0 +1,16 @@
+from typing import Dict
+
+def fibonacci(n: int, memo: Dict[int, int] = None) -> int:
+    """
+    Computes the nth Fibonacci number using Top-Down DP (Memoization).
+    O(n) time complexity vs O(2^n) recursive complexity.
+    """
+    if memo is None:
+        memo = {}
+    if n in memo:
+        return memo[n]
+    if n <= 1:
+        return n
+    
+    memo[n] = fibonacci(n - 1, memo) + fibonacci(n - 2, memo)
+    return memo[n]

pure_python_ds/algorithms/searching.py

@@ -0,0 +1,22 @@
+from typing import List, TypeVar, Optional, Any
+
+T = TypeVar('T')
+
+def binary_search(arr: List[Any], target: Any) -> int:
+    """
+    Performs an iterative binary search on a sorted list.
+    Returns the index of the target if found, else -1.
+    """
+    low = 0
+    high = len(arr) - 1
+    
+    while low <= high:
+        mid = (low + high) // 2
+        if arr[mid] == target:
+            return mid
+        elif arr[mid] < target:
+            low = mid + 1
+        else:
+            high = mid - 1
+            
+    return -1

pure_python_ds/algorithms/sorting.py

@@ -0,0 +1,36 @@
+from typing import List, TypeVar
+
+T = TypeVar('T')
+
+def merge_sort(arr: List[T]) -> List[T]:
+    """
+    Perform an O(n log n) Merge Sort on a list.
+    Returns a new sorted list.
+    """
+    if len(arr) <= 1:
+        return arr
+
+    mid = len(arr) // 2
+    # Recursive split
+    left = merge_sort(arr[:mid])
+    right = merge_sort(arr[mid:])
+
+    return _merge(left, right)
+
+def _merge(left: List[T], right: List[T]) -> List[T]:
+    """Helper method to merge two sorted lists into one."""
+    result = []
+    i = j = 0
+
+    while i < len(left) and j < len(right):
+        if left[i] < right[j]:
+            result.append(left[i])
+            i += 1
+        else:
+            result.append(right[j])
+            j += 1
+
+    # Add remaining elements
+    result.extend(left[i:])
+    result.extend(right[j:])
+    return result

pure_python_ds/graphs/__init__.py

@@ -0,0 +1,2 @@
+from .graph import Graph
+from .dsu import DSU

pure_python_ds/graphs/dsu.py

@@ -0,0 +1,22 @@
+class DSU:
+    def __init__(self, n: int):
+        self.parent = list(range(n))
+        self.rank = [0] * n
+
+    def find(self, i: int) -> int:
+        if self.parent[i] == i:
+            return i
+        self.parent[i] = self.find(self.parent[i]) # Path Compression
+        return self.parent[i]
+
+    def union(self, i: int, j: int):
+        root_i = self.find(i)
+        root_j = self.find(j)
+        if root_i != root_j:
+            if self.rank[root_i] < self.rank[root_j]:
+                self.parent[root_i] = root_j
+            elif self.rank[root_i] > self.rank[root_j]:
+                self.parent[root_j] = root_i
+            else:
+                self.parent[root_i] = root_j
+                self.rank[root_j] += 1

pure_python_ds/graphs/graph.py

@@ -0,0 +1,106 @@
+from typing import Generic, TypeVar, Optional, Set, Dict, List, Tuple
+import heapq # We'll use Python's built-in min-heap for O(log n) efficiency here
+
+T = TypeVar('T')
+
+class Graph(Generic[T]):
+    def __init__(self, directed: bool = False):
+        # Updated to store {vertex: {neighbor: weight}}
+        self._adj_list: Dict[T, Dict[T, float]] = {}
+        self.directed = directed
+
+    def add_vertex(self, vertex: T) -> None:
+        if vertex not in self._adj_list:
+            self._adj_list[vertex] = {}
+
+    def add_edge(self, v1: T, v2: T, weight: float = 1.0) -> None:
+        """Adds a weighted edge. Defaults to 1.0 if not specified."""
+        self.add_vertex(v1)
+        self.add_vertex(v2)
+        self._adj_list[v1][v2] = weight
+        if not self.directed:
+            self._adj_list[v2][v1] = weight
+
+    def dijkstra(self, start: T) -> Dict[T, float]:
+        """
+        Greedy algorithm to find the shortest distance from 'start' to all other nodes.
+        Returns a dictionary of {vertex: min_distance}.
+        """
+        # Distances from start to all other nodes are initially infinity
+        distances = {vertex: float('inf') for vertex in self._adj_list}
+        distances[start] = 0
+        
+        # Priority Queue: (distance, vertex)
+        pq = [(0, start)]
+        
+        while pq:
+            current_distance, current_vertex = heapq.heappop(pq)
+
+            # If we found a longer path than we already recorded, skip it
+            if current_distance > distances[current_vertex]:
+                continue
+
+            for neighbor, weight in self._adj_list[current_vertex].items():
+                distance = current_distance + weight
+
+                # If this path is shorter, update and push to PQ
+                if distance < distances[neighbor]:
+                    distances[neighbor] = distance
+                    heapq.heappush(pq, (distance, neighbor))
+                    
+        return distances
+    def kruskal_mst(self) -> List[Tuple[T, T, float]]:
+        """
+        Finds the Minimum Spanning Tree using the library's DSU module.
+        Returns a list of edges (v1, v2, weight) in the MST.
+        """
+        from pure_python_ds.graphs import DSU
+        
+        edges = []
+        # Gather all unique edges
+        for u in self._adj_list:
+            for v, weight in self._adj_list[u].items():
+                if self.directed or (v, u, weight) not in edges:
+                    edges.append((u, v, weight))
+        
+        # Sort edges by weight
+        edges.sort(key=lambda x: x[2])
+        
+        # Map vertices to integers for DSU
+        nodes = list(self._adj_list.keys())
+        node_to_idx = {node: i for i, node in enumerate(nodes)}
+        
+        dsu = DSU(len(nodes))
+        mst = []
+        
+        for u, v, weight in edges:
+            if dsu.find(node_to_idx[u]) != dsu.find(node_to_idx[v]):
+                dsu.union(node_to_idx[u], node_to_idx[v])
+                mst.append((u, v, weight))
+                
+        return mst
+    def bellman_ford(self, start: T) -> Dict[T, float]:
+        """
+        Shortest path algorithm that handles negative weights.
+        Returns distances or raises ValueError if a negative cycle is found.
+        """
+        distances = {vertex: float('inf') for vertex in self._adj_list}
+        distances[start] = 0
+        
+        # Relax edges |V| - 1 times
+        for _ in range(len(self._adj_list) - 1):
+            for u in self._adj_list:
+                for v, weight in self._adj_list[u].items():
+                    if distances[u] + weight < distances[v]:
+                        distances[v] = distances[u] + weight
+                        
+        # Check for negative cycles
+        for u in self._adj_list:
+            for v, weight in self._adj_list[u].items():
+                if distances[u] + weight < distances[v]:
+                    raise ValueError("Graph contains a negative weight cycle")
+                    
+        return distances
+    def has_edge(self, u: T, v: T) -> bool:
+        """Returns True if there is an edge from u to v."""
+        return u in self._adj_list and v in self._adj_list[u]

pure_python_ds/linear/__init__.py

@@ -0,0 +1,6 @@
+from .singly_linked_list import SinglyLinkedList
+from .doubly_linked_list import DoublyLinkedList
+from .stack import Stack
+from .queue import Queue
+from .heap import MinHeap, MaxHeap
+from .hash_table import HashTable

pure_python_ds/linear/doubly_linked_list.py

@@ -0,0 +1,91 @@
+from typing import Generic, TypeVar, Optional, Generator
+from pure_python_ds.nodes import ListNode
+
+T = TypeVar('T')
+
+class DoublyLinkedList(Generic[T]):
+    """A strictly typed, memory-optimized Doubly Linked List."""
+    
+    def __init__(self):
+        self.head: Optional[ListNode[T]] = None
+        self.tail: Optional[ListNode[T]] = None
+        self._length: int = 0
+
+    def __len__(self) -> int:
+        return self._length
+
+    def append(self, value: T) -> None:
+        """Adds a node to the end in O(1) time."""
+        new_node = ListNode(value)
+        if not self.head or not self.tail:
+            self.head = new_node
+            self.tail = new_node
+        else:
+            self.tail.next = new_node
+            new_node.prev = self.tail
+            self.tail = new_node
+        self._length += 1
+
+    def prepend(self, value: T) -> None:
+        """Adds a node to the beginning in O(1) time."""
+        new_node = ListNode(value)
+        if not self.head or not self.tail:
+            self.head = new_node
+            self.tail = new_node
+        else:
+            new_node.next = self.head
+            self.head.prev = new_node
+            self.head = new_node
+        self._length += 1
+
+    def remove_tail(self) -> Optional[T]:
+        """Removes the last node in O(1) time (Impossible in Singly Linked Lists!)."""
+        if not self.tail:
+            return None
+            
+        value = self.tail.value
+        if self.head is self.tail: # Only one element
+            self.head = None
+            self.tail = None
+        else:
+            self.tail = self.tail.prev
+            self.tail.next = None # Sever the tie
+            
+        self._length -= 1
+        return value
+
+    def __iter__(self) -> Generator[T, None, None]:
+        """Forward generator traversal."""
+        current = self.head
+        while current:
+            yield current.value
+            current = current.next
+
+    def __str__(self) -> str:
+        """Visual representation showing bidirectional pointers."""
+        values = [str(val) for val in self]
+        return "None <- " + " <-> ".join(values) + " -> None" if values else "Empty List"
+    def remove(self, value: T):
+        """Removes the first occurrence of value from the list."""
+        current = self.head
+        while current:
+            if current.value == value:
+                # If it's the head
+                if current == self.head:
+                    self.head = current.next
+                    if self.head:
+                        self.head.prev = None
+                    else:
+                        self.tail = None
+                # If it's the tail
+                elif current == self.tail:
+                    self.tail = current.prev
+                    if self.tail:
+                        self.tail.next = None
+                # If it's in the middle
+                else:
+                    current.prev.next = current.next
+                    current.next.prev = current.prev
+                return True
+            current = current.next
+        return False

pure_python_ds/linear/hash_table.py

@@ -0,0 +1,33 @@
+from typing import Any, List, Optional
+from pure_python_ds.linear.singly_linked_list import SinglyLinkedList
+
+class HashTable:
+    def __init__(self, size: int = 10):
+        self.size = size
+        self.table: List[Optional[SinglyLinkedList]] = [None] * size
+
+    def _hash(self, key: str) -> int:
+        return sum(ord(char) for char in key) % self.size
+
+    def set(self, key: str, value: Any):
+        index = self._hash(key)
+        if not self.table[index]:
+            self.table[index] = SinglyLinkedList()
+        
+        # Check if key exists to update, else append
+        current = self.table[index].head
+        while current:
+            if current.value[0] == key:
+                current.value = (key, value)
+                return
+            current = current.next
+        self.table[index].append((key, value))
+
+    def get(self, key: str) -> Any:
+        index = self._hash(key)
+        if not self.table[index]: return None
+        current = self.table[index].head
+        while current:
+            if current.value[0] == key: return current.value[1]
+            current = current.next
+        return None

pure_python_ds/linear/heap.py

@@ -0,0 +1,102 @@
+from typing import List, TypeVar, Generic, Optional
+
+T = TypeVar('T')
+
+class MinHeap(Generic[T]):
+    def __init__(self):
+        self.heap: List[T] = []
+
+    def push(self, val: T) -> None:
+        self.heap.append(val)
+        self._bubble_up(len(self.heap) - 1)
+
+    def pop(self) -> Optional[T]:
+        if len(self.heap) == 0: return None
+        if len(self.heap) == 1: return self.heap.pop()
+        
+        root = self.heap[0]
+        self.heap[0] = self.heap.pop()
+        self._bubble_down(0)
+        return root
+
+    def _bubble_up(self, index: int):
+        parent = (index - 1) // 2
+        # Min-Heap check: Child < Parent
+        if index > 0 and self.heap[index] < self.heap[parent]:
+            self.heap[index], self.heap[parent] = self.heap[parent], self.heap[index]
+            self._bubble_up(parent)
+
+    def _bubble_down(self, index: int):
+        smallest = index
+        left, right = 2 * index + 1, 2 * index + 2
+        
+        for child in [left, right]:
+            if child < len(self.heap) and self.heap[child] < self.heap[smallest]:
+                smallest = child
+        
+        if smallest != index:
+            self.heap[index], self.heap[smallest] = self.heap[smallest], self.heap[index]
+            self._bubble_down(smallest)
+
+    @property
+    def size(self) -> int:
+        return len(self.heap)
+    @classmethod
+    def heapify(cls, data: List[T]) -> 'MinHeap[T]':
+        """Transforms an unsorted list into a MinHeap in O(n) time."""
+        instance = cls()
+        instance.heap = list(data)
+        for i in range(len(instance.heap) // 2 - 1, -1, -1):
+            instance._bubble_down(i)
+        return instance
+
+class MaxHeap(Generic[T]):
+    """Native Max-Heap to avoid negating values for heapq-like logic."""
+    def __init__(self):
+        self.heap: List[T] = []
+
+    def push(self, val: T) -> None:
+        self.heap.append(val)
+        self._bubble_up(len(self.heap) - 1)
+
+    def pop(self) -> Optional[T]:
+        if len(self.heap) == 0: return None
+        if len(self.heap) == 1: return self.heap.pop()
+        
+        root = self.heap[0]
+        self.heap[0] = self.heap.pop()
+        self._bubble_down(0)
+        return root
+
+    def _bubble_up(self, index: int):
+        parent = (index - 1) // 2
+        # Max-Heap check: Child > Parent
+        if index > 0 and self.heap[index] > self.heap[parent]:
+            self.heap[index], self.heap[parent] = self.heap[parent], self.heap[index]
+            self._bubble_up(parent)
+
+    def _bubble_down(self, index: int):
+        largest = index
+        left, right = 2 * index + 1, 2 * index + 2
+        
+        for child in [left, right]:
+            # Max-Heap check: Child > Parent
+            if child < len(self.heap) and self.heap[child] > self.heap[largest]:
+                largest = child
+        
+        if largest != index:
+            self.heap[index], self.heap[largest] = self.heap[largest], self.heap[index]
+            self._bubble_down(largest)
+
+    @property
+    def size(self) -> int:
+        return len(self.heap)
+
+    @classmethod
+    def heapify(cls, data: List[T]) -> 'MaxHeap[T]':
+        """Transforms an unsorted list into a MaxHeap in O(n) time."""
+        instance = cls()
+        instance.heap = list(data)
+        for i in range(len(instance.heap) // 2 - 1, -1, -1):
+            instance._bubble_down(i)
+        return instance

pure_python_ds/linear/queue.py

@@ -0,0 +1,24 @@
+from typing import Generic, TypeVar, Optional
+from pure_python_ds.linear.singly_linked_list import SinglyLinkedList
+
+T = TypeVar('T')
+
+class Queue(Generic[T]):
+    """A strictly typed, memory-optimized Queue (FIFO)."""
+    
+    def __init__(self):
+        self._container = SinglyLinkedList[T]()
+
+    def __len__(self) -> int:
+        return len(self._container)
+
+    def enqueue(self, value: T) -> None:
+        """Adds an item to the back of the queue in O(1) time."""
+        self._container.append(value)
+
+    def dequeue(self) -> Optional[T]:
+        """Removes and returns the front item in O(1) time."""
+        return self._container.remove_head()
+        
+    def __str__(self) -> str:
+        return f"Queue Front -> {self._container}"

pure_python_ds/linear/singly_linked_list.py

@@ -0,0 +1,106 @@
+from typing import Generic, TypeVar, Optional, Generator
+from pure_python_ds.nodes import ListNode
+
+# Define the generic type variable
+T = TypeVar('T')
+
+class SinglyLinkedList(Generic[T]):
+    """
+    A strictly typed, memory-optimized Singly Linked List.
+    """
+    def __init__(self):
+        self.head: Optional[ListNode[T]] = None
+        self.tail: Optional[ListNode[T]] = None
+        self._length: int = 0
+        
+    def __str__(self) -> str:
+        """
+        Provides a visual representation of the Linked List.
+        Example: Future -> Systems -> Architect -> None
+        """
+        # We leverage our own generator to seamlessly loop through the values
+        values = [str(node_val) for node_val in self]
+        values.append("None")
+        return " -> ".join(values)
+    def __len__(self) -> int:
+        """Allows the user to call len(linked_list) in O(1) time."""
+        return self._length
+
+    def append(self, value: T) -> None:
+        """Adds a new node to the end of the list in O(1) time."""
+        new_node = ListNode(value)
+        if not self.head or not self.tail:
+            self.head = new_node
+            self.tail = new_node
+        else:
+            self.tail.next = new_node
+            self.tail = new_node
+        self._length += 1
+
+    def prepend(self, value: T) -> None:
+        """Adds a new node to the beginning of the list in O(1) time."""
+        new_node = ListNode(value)
+        if not self.head or not self.tail:
+            self.head = new_node
+            self.tail = new_node
+        else:
+            new_node.next = self.head
+            self.head = new_node
+        self._length += 1
+
+    def __iter__(self) -> Generator[T, None, None]:
+        """
+        Generator-based traversal. 
+        Allows users to run: `for val in linked_list:` with O(1) memory overhead.
+        """
+        current = self.head
+        while current:
+            yield current.value
+            current = current.next
+    def remove_head(self) -> Optional[T]:
+        """Removes and returns the first node's value in O(1) time."""
+        if not self.head:
+            return None
+        
+        value = self.head.value
+        self.head = self.head.next
+        self._length -= 1
+        
+        if self._length == 0:
+            self.tail = None  
+            
+        return value
+    def reverse(self):
+        """Reverses the list in O(n) time and O(1) space."""
+        prev = None
+        current = self.head
+        while current:
+            next_node = current.next
+            current.next = prev
+            prev = current
+            current = next_node
+        self.head = prev
+    def search(self, value: T) -> bool:
+        """Returns True if value exists in the list, else False."""
+        current = self.head
+        while current:
+            if current.value == value:
+                return True
+            current = current.next
+        return False
+    def remove(self, value: T) -> bool:
+        """Removes the first occurrence of value from the list."""
+        if not self.head:
+            return False
+            
+        if self.head.value == value:
+            self.head = self.head.next
+            return True
+            
+        current = self.head
+        while current.next:
+            if current.next.value == value:
+                current.next = current.next.next
+                return True
+            current = current.next
+        return False

pure_python_ds/linear/stack.py

@@ -0,0 +1,28 @@
+from typing import Generic, TypeVar, Optional
+from pure_python_ds.linear.singly_linked_list import SinglyLinkedList
+
+T = TypeVar('T')
+
+class Stack(Generic[T]):
+    """A strictly typed, memory-optimized Stack (LIFO)."""
+    
+    def __init__(self):
+        self._container = SinglyLinkedList[T]()
+
+    def __len__(self) -> int:
+        return len(self._container)
+
+    def push(self, value: T) -> None:
+        """Pushes an item onto the top of the stack in O(1) time."""
+        self._container.prepend(value)
+
+    def pop(self) -> Optional[T]:
+        """Removes and returns the top item in O(1) time."""
+        return self._container.remove_head()
+        
+    def __str__(self) -> str:
+        return f"Stack Top -> {self._container}"
+    def peek(self) -> Optional[T]:
+        if not self._container.head:
+            return None
+        return self._container.head.value

pure_python_ds/nodes/__init__.py

@@ -0,0 +1,25 @@
+from typing import Generic, TypeVar, Optional, Dict
+
+T = TypeVar('T')
+
+class ListNode(Generic[T]):
+    __slots__ = ['value', 'next', 'prev']
+    def __init__(self, value: T):
+        self.value: T = value
+        self.next: Optional['ListNode[T]'] = None
+        self.prev: Optional['ListNode[T]'] = None
+
+class TreeNode(Generic[T]):
+    __slots__ = ['value', 'left', 'right', 'height']
+    def __init__(self, value: T):
+        self.value: T = value
+        self.left: Optional['TreeNode[T]'] = None
+        self.right: Optional['TreeNode[T]'] = None
+        self.height: int = 1 
+
+class TrieNode:
+    # FIXED: Added is_end_of_word to slots and init
+    __slots__ = ['children', 'is_end_of_word']
+    def __init__(self):
+        self.children: Dict[str, 'TrieNode'] = {}
+        self.is_end_of_word: bool = False

pure_python_ds/nodes/b_tree_node.py

@@ -0,0 +1,9 @@
+from typing import List, Any, Optional
+
+class BTreeNode:
+    __slots__ = ['keys', 'children', 'leaf']
+    
+    def __init__(self, leaf: bool = False):
+        self.keys: List[Any] = []
+        self.children: List['BTreeNode'] = []
+        self.leaf = leaf

pure_python_ds/nodes/rb_node.py

@@ -0,0 +1,16 @@
+from enum import Enum
+from typing import Any, Optional
+
+class Color(Enum):
+    RED = 0
+    BLACK = 1
+
+class RBNode:
+    __slots__ = ['value', 'left', 'right', 'parent', 'color']
+    
+    def __init__(self, value: Any):
+        self.value = value
+        self.left: Optional['RBNode'] = None
+        self.right: Optional['RBNode'] = None
+        self.parent: Optional['RBNode'] = None
+        self.color = Color.RED

pure_python_ds/trees/__init__.py

@@ -0,0 +1,7 @@
+from .binary_tree import BinaryTree  # Add this line
+from .binary_search_tree import BinarySearchTree
+from .avl_tree import AVLTree
+from .trie import Trie
+from .segment_tree import SegmentTree
+from .red_black_tree import RedBlackTree
+from .b_tree import BTree