Docs: Update stdlib p* modules and path/platform notes

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

Author: heikkitoivonen

DOCUMENTATION_STATUS.md

@@ -5,12 +5,12 @@ This document tracks the coverage of built-in functions, types, and standard lib
 ## Overview
 
 - **Total Items**: 317 (150 builtins + 167 stdlib modules)
-- **Documented**: 379 (174 builtins + 205 stdlib)
-- **Coverage**: 119.6%
+- **Documented**: 382 (174 builtins + 208 stdlib)
+- **Coverage**: 120.5%
 
 **Note**: Coverage exceeds 100% because comprehensive documentation files (like `exceptions.md`) cover multiple individual items, and we document deprecated/removed modules for historical reference.
 
-Last updated: January 27, 2026 (Python 3.14 audit)
+Last updated: January 30, 2026 (Python 3.14 audit)
 
 ## Built-in Types & Functions
 
@@ -203,7 +203,7 @@ Complete coverage of all built-in functions, types, exceptions, and constants:
 
 ## Standard Library Modules
 
-**Coverage: 122.8% (205/167)**
+**Coverage: 124.6% (208/167)**
 
 All standard library modules are fully documented, including new Python 3.14 modules. Coverage exceeds 100% due to documentation of deprecated/removed modules for historical reference.
 
@@ -305,9 +305,9 @@ All file and I/O modules now documented:
 - ✅ `shutil` - High-level file operations
 - ✅ `tempfile` - Temporary files
 
-### ✅ ALL MODULES COMPLETE (205/205)
+### ✅ ALL MODULES COMPLETE (208/208)
 
-All 102 previously undocumented stdlib modules have been added:
+All 105 previously undocumented stdlib modules have been added:
 
 **Utilities & System (20)**
 - ✅ `ast` - Abstract syntax trees
@@ -359,22 +359,25 @@ All 102 previously undocumented stdlib modules have been added:
 - ✅ `telnetlib` - Telnet client
 - ✅ `xmlrpc` - XML-RPC protocol
 
-**File & Path Operations (7)**
+**File & Path Operations (9)**
 - ✅ `chunk` - IFF chunk reading
 - ✅ `imghdr` - Image file type detection
 - ✅ `nturl2path` - URL to path conversion
 - ✅ `pipes` - Shell pipeline interface
+- ✅ `posix` - POSIX APIs (low-level)
 - ✅ `pty` - Pseudo-terminal
+- ✅ `pwd` - Unix password database
 - ✅ `tty` - Terminal control
 - ✅ `zipimport` - Zip import support
 
 **Memory Mapping (1)**
 - ✅ `mmap` - Memory-mapped file access
 
-**Parsing & Compilation (12)**
+**Parsing & Compilation (13)**
 - ✅ `codeop` - Compile Python source
 - ✅ `code` - Code evaluation
 - ✅ `py_compile` - Compilation
+- ✅ `pyexpat` - Low-level Expat XML parser
 - ✅ `lib2to3` - Python 2 to 3 conversion
 - ✅ `modulefinder` - Module dependencies
 - ✅ `opcode` - Python opcodes

data/documentation_audit.json

@@ -168,8 +168,8 @@
   },
   "stdlib": {
     "total": 167,
-    "documented": 205,
-    "coverage_percent": 122.8,
+    "documented": 208,
+    "coverage_percent": 124.6,
     "missing": [
       "audit_documentation",
       "cProfile",
@@ -179,7 +179,7 @@
   },
   "summary": {
     "total_items": 317,
-    "total_documented": 379,
-    "overall_coverage_percent": 119.6
+    "total_documented": 382,
+    "overall_coverage_percent": 120.5
   }
 }

docs/stdlib/pathlib.md

@@ -7,8 +7,8 @@ The `pathlib` module provides an object-oriented approach to filesystem path han
 | Method | Time | Space | Notes |
 |--------|------|-------|-------|
 | `Path(str)` | O(n) | O(n) | Create Path from string |
-| `Path.cwd()` | O(1) | O(n) | Get current directory |
-| `Path.home()` | O(1) | O(n) | Get home directory |
+| `Path.cwd()` | O(n) | O(n) | n = length of current directory |
+| `Path.home()` | O(n) | O(n) | n = length of home directory |
 | `Path.exists()` | O(1) | O(1) | Check if path exists |
 | `Path.is_file()` | O(1) | O(1) | Check if path is file |
 | `Path.is_dir()` | O(1) | O(1) | Check if path is directory |
@@ -21,10 +21,10 @@ The `pathlib` module provides an object-oriented approach to filesystem path han
 | `Path.stat()` | O(1) | O(1) | Get file stats |
 | `Path.lstat()` | O(1) | O(1) | Like stat but don't follow symlinks |
 | `Path.resolve()` | O(n) | O(n) | Resolve to absolute path |
-| `Path.absolute()` | O(1) | O(n) | Make absolute without resolving symlinks |
-| `Path.expanduser()` | O(1) | O(n) | Expand ~ to home directory |
-| `Path.iterdir()` | O(d) | O(d) | Iterate directory contents |
-| `Path.walk()` | O(d) | O(d) | Walk directory tree (Python 3.12+) |
+| `Path.absolute()` | O(n) | O(n) | Make absolute without resolving symlinks |
+| `Path.expanduser()` | O(n) | O(n) | Expand ~ to home directory |
+| `Path.iterdir()` | O(d) | O(1) per item | Iterator over directory entries |
+| `Path.walk()` | O(n) | O(d) | n = total entries, d = max depth |
 | `Path.glob(pattern)` | O(n) | O(1) per item | n = directory entries checked, returns iterator |
 | `Path.rglob(pattern)` | O(n) | O(1) per item | n = total tree entries, returns iterator |
 | `Path.mkdir()` | O(1) | O(1) | Create directory |
@@ -35,7 +35,7 @@ The `pathlib` module provides an object-oriented approach to filesystem path han
 | `Path.rmdir()` | O(1) | O(1) | Delete empty directory |
 | `Path.symlink_to(target)` | O(1) | O(1) | Create symlink |
 | `Path.hardlink_to(target)` | O(1) | O(1) | Create hard link |
-| `Path.readlink()` | O(1) | O(n) | Read symlink target |
+| `Path.readlink()` | O(n) | O(n) | n = length of symlink target |
 | `Path.chmod(mode)` | O(1) | O(1) | Change file mode |
 | `Path.lchmod(mode)` | O(1) | O(1) | chmod without following symlinks |
 | `Path.owner()` | O(1) | O(1) | Get owner name |
@@ -64,10 +64,10 @@ path = Path('/home/user/documents/file.txt')  # O(27)
 # Relative path: O(n)
 path = Path('docs/README.md')  # O(13)
 
-# Current directory: O(1) - system call
+# Current directory: O(n) in path length
 cwd = Path.cwd()
 
-# Home directory: O(1) - system call
+# Home directory: O(n) in path length
 home = Path.home()
 ```
 
@@ -164,7 +164,7 @@ for item in path.iterdir():  # O(d)
 count = sum(1 for _ in path.iterdir())  # O(d)
 ```
 
-#### Space Complexity: O(d)
+#### Space Complexity: O(1) per item
 
 ```python
 from pathlib import Path
@@ -293,14 +293,14 @@ path.write_bytes(b'Binary data')  # O(11)
 path.write_text('x' * 1000000)  # O(n)
 ```
 
-#### Space Complexity: O(1)
+#### Space Complexity: O(n)
 
 ```python
 from pathlib import Path
 
-# Streaming write - no buffer needed
+# Encodes to bytes before writing
 content = 'x' * 1000000
-Path('file.txt').write_text(content)  # O(1) extra space
+Path('file.txt').write_text(content)  # O(n) extra space
 ```
 
 ## File System Modifications
@@ -368,13 +368,13 @@ for file in Path('src').rglob('*.py'):  # O(d) to find files
 ```python
 from pathlib import Path
 
-# Build paths: O(1) per operation
+# Build paths: O(n) in total path length
 base = Path('data')
-file = base / 'subdir' / 'file.txt'  # O(1) per /
+file = base / 'subdir' / 'file.txt'  # O(n)
 
 # Multiple files
 for name in files:
-    path = base / name  # O(1) per iteration
+    path = base / name  # O(n) in path length
 ```
 
 ### Safe Deletion

docs/stdlib/pdb.md

@@ -6,9 +6,9 @@ The `pdb` module provides an interactive debugger for Python code, allowing brea
 
 | Operation | Time | Space | Notes |
 |-----------|------|-------|-------|
-| `set_trace()` | O(1) | O(1) | Enter debugger |
-| Breakpoint | O(1) | O(1) | Register break |
-| Step/continue | O(1) | O(1) | Control flow |
+| `set_trace()` | Varies | O(1) | Setup is O(1); interactive runtime is program/user dependent |
+| Breakpoint | O(1) to register | O(1) | Hit checks occur during program execution |
+| Step/continue | Varies | O(1) | Runs until next stop; depends on code executed |
 
 ## Interactive Debugging
 
@@ -18,7 +18,7 @@ The `pdb` module provides an interactive debugger for Python code, allowing brea
 import pdb
 
 def buggy_function(x):
-    # Enter debugger - O(1)
+    # Enter debugger (setup is O(1); runtime depends on program/user)
     pdb.set_trace()
 
     result = x * 2
@@ -37,7 +37,7 @@ import traceback
 try:
     1 / 0
 except Exception:
-    # Debug after exception - O(1)
+    # Debug after exception (setup is O(1); runtime depends on session)
     pdb.post_mortem()
 ```
 

docs/stdlib/pickle.md

@@ -25,7 +25,7 @@ data = {'name': 'Alice', 'age': 30, 'scores': [95, 87, 92]}
 # Serialize to bytes - O(n) where n = object size
 pickled = pickle.dumps(data)
 print(type(pickled))  # <class 'bytes'>
-print(len(pickled))   # ~50 bytes
+print(len(pickled))   # Size varies by protocol and data
 
 # Deserialize from bytes - O(n)
 restored = pickle.loads(pickled)
@@ -57,29 +57,29 @@ import pickle
 
 obj = {'a': 1, 'b': [2, 3, 4]}
 
-# Protocol 0 (ASCII, human-readable) - O(n) slowest
+# Protocol 0 (ASCII, human-readable) - O(n)
 p0 = pickle.dumps(obj, protocol=0)
-print(len(p0))  # Largest
+print(len(p0))  # Often largest, but varies by object
 
 # Protocol 1 (Binary, old) - O(n)
 p1 = pickle.dumps(obj, protocol=1)
-print(len(p1))  # Smaller
+print(len(p1))  # Often smaller than protocol 0
 
 # Protocol 2 (Binary, Python 2.3+) - O(n)
 p2 = pickle.dumps(obj, protocol=2)
-print(len(p2))  # Smaller still
+print(len(p2))  # Often smaller than protocol 1
 
 # Protocol 3 (Binary, Python 3.0+) - O(n)
 p3 = pickle.dumps(obj, protocol=3)
-print(len(p3))  # Even smaller
+print(len(p3))  # Often smaller than protocol 2
 
-# Protocol 4 (Binary, Python 3.4+) - O(n) faster
+# Protocol 4 (Binary, Python 3.4+) - O(n)
 p4 = pickle.dumps(obj, protocol=4)
-print(len(p4))  # Optimized
+print(len(p4))  # Often more compact for many objects
 
-# Protocol 5 (Binary, Python 3.8+) - O(n) fastest
+# Protocol 5 (Binary, Python 3.8+) - O(n)
 p5 = pickle.dumps(obj, protocol=5)
-print(len(p5))  # Smallest and fastest
+print(len(p5))  # Supports out-of-band buffers; size varies
 ```
 
 ### Default Protocol
@@ -216,15 +216,15 @@ class Team:
         self.name = name
         self.members = members  # List of dicts
 
-# Pickle nested structure - O(n*m)
+# Pickle nested structure - O(n) in total object graph size
 team = Team('Team A', [
     {'name': 'Alice', 'role': 'lead'},
     {'name': 'Bob', 'role': 'dev'}
 ])
 
 pickled = pickle.dumps(team)
 
-# Unpickle - O(n*m)
+# Unpickle - O(n) in total object graph size
 restored = pickle.loads(pickled)
 print(restored.name)       # 'Team A'
 print(restored.members[0]) # {'name': 'Alice', ...}
@@ -267,11 +267,11 @@ large_list = list(range(1000000))
 # Method 1: dumps - creates bytes in memory - O(n) space
 data_bytes = pickle.dumps(large_list)  # Large memory usage
 
-# Method 2: dump to file - streams output - O(n) time, O(1) space
+# Method 2: dump to file - streams output - O(n) time, O(n) space for memoization
 with open('large.pkl', 'wb') as f:
     pickle.dump(large_list, f)  # Much more memory efficient
 
-# Method 3: Pickler with file - O(n) time, O(1) space
+# Method 3: Pickler with file - O(n) time, O(n) space for memoization
 with open('large.pkl', 'wb') as f:
     pickler = pickle.Pickler(f)
     pickler.dump(large_list)
@@ -395,7 +395,7 @@ restored = dill.loads(pickled)
 - **Protocol 0**: Slowest, largest, ASCII (rarely use)
 - **Protocol 1-2**: Legacy compatibility
 - **Protocol 3**: Default Python 3, good balance
-- **Protocol 4+**: Better compression, faster for large objects
+- **Protocol 4+**: More compact encoding (no compression), often faster for large objects
 
 ## Best Practices
 

docs/stdlib/pkgutil.md

@@ -6,11 +6,11 @@ The `pkgutil` module provides utilities for working with packages and module sea
 
 | Operation | Time | Space | Notes |
 |-----------|------|-------|-------|
-| `iter_modules(path)` | O(n) | O(n) | n = modules in path |
-| `walk_packages()` | O(n) | O(n) | n = all subpackages |
-| `find_loader(name)` | O(1) avg, O(n) worst | O(1) | Check sys.modules; O(n) worst case due to hash collisions |
-| `get_data(name)` | O(n) | O(n) | n = file size |
-| `extend_path()` | O(n) | O(n) | n = path entries |
+| `iter_modules(path)` | O(n) | O(1) per item | n = modules in path |
+| `walk_packages()` | O(n) | O(n) | n = all subpackages/modules (tracks seen paths) |
+| `find_spec(name)` | O(1) avg, O(p) worst | O(1) | p = sys.meta_path length (import hooks) |
+| `get_data(name)` | O(n) | O(n) | n = file size (plus import overhead) |
+| `extend_path()` | O(p + k) | O(p + k) | p = search path entries, k = .pkg entries |
 
 ## Common Operations
 

docs/stdlib/platform.md

@@ -6,14 +6,14 @@ The `platform` module provides functions to access platform-specific information
 
 | Operation | Time | Space | Notes |
 |-----------|------|-------|-------|
-| `platform()` | O(1) | O(1) | Cached after first call |
-| `system()` | O(1) | O(1) | Cached after first call |
-| `release()` | O(1) | O(1) | Cached after first call |
-| `version()` | O(1) | O(1) | Cached after first call |
-| `machine()` | O(1) | O(1) | Cached after first call |
-| `node()` | O(1) | O(1) | Cached after first call; first call may involve syscall |
+| `platform()` | O(1) cached, O(n) first | O(n) | n = length of result string |
+| `system()` | O(1) cached, O(n) first | O(n) | Derived from uname |
+| `release()` | O(1) cached, O(n) first | O(n) | Derived from uname |
+| `version()` | O(1) cached, O(n) first | O(n) | Derived from uname |
+| `machine()` | O(1) cached, O(n) first | O(n) | Derived from uname |
+| `node()` | O(1) cached, O(n) first | O(n) | Hostname length |
 | `python_version()` | O(1) | O(1) | Static value |
-| `uname()` | O(1) | O(1) | Cached after first call |
+| `uname()` | O(1) cached, O(n) first | O(n) | n = total size of fields |
 
 ## Common Operations
 
@@ -22,20 +22,20 @@ The `platform` module provides functions to access platform-specific information
 ```python
 import platform
 
-# O(1) - get operating system name
+# O(1) after cache; first call O(n)
 os_name = platform.system()  # 'Linux', 'Windows', 'Darwin'
 
-# O(1) - get OS release
+# O(1) after cache; first call O(n)
 os_release = platform.release()  # '5.15.0-1234-generic'
 
-# O(1) - get OS version
+# O(1) after cache; first call O(n)
 os_version = platform.version()
 # '#1234-Ubuntu SMP ...'
 
-# O(1) - get machine architecture
+# O(1) after cache; first call O(n)
 machine = platform.machine()  # 'x86_64', 'arm64'
 
-# O(1) - get hostname
+# O(1) after cache; first call O(n)
 hostname = platform.node()  # 'mycomputer'
 ```
 
@@ -64,15 +64,15 @@ compiler = platform.python_compiler()
 ```python
 import platform
 
-# O(1) - get complete platform description
+# O(1) after cache; first call O(n)
 platform_str = platform.platform()
 # 'Linux-5.15.0-1234-generic-x86_64-with-glibc2.35'
 
-# O(1) - with detailed version
+# O(1) after cache; first call O(n)
 detailed = platform.platform(aliased=True)
 # Uses common OS aliases like 'Ubuntu' instead of 'Linux'
 
-# O(1) - with specific details
+# O(1) after cache; first call O(n)
 custom = platform.platform(aliased=True, terse=True)
 ```
 
@@ -81,7 +81,7 @@ custom = platform.platform(aliased=True, terse=True)
 ```python
 import platform
 
-# O(1) - get uname data (Unix-like systems)
+# O(1) after cache; first call O(n)
 uname_info = platform.uname()
 # Returns: (system, node, release, version, machine, processor)