Refactor Comparable protocol and improve docstrings

Removed unused __lt__ method from Comparable protocol and updated docstrings for clarity.

Author: cclauss

data_structures/heap/heap.py

@@ -2,26 +2,20 @@
 
 from abc import abstractmethod
 from collections.abc import Iterable
+from functools import total_ordering
 from typing import Protocol, TypeVar
 
 
 class Comparable(Protocol):
-    @abstractmethod
-    def __lt__(self: T, other: T, /) -> bool:
-        pass
-
     @abstractmethod
     def __gt__(self: T, other: T, /) -> bool:
         pass
 
-    @abstractmethod
-    def __eq__(self: T, other: object, /) -> bool:
-        pass
-
 
 T = TypeVar("T", bound=Comparable)
 
 
+@total_ordering
 class Heap[T: Comparable]:
     """A Max Heap Implementation
 
@@ -54,7 +48,7 @@ def __repr__(self) -> str:
 
     def parent_index(self, child_idx: int) -> int | None:
         """
-        returns the parent index based on the given child index
+        Returns the parent index based on the given child index
 
         >>> h = Heap()
         >>> h.build_max_heap([103, 9, 1, 7, 11, 15, 25, 201, 209, 107, 5])
@@ -90,8 +84,8 @@ def parent_index(self, child_idx: int) -> int | None:
 
     def left_child_idx(self, parent_idx: int) -> int | None:
         """
-        return the left child index if the left child exists.
-        if not, return None.
+        Return the left child index if the left child exists.
+        If not, return None.
         """
         left_child_index = 2 * parent_idx + 1
         if left_child_index < self.heap_size:
@@ -100,8 +94,8 @@ def left_child_idx(self, parent_idx: int) -> int | None:
 
     def right_child_idx(self, parent_idx: int) -> int | None:
         """
-        return the right child index if the right child exists.
-        if not, return None.
+        Return the right child index if the right child exists.
+        If not, return None.
         """
         right_child_index = 2 * parent_idx + 2
         if right_child_index < self.heap_size:
@@ -110,10 +104,10 @@ def right_child_idx(self, parent_idx: int) -> int | None:
 
     def max_heapify(self, index: int) -> None:
         """
-        correct a single violation of the heap property in a subtree's root.
+        Correct a single violation of the heap property in a subtree's root.
 
         It is the function that is responsible for restoring the property
-        of Max heap i.e the maximum element is always at top.
+        of a max heap, i.e the maximum element is always at the top.
         """
         if index < self.heap_size:
             violation: int = index
@@ -133,7 +127,7 @@ def max_heapify(self, index: int) -> None:
 
     def build_max_heap(self, collection: Iterable[T]) -> None:
         """
-        build max heap from an unsorted array
+        Build a max heap from an unsorted array
 
         >>> h = Heap()
         >>> h.build_max_heap([20,40,50,20,10])
@@ -164,7 +158,7 @@ def build_max_heap(self, collection: Iterable[T]) -> None:
 
     def extract_max(self) -> T:
         """
-        get and remove max from heap
+        Get and remove max from heap
 
         >>> h = Heap()
         >>> h.build_max_heap([20,40,50,20,10])
@@ -195,7 +189,7 @@ def extract_max(self) -> T:
 
     def insert(self, value: T) -> None:
         """
-        insert a new value into the max heap
+        Insert a new value into the max heap
 
         >>> h = Heap()
         >>> h.insert(10)
@@ -241,7 +235,6 @@ def heap_sort(self) -> None:
 if __name__ == "__main__":
     import doctest
 
-    # run doc test
     doctest.testmod()
 
     # demo