Fix, modernize and improve all Python graph examples (#26)

* Initial plan

* Modernize and fix Python graph examples with type hints, docstrings, and improvements

Co-authored-by: djeada <37275728+djeada@users.noreply.github.com>

* Modernize Python collections with type hints, docstrings, and fix SyntaxWarnings

Co-authored-by: djeada <37275728+djeada@users.noreply.github.com>

* Fix Heap __copy__ method to properly copy the comparison function

Co-authored-by: djeada <37275728+djeada@users.noreply.github.com>

* Modernize Python brain teaser examples with type hints, docstrings, and improvements

Co-authored-by: djeada <37275728+djeada@users.noreply.github.com>

* Fix LRU cache bug: nodes now store key-value pairs for correct eviction

Co-authored-by: djeada <37275728+djeada@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: djeada <37275728+djeada@users.noreply.github.com>

Author: Copilot

src/brain_teasers/python/add_string_numbers/src/add_string_numbers.py

@@ -1,5 +1,22 @@
+"""Add two numbers represented as strings, supporting decimals."""
+
+from __future__ import annotations
+
+
 def add_string_numbers(s1: str, s2: str) -> str:
+    """
+    Add two numbers represented as strings.
+
+    Supports both integers and decimal numbers. Handles arbitrarily large numbers
+    that would overflow standard integer types.
 
+    Args:
+        s1: First number as a string.
+        s2: Second number as a string.
+
+    Returns:
+        The sum of the two numbers as a string.
+    """
     decimal_places = 0
 
     def is_float(s: str) -> bool:
@@ -9,10 +26,10 @@ def number_of_decimal_places(s: str) -> int:
         return len(s) - s.index(".") - 1
 
     if is_float(s1) or is_float(s2):
-        # check which number has more decimal places and add zeros to the other
-        # keep track of the number of decimal places
-        decimal_places_1 = number_of_decimal_places(s1)
-        decimal_places_2 = number_of_decimal_places(s2)
+        # Check which number has more decimal places and add zeros to the other
+        # Keep track of the number of decimal places
+        decimal_places_1 = number_of_decimal_places(s1) if is_float(s1) else 0
+        decimal_places_2 = number_of_decimal_places(s2) if is_float(s2) else 0
         if is_float(s1) and is_float(s2):
             decimal_places = max(decimal_places_1, decimal_places_2)
             s1 = s1.replace(".", "")
@@ -23,16 +40,12 @@ def number_of_decimal_places(s: str) -> int:
             decimal_places = decimal_places_1
             s1 = s1.replace(".", "")
             s2 += "0" * decimal_places
-
         elif is_float(s2):
             decimal_places = decimal_places_2
             s2 = s2.replace(".", "")
             s1 += "0" * decimal_places
 
-    # we can't convert to int, because the numbers might be too big and it will overflow
-    # so we'll add the numbers digit by digit
-    # we'll start from the end of the strings
-
+    # Add the numbers digit by digit starting from the end
     result = ""
     carry = 0
 
@@ -42,9 +55,9 @@ def number_of_decimal_places(s: str) -> int:
     while i >= 0 or j >= 0:
         digit_1 = int(s1[i]) if i >= 0 else 0
         digit_2 = int(s2[j]) if j >= 0 else 0
-        sum = digit_1 + digit_2 + carry
-        carry = sum // 10
-        result = str(sum % 10) + result
+        total = digit_1 + digit_2 + carry
+        carry = total // 10
+        result = str(total % 10) + result
         i -= 1
         j -= 1
 

src/brain_teasers/python/array_product/src/array_product.py

@@ -1,7 +1,20 @@
-from typing import List
+"""Product of array except self - compute array where each element is the product of all other elements."""
 
+from __future__ import annotations
 
-def product_of_array_except_self(arr: List[int]) -> List[int]:
+
+def product_of_array_except_self(arr: list[int]) -> list[int]:
+    """
+    Return an array where each element is the product of all other elements.
+
+    This algorithm runs in O(n) time without using division.
+
+    Args:
+        arr: Input array of integers.
+
+    Returns:
+        Array where result[i] is the product of all elements except arr[i].
+    """
     # Initialize the result array with all 1s
     result = [1] * len(arr)
     # Calculate the product of all elements to the left of each index

src/brain_teasers/python/binary_tree_right_side_view/src/binary_tree_right_side_view.py

@@ -1,36 +1,53 @@
-from typing import List
+"""Binary tree right side view - return values visible from the right side."""
+
+from __future__ import annotations
+
+from collections import deque
+from typing import Optional
 
 
 class TreeNode:
-    def __init__(self, value: int, left: "TreeNode" = None, right: "TreeNode" = None):
+    """A node in a binary tree."""
+
+    def __init__(
+        self,
+        value: int,
+        left: Optional[TreeNode] = None,
+        right: Optional[TreeNode] = None,
+    ) -> None:
         self.value = value
         self.left = left
         self.right = right
 
 
-def right_side_view(root: TreeNode) -> List[int]:
-    # Edge case: if the tree is empty, return an empty list
+def right_side_view(root: Optional[TreeNode]) -> list[int]:
+    """
+    Return the values of nodes visible from the right side of a binary tree.
+
+    Uses level-order traversal (BFS) and returns the rightmost node at each level.
+
+    Args:
+        root: The root node of the binary tree.
+
+    Returns:
+        List of values visible from the right side, from top to bottom.
+    """
     if not root:
         return []
-    # Initialize a queue and a result list
-    queue = [root]
-    result = []
-    # Loop until the queue is empty
+
+    queue: deque[TreeNode] = deque([root])
+    result: list[int] = []
+
     while queue:
-        # Get the size of the queue
         size = len(queue)
-        # Loop through all the nodes in the queue
         for i in range(size):
-            # Remove the first node from the queue
-            node = queue.pop(0)
-            # If this is the last node in the current level, add its value to the result list
+            node = queue.popleft()
+            # If this is the last node in the current level, add its value
             if i == size - 1:
                 result.append(node.value)
-            # If the node has a left child, add it to the queue
             if node.left:
                 queue.append(node.left)
-            # If the node has a right child, add it to the queue
             if node.right:
                 queue.append(node.right)
-    # Return the result list
+
     return result

…iew/tests/binary_tree_right_side_view.py …ests/test_binary_tree_right_side_view.pysrc/brain_teasers/python/binary_tree_right_side_view/tests/binary_tree_right_side_view.py renamed to src/brain_teasers/python/binary_tree_right_side_view/tests/test_binary_tree_right_side_view.py src/brain_teasers/python/binary_tree_right_side_view/tests/binary_tree_right_side_view.py renamed to src/brain_teasers/python/binary_tree_right_side_view/tests/test_binary_tree_right_side_view.py

@@ -1,119 +1,124 @@
-from typing import List
+"""Convert a binary search tree to a doubly linked list."""
+
+from __future__ import annotations
+
+from typing import Optional
 
 
 class TreeNode:
-    def __init__(self, value: int, left: "TreeNode" = None, right: "TreeNode" = None):
+    """A node in a binary search tree."""
+
+    def __init__(
+        self,
+        value: int,
+        left: Optional[TreeNode] = None,
+        right: Optional[TreeNode] = None,
+    ) -> None:
         self.value = value
         self.left = left
         self.right = right
 
 
 class ListNode:
-    def __init__(self, value: int, next: "ListNode" = None):
+    """A node in a doubly linked list."""
+
+    def __init__(self, value: int, next: Optional[ListNode] = None) -> None:
         self.value = value
         self.next = next
-        self.prev = None
+        self.prev: Optional[ListNode] = None
 
 
 class DoubleLinkedList:
-    def __init__(self):
-        self.head = None
-        self.tail = None
+    """A doubly linked list data structure."""
+
+    def __init__(self) -> None:
+        self.head: Optional[ListNode] = None
+        self.tail: Optional[ListNode] = None
 
-    def insert_before(self, node: ListNode, value: int) -> ListNode:
+    def insert_before(self, node: Optional[ListNode], value: int) -> ListNode:
         """Insert a new node with the given value before the given node."""
-        # Create the new node
         new_node = ListNode(value)
-        # If the given node is None, set the new node as the head and tail
         if not node:
             self.head = new_node
             self.tail = new_node
-        # Otherwise, insert the new node before the given node
         else:
-            # Set the new node's next to the given node
             new_node.next = node
-            # If the given node is the head, set the new node as the head
             if node == self.head:
                 self.head = new_node
-            # Otherwise, set the new node's prev to the given node's prev and the given node's prev's next to the new node
             else:
                 new_node.prev = node.prev
-                node.prev.next = new_node
-            # Set the given node's prev to the new node
+                if node.prev:
+                    node.prev.next = new_node
             node.prev = new_node
-        # Return the new node
         return new_node
 
-    def insert_after(self, node: ListNode, value: int) -> ListNode:
+    def insert_after(self, node: Optional[ListNode], value: int) -> ListNode:
         """Insert a new node with the given value after the given node."""
-        # Create the new node
         new_node = ListNode(value)
-        # If the given node is None, set the new node as the head and tail
         if not node:
             self.head = new_node
             self.tail = new_node
-        # Otherwise, insert the new node after the given node
         else:
-            # Set the new node's prev to the given node
             new_node.prev = node
-            # If the given node is the tail, set the new node as the tail
             if node == self.tail:
                 self.tail = new_node
-            # Otherwise, set the new node's next to the given node's next and the given node's next's prev to the new node
             else:
                 new_node.next = node.next
-                node.next.prev = new_node
-            # Set the given node's next to the new node
+                if node.next:
+                    node.next.prev = new_node
             node.next = new_node
-        # Return the new node
         return new_node
 
     def delete(self, node: ListNode) -> None:
-        """Delete the given node."""
-        # If the node is the head, set the head to the node's next
+        """Delete the given node from the list."""
         if node == self.head:
             self.head = node.next
-        # Otherwise, set the node's prev's next to the node's next
         else:
-            node.prev.next = node.next
-        # If the node is the tail, set the tail to the node's prev
+            if node.prev:
+                node.prev.next = node.next
         if node == self.tail:
             self.tail = node.prev
-        # Otherwise, set the node's next's prev to the node's prev
         else:
-            node.next.prev = node.prev
+            if node.next:
+                node.next.prev = node.prev
 
     def __iter__(self):
         node = self.head
         while node:
             yield node.value
             node = node.next
 
-    def __str__(self):
+    def __str__(self) -> str:
         return " -> ".join(map(str, self))
 
-    def to_list(self) -> List[int]:
+    def to_list(self) -> list[int]:
+        """Convert the linked list to a Python list."""
         return list(self)
 
 
-def bst_to_double_linked_list(root: TreeNode) -> DoubleLinkedList:
-    """Convert a binary search tree to a double linked list."""
-    # Create the double linked list
+def bst_to_double_linked_list(root: Optional[TreeNode]) -> DoubleLinkedList:
+    """
+    Convert a binary search tree to a doubly linked list.
+
+    Performs an in-order traversal to maintain sorted order.
+
+    Args:
+        root: The root node of the binary search tree.
+
+    Returns:
+        A doubly linked list containing all values in sorted order.
+    """
     double_linked_list = DoubleLinkedList()
-    # Create a stack to store the nodes
-    stack = []
-    # Start at the root node
+    stack: list[TreeNode] = []
     node = root
-    # Traverse the tree
+
     while node or stack:
-        # If the current node is not None, push it onto the stack and go to the left child
         if node:
             stack.append(node)
             node = node.left
-        # Otherwise, pop the top node from the stack, add it to the double linked list, and go to the right child
         else:
             node = stack.pop()
             double_linked_list.insert_before(double_linked_list.head, node.value)
             node = node.right
-    # Return the double linked list
+
     return double_linked_list

src/brain_teasers/python/bst_to_list/src/bst_to_list.py

@@ -1,21 +1,32 @@
+"""Count minimum deletions to make parentheses valid."""
+
+from __future__ import annotations
+
+
 def deletions_to_make_valid_parentheses(s: str) -> int:
-    # Stack to keep track of unmatched parentheses
-    stack = []
-    # Count of deletions needed
+    """
+    Return the minimum number of parentheses to delete to make the string valid.
+
+    A string is valid if every opening parenthesis has a matching closing one.
+
+    Args:
+        s: A string containing parentheses and potentially other characters.
+
+    Returns:
+        The minimum number of deletions needed.
+    """
+    stack: list[str] = []
     deletions = 0
-    # Loop through the string
+
     for c in s:
-        # If the current character is an opening parenthesis, push it onto the stack
         if c == "(":
             stack.append(c)
-        # If the current character is a closing parenthesis
         elif c == ")":
-            # If the stack is empty, we need to delete this closing parenthesis
             if not stack:
                 deletions += 1
-            # If the stack is not empty, we can match this closing parenthesis with an opening one
             else:
                 stack.pop()
-    # At the end of the loop, any remaining opening parentheses in the stack must be deleted
+
+    # Any remaining opening parentheses must be deleted
     deletions += len(stack)
     return deletions