Fix: Correct builtin complexity docs for CPython 3.14

Co-Authored-By: Codex <codex@openai.com>

Author: heikkitoivonen

docs/builtins/aiter.md

@@ -37,7 +37,7 @@ asyncio.run(main())
 import asyncio
 
 class AsyncIterable:
-    async def __aiter__(self):
+    def __aiter__(self):
         return AsyncIterator()
 
 class AsyncIterator:

docs/builtins/all.md

@@ -44,16 +44,17 @@ result = all(x > 2 for x in numbers)  # False - stops at 1
 
 ```python
 # ✅ O(1) - stops immediately at first falsy
-result = all([False, expensive_function(), expensive_function()])
-# Doesn't call expensive_function()
+checks = [lambda: False, expensive_function, expensive_function]
+result = all(check() for check in checks)
+# expensive_function() is never called
 
 # ❌ O(n) - evaluates all
 result = all([False] + [expensive_function() for _ in range(1000)])
 # Calls expensive_function() 1000 times
 
-# ✅ O(1) - generator stops early
-result = all(x > 0 for x in range(1000000) if x < 0)
-# Stops immediately when x < 0 is False
+# ✅ O(k) - generator stops when predicate first fails
+result = all(x < 100 for x in range(1000000))
+# Stops after checking 100 items
 ```
 
 ### Generator Efficiency

docs/builtins/anext.md

@@ -26,7 +26,7 @@ async def async_generator():
 async def main():
     async_iter = aiter(async_generator())
 
-    # Get next item - O(n)
+    # Get next item - O(k) where k = async iterator work for this step
     value = await anext(async_iter)
     print(value)  # 0
 
@@ -52,7 +52,7 @@ async def main():
     print(await anext(async_iter))  # 1
     print(await anext(async_iter))  # 2
 
-    # Default when exhausted - O(n)
+    # Default when exhausted - O(1) once iterator is exhausted
     value = await anext(async_iter, "END")
     print(value)  # "END"
 
@@ -73,7 +73,7 @@ async def main():
     print(await anext(async_iter))  # 1
 
     try:
-        # No default - raises StopAsyncIteration - O(n)
+        # No default - raises StopAsyncIteration when exhausted (O(1) at exhaustion)
         print(await anext(async_iter))
     except StopAsyncIteration:
         print("Iterator exhausted")
@@ -95,7 +95,7 @@ async def main():
     # Create async iterator - O(1)
     iterator = aiter(fetch_items(["a", "b", "c"]))
 
-    # Get items manually - O(n) each
+    # Get items manually - O(k) each where k depends on iterator body
     first = await anext(iterator)
     print(f"First: {first}")  # First: a
 

docs/builtins/any.md

@@ -45,8 +45,9 @@ result = any(x > 2 for x in numbers)  # True - stops at 3 (index 2)
 
 ```python
 # ✅ O(1) - stops immediately at first truthy
-result = any([True, expensive_function(), expensive_function()])
-# Doesn't call expensive_function()
+checks = [lambda: True, expensive_function, expensive_function]
+result = any(check() for check in checks)
+# expensive_function() is never called
 
 # ❌ O(n) - evaluates all
 result = any([True] + [expensive_function() for _ in range(1000)])

docs/builtins/compile.md

@@ -135,11 +135,11 @@ result2 = eval(code_obj, {"x": 5, "y": 10})  # 15
 ## Compilation with Optimization
 
 ```python
-# O(n) - optimize flag (Python 2 feature, deprecated in 3)
-# Python 3 ignores optimize parameter
-
-# In Python 3, compile is always well-optimized
-code = compile("x = 1", "<string>", "exec", optimize=-1)
+# O(n) - optimize is active in Python 3
+# optimize=-1 (inherit), 0 (no optimization), 1, or 2
+code_default = compile("x = 1", "<string>", "exec", optimize=-1)
+code_o1 = compile("assert x > 0", "<string>", "exec", optimize=1)
+code_o2 = compile("def f():\n    'doc'\n    return 1", "<string>", "exec", optimize=2)
 ```
 
 ## Error Handling

docs/builtins/dict.md

@@ -34,7 +34,7 @@ CPython uses a hash table with:
 - **Hash function**: SipHash13 for `str`/`bytes` (default since Python 3.11); other types use type-specific hashing
 - **Collision handling**: Open addressing with probing
 - **Growth factor**: ~2-4x when load factor exceeded
-- **Python 3.6+**: Insertion order preserved (compact dict design)
+- **Python 3.6 (CPython)**: Compact dict preserves insertion order as an implementation detail
 
 ### Hash Collision Impact
 
@@ -50,7 +50,7 @@ value = d[500]  # O(1)
 ### Insertion Order Guarantee
 
 ```python
-# Python 3.6+ guarantees insertion order
+# Python 3.7+ guarantees insertion order (language guarantee)
 d = {}
 d['a'] = 1
 d['b'] = 2
@@ -62,7 +62,8 @@ d['c'] = 3
 
 | Version | Change |
 |---------|--------|
-| Python 3.6+ | Insertion order preserved |
+| Python 3.6 | CPython compact dict preserves insertion order (implementation detail) |
+| Python 3.7+ | Insertion order guaranteed by language spec |
 | Python 3.9+ | Dict merge & update operators (`\|`, `\|=`) |
 | Python 3.10+ | Pattern matching with dicts |
 | Python 3.11+ | 23% smaller when all keys are Unicode strings |
@@ -91,7 +92,7 @@ Similar hash table implementation as CPython.
 
 ❌ **Avoid**:
 
-- Don't rely on order in Python < 3.6
+- Don't rely on insertion order in Python < 3.7 for portable behavior
 - Unhashable types as keys (lists, dicts, sets)
 - Extremely large dicts with poor hash functions
 

docs/builtins/dict_func.md

@@ -7,10 +7,10 @@ The `dict()` function creates dictionaries from various sources.
 | Case | Time | Space | Notes |
 |------|------|-------|-------|
 | Empty dict | O(1) | O(1) | dict() |
-| From keyword arguments | O(n) | O(n) | n = number of kwargs |
-| From list of pairs | O(n) | O(n) | n = number of pairs |
-| From another dict | O(n) | O(n) | n = dict size |
-| From iterable of pairs | O(n) | O(n) | n = number of pairs |
+| From keyword arguments | O(n) avg, O(n^2) worst | O(n) | n = number of kwargs |
+| From list of pairs | O(n) avg, O(n^2) worst | O(n) | n = number of pairs |
+| From another dict | O(n) avg, O(n^2) worst | O(n) | n = dict size |
+| From iterable of pairs | O(n) avg, O(n^2) worst | O(n) | n = number of pairs |
 
 ## Basic Usage
 
@@ -84,14 +84,13 @@ d = dict(pairs)  # O(4) - hash and store each pair
 ### Collision Handling
 
 ```python
-# O(n) - collisions don't affect overall complexity
-# Even with hash collisions, dict() is still O(n)
+# Average case: O(n)
+# Pathological collisions can degrade construction toward O(n^2)
 
-# worst case - all keys hash to same value
-# Still O(n) due to Python's implementation
+# Worst case: many keys map to the same hash/probe sequence
 
 pairs = [(i, i*10) for i in range(1000)]
-d = dict(pairs)  # O(1000) - even with collisions
+d = dict(pairs)  # O(n) average
 ```
 
 ### Keyword Arguments

docs/builtins/globals.md

@@ -7,7 +7,7 @@ The `globals()` and `locals()` functions return dictionary representations of th
 | Operation | Time | Space | Notes |
 |-----------|------|-------|-------|
 | `globals()` | O(1) | O(1) | Returns reference to existing global dict |
-| `locals()` | O(m) | O(m) | Creates snapshot copy; m = number of local vars |
+| `locals()` | O(1) or O(m) | O(1) or O(m) | Module/class scope is O(1); optimized function scopes materialize locals mapping |
 | Accessing dict value | O(1) avg | O(1) | Dict key lookup; O(n) worst case with collisions |
 
 ## Understanding Namespaces
@@ -54,7 +54,7 @@ x = 10
 y = 20
 z = 30
 
-all_vars = globals()  # O(n)
+all_vars = globals()  # O(1)
 
 # Filter variables (not functions/modules) - O(n)
 my_vars = {k: v for k, v in all_vars.items() 
@@ -113,7 +113,7 @@ caller()
 ### Module Level
 
 ```python
-# At module level, locals() == globals() - O(n)
+# At module level, locals() == globals() - O(1)
 X = 100
 
 print(locals() is globals())  # True at module level
@@ -249,7 +249,7 @@ print(task())
 ### Configuration Registry
 
 ```python
-# Use globals() as simple registry - O(n)
+# Use globals() as simple registry - O(1) per lookup/update
 CONFIG = {}
 
 def register_config(name, value):
@@ -286,13 +286,16 @@ for i in range(1000):
 ### Large Namespaces
 
 ```python
-# Many variables = expensive globals() call - O(n)
-# In interactive session with many variables
+# globals() remains O(1) regardless of namespace size
+# Iterating over the returned dict is O(n)
 for i in range(10000):
     globals()[f'var_{i}'] = i  # O(1) each
 
-# Now globals() is O(10000)
-g = globals()  # Slower!
+# Still O(1): returns the same global dict object
+g = globals()
+
+# Iteration scales with number of entries - O(n)
+names = [k for k in g if k.startswith("var_")]
 
 # Prefer dict for custom data
 my_data = {}
@@ -347,13 +350,14 @@ print(obj.x)  # 10
 ## Debugging with Frame Inspection
 
 ```python
-import sys
+import inspect
 
 def get_caller_info():
     """Get information about calling function"""
-    frame = sys.exc_info()[2]  # O(1)
+    current = inspect.currentframe()  # O(1)
+    frame = current.f_back if current is not None else None  # O(1)
     if frame is None:
-        frame = sys.gettrace().f_back  # O(1)
+        return None
 
     # Access caller's locals - O(m)
     locals_dict = frame.f_locals
@@ -373,7 +377,7 @@ def example():
 
 - **Python 2.x**: Same behavior
 - **Python 3.x**: Same behavior
-- **All versions**: O(1) for globals() (returns reference), O(m) for locals() (creates copy)
+- **All versions**: `globals()` is O(1); `locals()` semantics are scope- and implementation-dependent
 
 ## Related Functions
 
@@ -386,14 +390,12 @@ def example():
 ✅ **Do**:
 
 - Use `globals()` for metaprogramming when needed
-- Cache globals() if calling multiple times
 - Use inspect module for reflection
 - Be explicit about variable scope
 
 ❌ **Avoid**:
 
 - Relying on locals() to set variables in functions
-- Calling globals() in loops (cache it)
 - Modifying globals() at module level (confusing)
 - Using globals()/locals() instead of proper parameters
 - Assuming locals() state persists after function returns