types(intro_sort): constrain items to Comparable

Bind every function in sorts/intro_sort.py to a Comparable Protocol so the
signatures say "a list of items that can be compared with each other"
instead of a bare list, and keep the element type in the return.

Two of the hints were outright wrong rather than merely loose:

- median_of_3 returned int but returns an element of the collection, so it
  is now T
- partition took pivot: int but takes an element of the collection, so it is
  now T

Both were only reachable with the wrong type through untyped callers.

Doctests added for a comparable non-int type (strings) and for the failure
mode on insertion_sort, heap_sort, median_of_3, partition and sort: mixing
non-comparable items must raise TypeError rather than silently mis-sort.

intro_sort had no test at all. tests/test_sorts.py now adds it to the shared
battery and to the rejection check, plus a dedicated test that reaches the
branches the battery cannot: every shared case is shorter than the
16-element threshold, so the battery only ever exercises insertion_sort.
The new test sorts 17/32/100/500-element int and str inputs to take the
quicksort branch, and drives intro_sort with a depth budget of 0 to take the
heapsort branch. The RNG is seeded so the test is deterministic.

Author: AuroraEon

sorts/intro_sort.py

@@ -2,12 +2,25 @@
 Introspective Sort is a hybrid sort (Quick Sort + Heap Sort + Insertion Sort)
 if the size of the list is under 16, use insertion sort
 https://en.wikipedia.org/wiki/Introsort
+
+For doctests run following command:
+python3 -m doctest -v intro_sort.py
+
+For manual testing run:
+python3 intro_sort.py
 """
 
 import math
+from typing import Any, Protocol
+
+
+class Comparable(Protocol):
+    def __lt__(self, other: Any, /) -> bool: ...
 
 
-def insertion_sort(array: list, start: int = 0, end: int = 0) -> list:
+def insertion_sort[T: Comparable](
+    array: list[T], start: int = 0, end: int = 0
+) -> list[T]:
     """
     >>> array = [4, 2, 6, 8, 1, 7, 8, 22, 14, 56, 27, 79, 23, 45, 14, 12]
     >>> insertion_sort(array, 0, len(array))
@@ -24,6 +37,10 @@ def insertion_sort(array: list, start: int = 0, end: int = 0) -> list:
     >>> array = [73.568, 73.56, -45.03, 1.7, 0, 89.45]
     >>> insertion_sort(array, 0, len(array))
     [-45.03, 0, 1.7, 73.56, 73.568, 89.45]
+    >>> insertion_sort([1, "a"])  # doctest: +ELLIPSIS
+    Traceback (most recent call last):
+    ...
+    TypeError: ...
     """
     end = end or len(array)
     for i in range(start, end):
@@ -36,7 +53,9 @@ def insertion_sort(array: list, start: int = 0, end: int = 0) -> list:
     return array
 
 
-def heapify(array: list, index: int, heap_size: int) -> None:  # Max Heap
+def heapify[T: Comparable](
+    array: list[T], index: int, heap_size: int
+) -> None:  # Max Heap
     """
     >>> array = [4, 2, 6, 8, 1, 7, 8, 22, 14, 56, 27, 79, 23, 45, 14, 12]
     >>> heapify(array, len(array) // 2, len(array))
@@ -56,7 +75,7 @@ def heapify(array: list, index: int, heap_size: int) -> None:  # Max Heap
         heapify(array, largest, heap_size)
 
 
-def heap_sort(array: list) -> list:
+def heap_sort[T: Comparable](array: list[T]) -> list[T]:
     """
     >>> heap_sort([4, 2, 6, 8, 1, 7, 8, 22, 14, 56, 27, 79, 23, 45, 14, 12])
     [1, 2, 4, 6, 7, 8, 8, 12, 14, 14, 22, 23, 27, 45, 56, 79]
@@ -66,6 +85,12 @@ def heap_sort(array: list) -> list:
     ['b', 'b', 'd', 'e', 'e', 'f', 'g', 'p', 's', 'u', 'v', 'x', 'z']
     >>> heap_sort([6.2, -45.54, 8465.20, 758.56, -457.0, 0, 1, 2.879, 1.7, 11.7])
     [-457.0, -45.54, 0, 1, 1.7, 2.879, 6.2, 11.7, 758.56, 8465.2]
+    >>> heap_sort(["banana", "apple", "cherry"])
+    ['apple', 'banana', 'cherry']
+    >>> heap_sort([1, "a"])  # doctest: +ELLIPSIS
+    Traceback (most recent call last):
+    ...
+    TypeError: ...
     """
     n = len(array)
 
@@ -79,9 +104,9 @@ def heap_sort(array: list) -> list:
     return array
 
 
-def median_of_3(
-    array: list, first_index: int, middle_index: int, last_index: int
-) -> int:
+def median_of_3[T: Comparable](
+    array: list[T], first_index: int, middle_index: int, last_index: int
+) -> T:
     """
     >>> array = [4, 2, 6, 8, 1, 7, 8, 22, 14, 56, 27, 79, 23, 45, 14, 12]
     >>> median_of_3(array, 0, ((len(array) - 0) // 2) + 1, len(array) - 1)
@@ -92,6 +117,12 @@ def median_of_3(
     >>> array = [4, 2, 6, 8, 1, 7, 8, 22, 15, 14, 27, 79, 23, 45, 14, 16]
     >>> median_of_3(array, 0, ((len(array) - 0) // 2) + 1, len(array) - 1)
     14
+    >>> median_of_3(["b", "m", "z"], 0, 1, 2)
+    'm'
+    >>> median_of_3([1, "a", 2], 0, 1, 2)  # doctest: +ELLIPSIS
+    Traceback (most recent call last):
+    ...
+    TypeError: ...
     """
     if (array[first_index] > array[middle_index]) != (
         array[first_index] > array[last_index]
@@ -105,7 +136,7 @@ def median_of_3(
         return array[last_index]
 
 
-def partition(array: list, low: int, high: int, pivot: int) -> int:
+def partition[T: Comparable](array: list[T], low: int, high: int, pivot: T) -> int:
     """
     >>> array = [4, 2, 6, 8, 1, 7, 8, 22, 14, 56, 27, 79, 23, 45, 14, 12]
     >>> partition(array, 0, len(array), 12)
@@ -119,6 +150,10 @@ def partition(array: list, low: int, high: int, pivot: int) -> int:
     >>> array = [6.2, -45.54, 8465.20, 758.56, -457.0, 0, 1, 2.879, 1.7, 11.7]
     >>> partition(array, 0, len(array), 2.879)
     6
+    >>> partition([1, "a", 2], 0, 3, 2)  # doctest: +ELLIPSIS
+    Traceback (most recent call last):
+    ...
+    TypeError: ...
     """
     i = low
     j = high
@@ -134,7 +169,7 @@ def partition(array: list, low: int, high: int, pivot: int) -> int:
         i += 1
 
 
-def sort(array: list) -> list:
+def sort[T: Comparable](array: list[T]) -> list[T]:
     """
     :param collection: some mutable ordered collection with heterogeneous
     comparable items inside
@@ -155,6 +190,12 @@ def sort(array: list) -> list:
     [0.3, 1.0, 1.7, 2.1, 3.3]
     >>> sort(['d', 'a', 'b', 'e', 'c'])
     ['a', 'b', 'c', 'd', 'e']
+    >>> sort(["banana", "apple", "cherry"])
+    ['apple', 'banana', 'cherry']
+    >>> sort([1, "a"])  # doctest: +ELLIPSIS
+    Traceback (most recent call last):
+    ...
+    TypeError: ...
     """
     if len(array) == 0:
         return array
@@ -163,9 +204,9 @@ def sort(array: list) -> list:
     return intro_sort(array, 0, len(array), size_threshold, max_depth)
 
 
-def intro_sort(
-    array: list, start: int, end: int, size_threshold: int, max_depth: int
-) -> list:
+def intro_sort[T: Comparable](
+    array: list[T], start: int, end: int, size_threshold: int, max_depth: int
+) -> list[T]:
     """
     >>> array = [4, 2, 6, 8, 1, 7, 8, 22, 14, 56, 27, 79, 23, 45, 14, 12]
     >>> max_depth = 2 * math.ceil(math.log2(len(array)))

tests/test_sorts.py

@@ -17,6 +17,7 @@
 separately below.
 """
 
+import random
 from dataclasses import dataclass
 from typing import NamedTuple
 
@@ -34,6 +35,7 @@
 from sorts.gnome_sort import gnome_sort
 from sorts.heap_sort import heap_sort
 from sorts.insertion_sort import insertion_sort
+from sorts.intro_sort import intro_sort, sort
 from sorts.iterative_merge_sort import iter_merge_sort
 from sorts.merge_sort import merge_sort
 from sorts.odd_even_sort import odd_even_sort
@@ -59,6 +61,36 @@ def test_heap_sort() -> None:
     assert heap_sort([5, 4, 3, 2, 1]) == [1, 2, 3, 4, 5]
 
 
+def test_intro_sort_comparable_items() -> None:
+    """``intro_sort`` agrees with the built-in once it leaves the small-input
+    insertion-sort base case, and both of its remaining branches are reached.
+
+    Every case in the shared ``CASES`` battery is shorter than the 16-element
+    threshold, so the battery alone only ever exercises ``insertion_sort``.
+    The inputs below are large enough to take the quicksort branch, and the
+    last two force the heapsort branch by exhausting the recursion budget.
+    """
+    rng = random.Random(20260923)
+    alphabet = "abcdefghijklmnopqrstuvwxyz"
+
+    for size in (17, 32, 100, 500):
+        numbers = [rng.randint(-1000, 1000) for _ in range(size)]
+        assert sort(numbers) == sorted(numbers)
+
+        letters = rng.choices(alphabet, k=size)
+        assert sort(letters) == sorted(letters)
+
+    # a depth budget of 0 sends the algorithm straight to the heapsort branch
+    values = [rng.randint(-1000, 1000) for _ in range(50)]
+    assert intro_sort(list(values), 0, len(values), 1, 0) == sorted(values)
+
+    # a generous budget keeps it on the quicksort branch instead
+    assert intro_sort(list(values), 0, len(values), 1, 64) == sorted(values)
+
+    with pytest.raises(TypeError):
+        sort([1, "a"])
+
+
 SORTS = (
     binary_insertion_sort,
     bubble_sort_iterative,
@@ -83,6 +115,7 @@ def test_heap_sort() -> None:
     selection_sort,
     shell_sort,
     shrink_shell_sort,
+    sort,
     stooge_sort,
     strand_sort,
 )
@@ -152,6 +185,7 @@ def test_rec_insertion_sort(case) -> None:
         reversort,
         selection_sort,
         shrink_shell_sort,
+        sort,
         strand_sort,
     ],
     ids=lambda f: f.__name__,