Manual review of builtin functions: next-locals

Mostly removing content that has nothing to do with performance.

Author: heikkitoivonen

docs/builtins/globals.md

@@ -138,27 +138,6 @@ def func():
 func()
 ```
 
-### Nested Functions
-
-```python
-# Nested functions can access enclosing scope
-def outer():
-    x = 10
-    
-    def inner():
-        y = 20
-        
-        # locals() shows only inner's variables
-        print(locals())  # {'y': 20}
-        
-        # Access outer's x through closure, not locals()
-        print(x)  # 10 (from enclosing scope)
-    
-    inner()
-
-outer()
-```
-
 ## Modifying Namespaces
 
 ### Setting Global Variables
@@ -303,76 +282,6 @@ for i in range(10000):
     my_data[f'var_{i}'] = i  # O(1) each
 ```
 
-## Advanced Patterns
-
-### Inspecting Function Parameters
-
-```python
-import inspect
-
-def my_func(a, b, c=10):
-    # Get function signature
-    sig = inspect.signature(my_func)  # O(1)
-    
-    # Get local variables
-    local_vars = locals()  # O(m)
-    
-    # Show what was passed
-    params = {}
-    for param_name in sig.parameters:  # O(k) params
-        params[param_name] = local_vars.get(param_name)
-    
-    return params
-
-result = my_func(1, 2, 3)  # O(m)
-print(result)  # {'a': 1, 'b': 2, 'c': 3}
-```
-
-### Metaprogramming
-
-```python
-# Create class dynamically - O(k)
-def create_class(name, attrs):
-    """Create class using globals()"""
-    class_dict = {}  # O(1)
-    
-    for attr_name, attr_value in attrs.items():
-        class_dict[attr_name] = attr_value
-    
-    # Create class (simplified)
-    return type(name, (), class_dict)
-
-MyClass = create_class('MyClass', {'x': 10, 'y': 20})
-obj = MyClass()
-print(obj.x)  # 10
-```
-
-## Debugging with Frame Inspection
-
-```python
-import inspect
-
-def get_caller_info():
-    """Get information about calling function"""
-    current = inspect.currentframe()  # O(1)
-    frame = current.f_back if current is not None else None  # O(1)
-    if frame is None:
-        return None
-    
-    # Access caller's locals - O(m)
-    locals_dict = frame.f_locals
-    
-    return {
-        'line': frame.f_lineno,
-        'locals': locals_dict
-    }
-
-def example():
-    x = 10
-    y = 20
-    # info = get_caller_info()  # O(m)
-```
-
 ## Version Notes
 
 - **Python 2.x**: Same behavior
@@ -384,18 +293,3 @@ def example():
 - **[vars()](vars.md)** - Similar to locals() but for objects
 - **[dir()](dir.md)** - List names in namespace
 - **inspect.signature()** - Get function signature
-
-## Best Practices
-
-✅ **Do**:
-
-- Use `globals()` for metaprogramming when needed
-- Use inspect module for reflection
-- Be explicit about variable scope
-
-❌ **Avoid**:
-
-- Relying on locals() to set variables in functions
-- Modifying globals() at module level (confusing)
-- Using globals()/locals() instead of proper parameters
-- Assuming locals() state persists after function returns

docs/builtins/id.md

@@ -48,55 +48,12 @@ print(x is z)      # False - different objects
 print(id(x) == id(z))  # False - different IDs
 ```
 
-## Understanding Python Objects
-
-### Immutable Types
-
-```python
-# In CPython, small integers are cached (implementation detail)
-a = 5
-b = 5
-print(id(a) == id(b))  # True - same cached object
-
-# For larger integers, identity behavior is implementation/code-path dependent
-c = int("257")
-d = int("257")
-print(id(c) == id(d))  # Typically False (distinct runtime-created objects)
-
-# String interning (same for equal strings sometimes)
-s1 = "hello"
-s2 = "hello"
-print(id(s1) == id(s2))  # Usually True (interned)
-
-t1 = "".join(['h', 'e', 'l', 'l', 'o'])
-t2 = "".join(['h', 'e', 'l', 'l', 'o'])
-print(id(t1) == id(t2))  # False (not interned)
-```
-
-### Mutable Types
-
-```python
-# Lists create new objects - O(1) to get ID
-lst1 = [1, 2, 3]
-lst2 = [1, 2, 3]
-print(id(lst1) == id(lst2))  # False - different objects
-
-# Assignment creates reference, not copy
-lst3 = lst1
-print(id(lst1) == id(lst3))  # True - same object
-print(lst1 is lst3)           # True
-
-# Modification affects both
-lst3.append(4)
-print(lst1)  # [1, 2, 3, 4] - both modified
-```
-
 ## Common Patterns
 
 ### Checking Object Identity
 
 ```python
-# Use is/is not instead of id() directly - cleaner
+# Use is/is not instead of id() directly - cleaner and faster
 x = [1, 2, 3]
 y = x
 z = [1, 2, 3]
@@ -108,7 +65,7 @@ if x is y:  # O(1) - equivalent to id(x) == id(y)
 if x is not z:  # O(1)
     print("Different objects")
 
-# Avoid - using id() directly (less readable)
+# Avoid - using id() directly (less readable and slower)
 if id(x) == id(y):
     print("Same object")
 ```
@@ -172,49 +129,6 @@ a['b'] = b  # Create cycle
 print(has_cycle(a))  # True - cycle found
 ```
 
-## ID vs Equality
-
-### Difference: == vs is
-
-```python
-# == checks value equality
-x = [1, 2, 3]
-y = [1, 2, 3]
-print(x == y)  # True - same content
-
-# is checks object identity
-print(x is y)  # False - different objects
-print(id(x) == id(y))  # False - equivalent
-
-# For immutables, often same
-a = (1, 2, 3)
-b = (1, 2, 3)
-print(a == b)  # True
-print(a is b)  # Might be True or False (optimization)
-
-# For None, always same object
-c = None
-d = None
-print(c is d)  # Always True
-print(id(c) == id(d))  # Always True
-```
-
-### Hashing and ID
-
-```python
-# Hash and ID are different
-x = 42
-print(hash(x))  # Hash value - O(1)
-print(id(x))    # Object ID - O(1)
-
-# Different objects can have same hash
-# But will have different IDs
-y = [1, 2, 3]
-z = [1, 2, 3]
-# hash(y) raises TypeError (unhashable)
-# But id(y) != id(z)
-```
-
 ## Implementation Details
 
 ### CPython: ID is Memory Address
@@ -281,68 +195,6 @@ cache[obj] = "data"     # O(1) - cleaner
 value = cache[obj]      # O(1)
 ```
 
-## Debugging and Inspection
-
-### Object Tracking
-
-```python
-# Use id() to track object creation - O(1)
-import sys
-
-def track_objects():
-    """Show all objects and their IDs"""
-    objects = {}
-    
-    # Get all objects (memory intensive!)
-    for obj in gc.get_objects():  # O(n)
-        obj_id = id(obj)  # O(1)
-        obj_type = type(obj).__name__
-        objects[obj_id] = obj_type
-    
-    return objects
-
-# Usage - useful for debugging memory issues
-# import gc
-# tracked = track_objects()
-```
-
-### Identity and Memory
-
-```python
-# id() shows object placement in memory
-x = "hello"
-y = "hello"
-z = x
-
-print(id(x))  # Memory address 1
-print(id(y))  # Memory address 2 or 1 (interned)
-print(id(z))  # Memory address 1 (same as x)
-
-# Shows that z and x are same object
-print(x is z)  # True
-```
-
-## Special Cases
-
-### None and Booleans
-
-```python
-# None is singleton - always same object
-a = None
-b = None
-print(id(a) == id(b))  # Always True
-print(a is b)          # Always True
-
-# Booleans are singletons
-true1 = True
-true2 = True
-print(id(true1) == id(true2))  # Always True
-
-false1 = False
-false2 = False
-print(id(false1) == id(false2))  # Always True
-```
-
 ## Version Notes
 
 - **Python 2.x**: id() available, returns memory address in CPython
@@ -362,12 +214,9 @@ print(id(false1) == id(false2))  # Always True
 - Use `is` operator instead of `id(x) == id(y)`
 - Use `is None` for None checks (standard)
 - Use id() for debugging and object tracking
-- Remember ID is implementation-dependent
 
 ❌ **Avoid**:
 
 - Using id() in regular code (use `is` instead)
-- Assuming specific ID values
 - Relying on ID across Python sessions
 - Using ID as hash for collections (use hash() or object itself)
-- Comparing IDs between different Python implementations

docs/builtins/locals_func.md

@@ -269,38 +269,19 @@ def slow_access(a, b, c):
     return locals()['a'] + locals()['b'] + locals()['c']  # Creates dict 3 times!
 ```
 
-## Best Practices
+## Related Functions
 
-```python
-# ✅ DO: Use locals() for debugging/introspection
-def debug():
-    x = 1
-    y = 2
-    print(locals())  # Good for understanding scope
-
-# ✅ DO: Use it for variable existence checks
-if 'var_name' in locals():
-    process(locals()['var_name'])
-
-# ✅ DO: Understand it's a snapshot
-local_dict = locals()
-x = 10
-print('x' in local_dict)  # False - dict is a snapshot
+- [globals() Function](globals.md) - Get global symbol table
+- [dir() Function](dir.md) - List accessible names
+- [vars() Function](vars.md) - Get __dict__ of object
 
-# ❌ DON'T: Rely on modifications to locals()
-locals()['x'] = 20
-print(x)  # Still old value (except in class body)
+## Best Practices
 
-# ❌ DON'T: Use in tight loops for performance
-for i in range(1000000):
-    v = locals()['var']  # Inefficient - creates dict each time
+✅ **Do**:
 
-# ❌ DON'T: Serialize/pickle locals() dict
-# It contains references that may not be picklable
-```
+- Use locals() for debugging/introspection
+- Use it for variable existence checks
 
-## Related Functions
+❌ **Avoid**:
 
-- [globals() Function](globals.md) - Get global symbol table
-- [dir() Function](dir.md) - List accessible names
-- [vars() Function](vars.md) - Get __dict__ of object
+- Use in tight loops for performance