data_structures: add return type annotations (ANN201) (#15306)

Annotate the unambiguous, primitive/container-returning public methods
flagged by ruff ANN201 across data_structures/ (int/bool/float/list/dict
and one fluent self-return). Reduces ANN201 in this directory from 58 to 36.

Element-typed and sentinel-union returns (e.g. node .data getters,
dict|False in the Sudoku solver) are intentionally left for follow-up,
since they warrant generics/TypeVar or a type checker rather than a guess.

Refs #15296

Author: priya-sundaram-dev

data_structures/binary_tree/segment_tree.py

@@ -11,7 +11,7 @@ def __init__(self, a) -> None:
         if self.N:
             self.build(1, 0, self.N - 1)
 
-    def left(self, idx):
+    def left(self, idx) -> int:
         """
         Returns the left child index for a given index in a binary tree.
 
@@ -23,7 +23,7 @@ def left(self, idx):
         """
         return idx * 2
 
-    def right(self, idx):
+    def right(self, idx) -> int:
         """
         Returns the right child index for a given index in a binary tree.
 
@@ -44,7 +44,7 @@ def build(self, idx, left, right) -> None:
             self.build(self.right(idx), mid + 1, right)
             self.st[idx] = max(self.st[self.left(idx)], self.st[self.right(idx)])
 
-    def update(self, a, b, val):
+    def update(self, a, b, val) -> bool:
         """
         Update the values in the segment tree in the range [a,b] with the given value.
 
@@ -71,7 +71,7 @@ def update_recursive(self, idx, left, right, a, b, val) -> bool:
         self.st[idx] = max(self.st[self.left(idx)], self.st[self.right(idx)])
         return True
 
-    def query(self, a, b):
+    def query(self, a, b) -> float:
         """
         Query the maximum value in the range [a,b].
 
@@ -83,7 +83,7 @@ def query(self, a, b):
         """
         return self.query_recursive(1, 0, self.N - 1, a - 1, b - 1)
 
-    def query_recursive(self, idx, left, right, a, b):
+    def query_recursive(self, idx, left, right, a, b) -> float:
         """
         query(1, 1, N, a, b) for query max of [a,b]
         """

data_structures/hashing/hash_table.py

@@ -22,7 +22,7 @@ def __init__(
         self.__aux_list: list = []
         self._keys: dict = {}
 
-    def keys(self):
+    def keys(self) -> dict:
         """
         The keys function returns a dictionary containing the key value pairs.
         key being the index number in hash table and value being the data value.
@@ -48,12 +48,12 @@ def keys(self):
         """
         return self._keys
 
-    def balanced_factor(self):
+    def balanced_factor(self) -> float:
         return sum(1 for slot in self.values if slot is not None) / (
             self.size_table * self.charge_factor
         )
 
-    def hash_function(self, key):
+    def hash_function(self, key) -> int:
         """
         Generates hash for the given key value
 

data_structures/hashing/hash_table_with_linked_list.py

@@ -12,7 +12,7 @@ def _set_value(self, key, data) -> None:
         self.values[key].appendleft(data)
         self._keys[key] = self.values[key]
 
-    def balanced_factor(self):
+    def balanced_factor(self) -> float:
         return (
             sum(self.charge_factor - len(slot) for slot in self.values)
             / self.size_table

data_structures/heap/binomial_heap.py

@@ -251,7 +251,7 @@ def peek(self):
         """
         return self.min_node.val
 
-    def is_empty(self):
+    def is_empty(self) -> bool:
         return self.size == 0
 
     def delete_min(self):

data_structures/heap/max_heap.py

@@ -60,7 +60,7 @@ def pop(self) -> int:
         return max_value
 
     @property
-    def get_list(self):
+    def get_list(self) -> list:
         return self.__heap[1:]
 
     def __len__(self) -> int:

data_structures/heap/min_heap.py

@@ -39,19 +39,19 @@ def __init__(self, array) -> None:
     def __getitem__(self, key):
         return self.get_value(key)
 
-    def get_parent_idx(self, idx):
+    def get_parent_idx(self, idx) -> int:
         return (idx - 1) // 2
 
-    def get_left_child_idx(self, idx):
+    def get_left_child_idx(self, idx) -> int:
         return idx * 2 + 1
 
-    def get_right_child_idx(self, idx):
+    def get_right_child_idx(self, idx) -> int:
         return idx * 2 + 2
 
     def get_value(self, key):
         return self.heap_dict[key]
 
-    def build_heap(self, array):
+    def build_heap(self, array) -> list:
         last_idx = len(array) - 1
         start_from = self.get_parent_idx(last_idx)
 
@@ -120,7 +120,7 @@ def insert(self, node) -> None:
         self.heap_dict[node.name] = node.val
         self.sift_up(len(self.heap) - 1)
 
-    def is_empty(self):
+    def is_empty(self) -> bool:
         return len(self.heap) == 0
 
     def decrease_key(self, node, new_value) -> None:

data_structures/linked_list/doubly_linked_list.py

@@ -196,7 +196,7 @@ def delete(self, data) -> str:
             current.next.previous = current.previous  # 1 <--> 3
         return data
 
-    def is_empty(self):
+    def is_empty(self) -> bool:
         """
         >>> linked_list = DoublyLinkedList()
         >>> linked_list.is_empty()

data_structures/linked_list/doubly_linked_list_two.py

@@ -158,7 +158,7 @@ def remove_node_pointers(node: Node) -> None:
         node.next = None
         node.previous = None
 
-    def is_empty(self):
+    def is_empty(self) -> bool:
         return self.head is None
 
 

data_structures/queues/circular_queue.py

@@ -47,7 +47,7 @@ def first(self):
         """
         return False if self.is_empty() else self.array[self.front]
 
-    def enqueue(self, data):
+    def enqueue(self, data) -> "CircularQueue":
         """
         This function inserts an element at the end of the queue using self.rear value
         as an index.

data_structures/stacks/prefix_evaluation.py

@@ -11,7 +11,7 @@
 }
 
 
-def is_operand(c):
+def is_operand(c) -> bool:
     """
     Return True if the given char c is an operand, e.g. it is a number
 
@@ -23,7 +23,7 @@ def is_operand(c):
     return c.isdigit()
 
 
-def evaluate(expression):
+def evaluate(expression) -> float:
     """
     Evaluate a given expression in prefix notation.
     Asserts that the given expression is valid.
@@ -55,7 +55,7 @@ def evaluate(expression):
     return stack.pop()
 
 
-def evaluate_recursive(expression: list[str]):
+def evaluate_recursive(expression: list[str]) -> float:
     """
     Alternative recursive implementation