Fix: Complete remaining stdlib correctness audit

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

Author: heikkitoivonen

docs/stdlib/asynchat.md

@@ -323,6 +323,6 @@ async def main():
 ## Related Documentation
 
 - [asyncio Module](asyncio.md) - **USE THIS INSTEAD**
-- [asyncore Module](asyncore.md) - Also deprecated
+- [asyncore Module](asyncore.md) - Also removed in 3.12
 - [socket Module](socket.md) - Low-level sockets
 - [concurrent.futures Module](concurrent_futures.md) - Alternative for concurrency

docs/stdlib/asyncore.md

@@ -345,7 +345,7 @@ async def main():
 
 # asyncio event loop (MODERN):
 # - Uses best available: epoll/kqueue/IOCP
-# - O(log m) to check ready sockets
+# - Readiness handling is implementation-dependent (not a simple O(log m) rule)
 # - Scales to thousands of connections
 # - Coroutine-based (async/await)
 ```
@@ -360,6 +360,6 @@ async def main():
 ## Related Documentation
 
 - [asyncio Module](asyncio.md) - **USE THIS INSTEAD**
-- [asynchat Module](asynchat.md) - Also deprecated
+- [asynchat Module](asynchat.md) - Also removed in 3.12
 - [selectors Module](selectors.md) - Low-level multiplexed I/O
 - [socket Module](socket.md) - Low-level sockets

docs/stdlib/cgi.md

@@ -18,7 +18,6 @@ The `cgi` module provides utilities for parsing CGI (Common Gateway Interface) f
 ### Query String Parsing
 
 ```python
-import cgi
 from urllib.parse import parse_qs, parse_qsl
 
 # Modern approach (use urllib.parse instead)
@@ -97,7 +96,8 @@ def main():
     name = form.getvalue('name', 'Guest')
 
     # Generate response
-    print(f"<h1>Hello, {cgi.escape(name)}!</h1>")
+    from html import escape
+    print(f"<h1>Hello, {escape(name)}!</h1>")
 
 if __name__ == "__main__":
     main()
@@ -202,6 +202,6 @@ form = cgi.FieldStorage()
 ## Related Modules
 
 - [urllib.parse Module](urllib.md) - URL parsing and encoding
-- [html Module](#) - HTML utilities
+- [html Module](html.md) - HTML utilities
 - [urllib.request Module](urllib.md) - URL requests
 - [wsgiref Module](wsgiref.md) - WSGI reference implementation

docs/stdlib/cgitb.md

@@ -231,7 +231,7 @@ cgitb.enable()
 ## Best Practices
 
 ```python
-# ✅ DO: Use error handling in development
+# ✅ Legacy only (Python <= 3.12): use cgitb in development
 import cgitb
 cgitb.enable()  # Use only in development
 
@@ -253,4 +253,4 @@ print("<p>An error occurred. Please try again later.</p>")
 - [logging Module](logging.md) - Error logging
 - [traceback Module](traceback.md) - Traceback handling
 - [sys Module](sys.md) - System information
-- [html Module](#) - HTML utilities
+- [html Module](html.md) - HTML utilities

docs/stdlib/imp.md

@@ -1,8 +1,10 @@
 # imp Module
 
-The `imp` module provides functions for importing modules. This module is deprecated since Python 3.4 and removed in Python 3.12.
+⚠️ **REMOVED IN PYTHON 3.12**: The `imp` module was deprecated since Python 3.4 and removed in Python 3.12.
 
-## Deprecation Notice
+The `imp` module provided functions for importing modules.
+
+## Removal Notice
 
 ```python
 # ❌ DON'T: Use imp module (deprecated, removed in 3.12)
@@ -223,5 +225,5 @@ print(config.DATABASE_URL)
 
 - [importlib Module](importlib.md) - Modern import machinery
 - [sys Module](sys.md) - System module list
-- [importlib.util Module](#) - Utility functions
+- [importlib Module](importlib.md) - Utility functions (`importlib.util`)
 - [pathlib Module](pathlib.md) - File path handling

docs/stdlib/lib2to3.md

@@ -1,6 +1,8 @@
 # lib2to3 Module
 
-The `lib2to3` module provides tools for converting Python 2 code to Python 3, using a refactoring framework with syntax tree transformations.
+⚠️ **REMOVED IN PYTHON 3.13**: The `lib2to3` module and `2to3` tool were deprecated in Python 3.11 and removed in Python 3.13.
+
+The `lib2to3` module provided tools for converting Python 2 code to Python 3, using a refactoring framework with syntax tree transformations.
 
 ## Complexity Reference
 
@@ -15,7 +17,7 @@ The `lib2to3` module provides tools for converting Python 2 code to Python 3, us
 ### Using 2to3 Tool
 
 ```bash
-# Command-line usage
+# Legacy command-line usage (Python <= 3.12)
 2to3 -w script.py          # Convert in place
 2to3 -d script.py          # Dry run (show diffs)
 2to3 -f all script.py      # Apply all fixers
@@ -25,6 +27,7 @@ The `lib2to3` module provides tools for converting Python 2 code to Python 3, us
 ### Programmatic Conversion
 
 ```python
+# Legacy API usage (Python <= 3.12)
 from lib2to3 import refactor
 
 # Create refactoring tool - O(1)

docs/stdlib/sndhdr.md

@@ -1,8 +1,10 @@
 # sndhdr Module
 
-The `sndhdr` module identifies the format of sound files and returns information about sound file headers. This module is deprecated and removed in Python 3.13.
+⚠️ **REMOVED IN PYTHON 3.13**: The `sndhdr` module was deprecated in Python 3.11 and removed in Python 3.13.
 
-## Deprecation Notice
+The `sndhdr` module identified the format of sound files and returned information about sound file headers.
+
+## Removal Notice
 
 ```python
 # ❌ DON'T: Use sndhdr (deprecated, removed in 3.13)
@@ -14,7 +16,6 @@ info = sndhdr.what('sound.au')
 # - soundfile library
 # - audioread library
 # - wave module (for WAV files)
-# - sunau module (for AU files)
 ```
 
 ## Complexity Reference
@@ -76,37 +77,6 @@ print(f"Duration: {info['duration']:.2f} seconds")
 print(f"Sample rate: {info['sample_rate']} Hz")
 ```
 
-### Using sunau Module (Built-in)
-
-```python
-# ✅ RECOMMENDED: Use sunau for AU files
-import sunau
-
-def inspect_au(filepath):
-    """
-    Inspect AU sound file header.
-    
-    Time: O(1)
-    Space: O(1)
-    """
-    with sunau.open(filepath, 'rb') as f:
-        # Get parameters - O(1)
-        (channels, sample_width, sample_rate, nframes, compression, compression_name) = f.getparams()
-        
-        return {
-            'channels': channels,
-            'sample_width': sample_width,
-            'sample_rate': sample_rate,
-            'frames': nframes,
-            'compression': compression_name,
-            'duration': nframes / sample_rate if sample_rate > 0 else 0
-        }
-
-info = inspect_au('audio.au')
-print(f"Compression: {info['compression']}")
-print(f"Duration: {info['duration']:.2f} seconds")
-```
-
 ### Using scipy (Third-party)
 
 ```python
@@ -195,7 +165,7 @@ def inspect_sound(filepath):
 
 ```python
 import wave
-import sunau
+import soundfile as sf
 from pathlib import Path
 
 def inspect_sound(filepath):
@@ -219,19 +189,15 @@ def inspect_sound(filepath):
                 'frames': params.nframes
             }
 
-    elif suffix == '.au':
-        with sunau.open(filepath, 'rb') as f:
-            params = f.getparams()
-            return {
-                'format': 'AU',
-                'channels': params.nchannels,
-                'sample_width': params.sampwidth,
-                'sample_rate': params.framerate,
-                'frames': params.nframes
-            }
-    
-    else:
-        raise ValueError(f"Unsupported format: {suffix}")
+    # Fallback for other audio formats (including .au, if supported)
+    info = sf.info(filepath)
+    return {
+        'format': info.format,
+        'channels': info.channels,
+        'sample_width': None,
+        'sample_rate': info.samplerate,
+        'frames': info.frames,
+    }
 
 # Usage
 info = inspect_sound('audio.wav')
@@ -241,7 +207,6 @@ print(f"Sample rate: {info['sample_rate']} Hz")
 
 ## Related Modules
 
-- [wave Module](#) - WAV file handling
-- [sunau Module](sunau.md) - AU file handling
+- [wave Module](wave.md) - WAV file handling
 - [aifc Module](aifc.md) - AIFF audio handling
 - [struct Module](struct.md) - Binary data parsing