Docs: Fix stdlib introspection and io

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

Author: heikkitoivonen

docs/stdlib/idlelib.md

@@ -6,8 +6,8 @@ The `idlelib` module provides the Python IDLE editor library, used to build the
 
 | Operation | Time | Space | Notes |
 |-----------|------|-------|-------|
-| Editor initialization | O(1) | O(n) | n = UI components |
-| Syntax highlighting | O(n) | O(n) | n = line length |
+| Editor initialization | Varies | Varies | Depends on Tk setup and platform |
+| Syntax highlighting | Varies | Varies | Depends on highlighter and text size processed |
 
 ## IDLE Components
 

docs/stdlib/imaplib.md

@@ -6,9 +6,9 @@ The `imaplib` module provides IMAP4 client functionality for accessing email on
 
 | Operation | Time | Space | Notes |
 |-----------|------|-------|-------|
-| `login()` | O(1) | O(1) | Authentication |
-| List mailboxes | O(n) | O(n) | n = mailboxes |
-| Fetch messages | O(n) | O(n) | n = messages |
+| `login()` | Varies | Varies | Network round‑trip, server auth |
+| List mailboxes | Varies | Varies | Depends on server and response size |
+| Fetch messages | Varies | Varies | Depends on server, message sizes, and network |
 
 ## Accessing IMAP Mailboxes
 

docs/stdlib/importlib.md

@@ -6,11 +6,10 @@ The `importlib` module provides tools for importing modules and working with Pyt
 
 | Operation | Time | Space | Notes |
 |-----------|------|-------|-------|
-| `import_module(name)` | O(n) | O(n) | n = import depth |
-| `find_loader(name)` | O(1) | O(1) | Check sys.modules |
-| `reload(module)` | O(n) | O(n) | n = module size |
-| `import_module(package)` | O(n+m) | O(n+m) | n = submodules |
-| `resources.files()` | O(1) | O(1) | Get resource path |
+| `import_module(name)` | Varies | Varies | Depends on cache, meta path, and I/O |
+| `importlib.util.find_spec(name)` | Varies | Varies | Depends on finders and file system |
+| `reload(module)` | Varies | Varies | Re-executes module code |
+| `resources.files(package)` | Varies | Varies | May import package or access loaders |
 
 ## Common Operations
 
@@ -19,17 +18,17 @@ The `importlib` module provides tools for importing modules and working with Pyt
 ```python
 import importlib
 
-# O(n) where n = import depth/module size
+# Cost depends on loaders, cache, and filesystem
 # Prefer this over __import__()
 module = importlib.import_module('os.path')
 
 # Equivalent to: import os.path
-import_module('json')  # O(n)
-import_module('collections.abc')  # O(n)
+import_module('json')
+import_module('collections.abc')
 
-# From cached sys.modules if already imported - O(1)
+# From cached sys.modules if already imported
 module = importlib.import_module('json')
-module = importlib.import_module('json')  # Second call is O(1)
+module = importlib.import_module('json')  # Second call is cached
 ```
 
 ### Reloading Modules
@@ -38,7 +37,6 @@ module = importlib.import_module('json')  # Second call is O(1)
 import importlib
 import mymodule
 
-# O(n) where n = module size
 # Re-executes module code
 importlib.reload(mymodule)
 
@@ -52,33 +50,31 @@ importlib.reload(mymodule)
 import importlib.util
 import sys
 
-# O(1) - check if module is cached
 spec = importlib.util.find_spec('json')
 if spec is not None:
-    print(f"Found: {spec.origin}")  # O(1)
+    print(f"Found: {spec.origin}")
 
-# Get loader - O(1) if cached, O(n) if needs import
+# Get loader
 loader = spec.loader
 
-# Manual import from spec - O(n)
+# Manual import from spec (executes module code)
 module = importlib.util.module_from_spec(spec)
 sys.modules[spec.name] = module
-spec.loader.exec_module(module)  # O(n)
+spec.loader.exec_module(module)
 ```
 
 ### Working with Submodules
 
 ```python
 import importlib
 
-# O(n) where n = total submodules
 package = importlib.import_module('email')
 
-# Get submodule - O(m) where m = submodule size
+# Get submodule
 mime = importlib.import_module('email.mime')
 text = importlib.import_module('email.mime.text')
 
-# Check if submodule exists - O(1) after first import
+# Check if submodule exists after first import
 import email.mime.text
 print('email.mime.text' in sys.modules)  # O(1)
 ```
@@ -92,12 +88,12 @@ import importlib
 import sys
 
 def try_import(module_name, default=None):
-    """Safely import module - O(n) or O(1)"""
+    """Safely import module; cost depends on cache and loaders."""
     try:
-        if module_name in sys.modules:  # O(1) check
+        if module_name in sys.modules:  # Cached
             return sys.modules[module_name]
 
-        return importlib.import_module(module_name)  # O(n)
+        return importlib.import_module(module_name)
     except ImportError:
         return default
 
@@ -122,7 +118,7 @@ class PluginManager:
         self.plugins = {}
 
     def load_plugin(self, name, module_path):
-        """Load plugin module - O(n) where n = module size"""
+        """Load plugin module; cost depends on loaders and module code."""
         try:
             module = importlib.import_module(module_path)
 
@@ -139,7 +135,6 @@ class PluginManager:
         """Get cached plugin - O(1)"""
         return self.plugins.get(name)
 
-# Usage - O(n) per plugin
 manager = PluginManager()
 manager.load_plugin('plugin1', 'plugins.plugin1')
 manager.load_plugin('plugin2', 'plugins.plugin2')
@@ -155,11 +150,11 @@ import importlib
 
 module = importlib.import_module('collections')
 
-# O(1) - hasattr checks __dict__
+# hasattr checks __dict__
 if hasattr(module, 'deque'):
     Deque = getattr(module, 'deque')
 
-# O(n) - iterate all attributes where n = module size
+# iterate all attributes
 for attr_name in dir(module):  # O(n)
     attr = getattr(module, attr_name)
     if callable(attr):
@@ -172,7 +167,7 @@ for attr_name in dir(module):  # O(n)
 import importlib.util
 
 def module_available(name):
-    """Check if module can be imported - O(1) cache or O(n) search"""
+    """Check if module can be imported; cost depends on finders."""
     spec = importlib.util.find_spec(name)
     return spec is not None
 
@@ -181,8 +176,8 @@ available_mods = {}
 
 def is_available(name):
     if name not in available_mods:
-        available_mods[name] = module_available(name)  # O(n) first time
-    return available_mods[name]  # O(1) after cached
+        available_mods[name] = module_available(name)
+    return available_mods[name]  # Cached
 ```
 
 ## Performance Tips
@@ -192,12 +187,12 @@ def is_available(name):
 ```python
 import importlib
 
-# Bad: O(n) import each time
+# Bad: import each time
 def process():
     json = importlib.import_module('json')
     return json.loads(data)
 
-# Good: O(1) after first import
+# Good: reuse cached module after first import
 json = importlib.import_module('json')
 
 def process():
@@ -209,7 +204,7 @@ def process():
 ```python
 import importlib.util
 
-# Efficient existence check - O(1) if cached or path-based
+# Efficient existence check when cached or path-based
 if importlib.util.find_spec('numpy'):
     import numpy
     # Use numpy
@@ -225,22 +220,19 @@ def ensure_modules(module_list):
     """Import multiple modules efficiently"""
     loaded = {}
     for name in module_list:
-        if name not in sys.modules:  # O(1) check
-            loaded[name] = importlib.import_module(name)  # O(n)
+        if name not in sys.modules:  # Cached check
+            loaded[name] = importlib.import_module(name)
         else:
-            loaded[name] = sys.modules[name]  # O(1)
+            loaded[name] = sys.modules[name]
     return loaded
 
-# O(k*n) where k = module count, n = avg module size
+# Cost depends on module count, loaders, and module code
 modules = ensure_modules(['json', 'os', 'sys'])
 ```
 
 ## Version Notes
 
-- **Python 2.7**: Limited support
-- **Python 3.1+**: importlib added
-- **Python 3.4+**: importlib.util for detailed control
-- **Python 3.7+**: Simplified import machinery
+- **Python 3.x**: `importlib` and `importlib.util` are available
 
 ## Related Documentation
 

docs/stdlib/inspect.md

@@ -7,11 +7,11 @@ The `inspect` module provides utilities for inspecting live objects, including m
 | Operation | Time | Space | Notes |
 |-----------|------|-------|-------|
 | `getmembers(obj)` | O(m) | O(m) | Get all members of object |
-| `getdoc(obj)` | O(1) | O(n) | Get docstring |
+| `getdoc(obj)` | O(n) | O(n) | n = docstring length |
 | `signature(func)` | O(p) | O(p) | Get function signature |
-| `getsource(obj)` | O(n) | O(n) | Get source code |
-| `getsourcelines(obj)` | O(n) | O(n) | Get source + line numbers |
-| `getfile(obj)` | O(1) | O(1) | Get file path |
+| `getsource(obj)` | Varies | Varies | File I/O + inspect cache |
+| `getsourcelines(obj)` | Varies | Varies | File I/O + inspect cache |
+| `getfile(obj)` | Varies | Varies | May inspect metadata and loaders |
 | `isfunction(obj)` | O(1) | O(1) | Check if function |
 | `ismethod(obj)` | O(1) | O(1) | Check if method |
 | `isclass(obj)` | O(1) | O(1) | Check if class |
@@ -120,14 +120,14 @@ Where n = source code size.
 ```python
 import inspect
 
-# Get source: O(n) to read file
-source = inspect.getsource(func)  # O(n)
+# Get source: file I/O and caching behavior vary
+source = inspect.getsource(func)
 
-# Get lines with line numbers: O(n)
-source_lines, start_line = inspect.getsourcelines(func)  # O(n)
+# Get lines with line numbers
+source_lines, start_line = inspect.getsourcelines(func)
 
 # Source is read from disk and cached
-# Subsequent calls may be O(1) from cache
+# Subsequent calls may be faster if cached
 ```
 
 #### Space Complexity: O(n)
@@ -304,9 +304,7 @@ frame = sys._getframe(0)  # O(1) vs O(d)
 
 ## Version Notes
 
-- **Python 3.3+**: `signature()` added
-- **Python 3.5+**: Improvements to signature handling
-- **Python 3.10+**: Parameter behavior changes
+- **Python 3.x**: `inspect` utilities are available
 
 ## Related Documentation
 

docs/stdlib/io.md

@@ -69,7 +69,7 @@ stream.seek(0)
 for line in stream:  # O(n) iteration
     print(f"Line: {line.strip()}")
 
-# Clear stream - O(1)
+# Close stream - O(1)
 stream.close()
 ```
 
@@ -243,16 +243,16 @@ from io import BytesIO
 
 stream = BytesIO(b"x" * 1000)
 
+def process(data):
+    print(f"Processing {len(data)} bytes")
+
 # Read in chunks - O(n) total, O(1) per chunk
 chunk_size = 100
 while True:
     chunk = stream.read(chunk_size)  # O(k) per chunk
     if not chunk:
         break
     process(chunk)  # Process chunk
-
-def process(data):
-    print(f"Processing {len(data)} bytes")
 ```
 
 ### Seek Performance

docs/stdlib/ipaddress.md

@@ -13,7 +13,7 @@ The `ipaddress` module provides utilities for creating and manipulating IPv4 and
 | `ip_address(addr)` | O(n) | O(1) | Auto-detect IP type |
 | `ip_network(addr)` | O(n) | O(1) | Auto-detect network type |
 | Address membership | O(1) | O(1) | Check in network |
-| Subnet iteration | O(2^k) | O(1) | Generate subnets |
+| Subnet iteration | O(s) | O(1) | s = number of subnets generated |
 
 ## IP Address Creation
 
@@ -189,10 +189,12 @@ if is_private('10.0.0.1'):
 from ipaddress import IPv4Network
 
 def find_common_supernet(networks):
-    """Find supernet containing all networks: O(n)"""
-    networks = [IPv4Network(n) for n in networks]  # O(n)
-    supernet = IPv4Network.supernet_of(networks)  # O(n)
-    return supernet
+    """Find a supernet containing all networks (naive)."""
+    nets = [IPv4Network(n) for n in networks]
+    candidate = nets[0]
+    while not all(candidate.supernet_of(n) or candidate == n for n in nets):
+        candidate = candidate.supernet()
+    return candidate
 ```
 
 ### Parse Mixed Address Types

docs/stdlib/itertools.md

@@ -17,7 +17,6 @@ The `itertools` module provides efficient looping tools for creating iterators a
 
 | Function | Time | Space | Notes |
 |----------|------|-------|-------|
-| `filter(pred, iter)` | O(n) total | O(1) | Filter items |
 | `filterfalse(pred, iter)` | O(n) total | O(1) | Opposite filter |
 | `compress(iter, sel)` | O(n) total | O(1) | Mask-based filter |
 | `dropwhile(pred, iter)` | O(n) total | O(1) | Drop while true |
@@ -44,11 +43,11 @@ The `itertools` module provides efficient looping tools for creating iterators a
 | `combinations(iterable, r)` | O(C(n,r)) total | O(r) per item | All r-combinations |
 | `combinations_with_replacement(iter, r)` | O(C(n+r-1,r)) total | O(r) per item | Combinations allowing repeats |
 | `permutations(iterable, r)` | O(P(n,r)) total | O(r) per item | All permutations |
-| `product(iter1, iter2, ...)` | O(n₁×n₂×...×nₖ) | O(n) init + O(k) per item | Cartesian product; stores all inputs in memory first |
+| `product(iter1, iter2, ...)` | O(n₁×n₂×...×nₖ) | O(Σnᵢ) init + O(k) per item | Cartesian product; stores all inputs in memory first |
 
 ## Memory Characteristics
 
-All itertools functions are lazy - they generate items on demand without storing the entire result.
+All itertools functions are lazy iterators, but some cache input data (e.g., `cycle`, `tee`, `product`).
 
 ```python
 import itertools