Docs: Update sorting algorithm references for Python 3.11+ Powersort

Python 3.11 switched from Timsort to Powersort (an improved merge policy
with the same complexity characteristics).

Co-Authored-By: Amp <amp@ampcode.com>

Author: heikkitoivonen

DOCUMENTATION_REVIEW_PROMPT.md

@@ -31,8 +31,8 @@ For each operation listed:
 # ❌ WRONG: "list.append() is O(1)" without context
 # ✅ CORRECT: "list.append() is O(1) amortized (dynamic array resizing)"
 
-# ❌ WRONG: "sorted() is O(n log n)" without mentioning Timsort
-# ✅ CORRECT: "sorted() is O(n log n) (Timsort), O(n) best case (already sorted)"
+# ❌ WRONG: "sorted() is O(n log n)" without algorithm details
+# ✅ CORRECT: "sorted() is O(n log n) (Timsort/Powersort), O(n) best case (already sorted)"
 ```
 
 ### ✅ Code Examples (FOCUSED)
@@ -177,7 +177,7 @@ if 5 in items:  # O(n)
 "sorted() uses Timsort algorithm"
 
 # AFTER
-"sorted() uses Timsort, O(n log n) average and worst case, O(n) best case (already sorted), O(n) space"
+"sorted() uses Timsort (≤3.10) or Powersort (3.11+), O(n log n) average and worst case, O(n) best case (already sorted), O(n) space"
 
 # BEFORE (too generic)
 ```python

README.md

@@ -175,7 +175,7 @@ Example: Add: List complexity documentation
 | `pop()` | O(1) | Last element |
 | `pop(0)` | O(n) | First element |
 | `in` | O(n) | Linear search |
-| `sort()` | O(n log n) | Timsort |
+| `sort()` | O(n log n) | Timsort/Powersort |
 
 **Pro tip:** Use `deque.appendleft()` for O(1) prepend instead of `list.insert(0)`.
 

docs/builtins/list.md

@@ -18,7 +18,7 @@ The `list` type is a mutable, ordered sequence. It's implemented as a dynamic ar
 | `clear()` | O(n) | Deallocate memory |
 | `index(x)` | O(n) | Linear search |
 | `count(x)` | O(n) | Linear scan |
-| `sort()` | O(n log n) | Timsort algorithm |
+| `sort()` | O(n log n) | Timsort/Powersort |
 | `reverse()` | O(n) | In-place reversal |
 | `copy()` | O(n) | Shallow copy |
 | `extend(iterable)` | O(k) | k = length of iterable |

docs/builtins/sorted.md

@@ -6,17 +6,17 @@ The `sorted()` function returns a new sorted list from the items in an iterable.
 
 | Case | Time | Space | Notes |
 |------|------|-------|-------|
-| Basic sorting | O(n log n) | O(n) | Timsort algorithm |
+| Basic sorting | O(n log n) | O(n) | Timsort/Powersort |
 | With key function | O(n log n + n*k) | O(n) | k = key function time; key computed once per element |
 | Reverse sorting | O(n log n) | O(n) | No extra overhead |
-| Already sorted | O(n) | O(n) | Best case for Timsort |
+| Already sorted | O(n) | O(n) | Best case |
 
 ## Basic Usage
 
 ### Simple Sorting
 
 ```python
-# O(n log n) - uses Timsort algorithm
+# O(n log n) - Timsort (≤3.10) or Powersort (3.11+)
 numbers = [3, 1, 4, 1, 5, 9, 2, 6]
 result = sorted(numbers)
 # [1, 1, 2, 3, 4, 5, 6, 9]
@@ -102,16 +102,19 @@ result = sorted(coords, key=lambda c: c[1])
 # [(3, 2), (1, 5), (2, 8)]
 ```
 
-## Timsort Algorithm
+## Sorting Algorithm
 
 ### How It Works
 
 ```
-Timsort is a hybrid algorithm combining merge sort and insertion sort:
+Python uses Timsort (Python 2.3-3.10) or Powersort (Python 3.11+).
+Both are hybrid algorithms combining merge sort and insertion sort:
 1. Divide array into small chunks (runs) - ~32-64 elements
 2. Sort each run with insertion sort - O(k²) per run
 3. Merge runs together - O(n log n) overall
 4. Already sorted data: O(n) - detects and uses it
+
+Powersort uses an improved merge policy but has the same complexity.
 ```
 
 ### Performance Characteristics
@@ -147,7 +150,7 @@ original = [3, 1, 4, 1, 5]
 original.sort()  # [1, 1, 3, 4, 5]
 # original modified
 
-# Both use Timsort, same complexity but sorted() makes copy
+# Both use same algorithm, same complexity but sorted() makes copy
 ```
 
 ### Expensive Key Functions
@@ -325,6 +328,5 @@ result = sorted(numbers)  # Nearly O(n)
 
 ## Version Notes
 
-- **Python 2.x**: Uses Timsort since 2.3
-- **Python 3.x**: Same Timsort implementation
-- **Python 3.8+**: No changes to complexity, consistent performance
+- **Python 2.3-3.10**: Uses Timsort algorithm
+- **Python 3.11+**: Uses Powersort (improved merge policy, same complexity)

docs/implementations/cpython.md

@@ -99,7 +99,7 @@ gc.collect()  # O(n) where n = tracked objects
 | `insert(0)` | O(n) - no special optimization |
 | `pop()` | O(1) |
 | `pop(0)` | O(n) |
-| `sort()` | O(n log n) using Timsort |
+| `sort()` | O(n log n) using Timsort (≤3.10) or Powersort (3.11+) |
 
 ### Dict Operations
 

docs/versions/py311.md

@@ -166,7 +166,7 @@ lst.extend([2,3])  # O(k) for k items
 lst.insert(0, 0)   # O(n) shift all
 lst.pop()          # O(1)
 lst.pop(0)         # O(n) shift all
-lst.sort()         # O(n log n) Timsort
+lst.sort()         # O(n log n) Powersort
 lst[i]             # O(1)
 1 in lst           # O(n) search
 ```

docs/versions/py313.md

@@ -98,7 +98,7 @@ lst = list(range(1000000))
 # append: O(1)* - same as 3.12
 lst.append(999999)
 
-# sort: O(n log n) - Timsort unchanged
+# sort: O(n log n) - Powersort (since 3.11)
 lst.sort()
 ```