Docs: Add resource/grp/xml docs and fix stdlib complexities

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

Author: heikkitoivonen

DOCUMENTATION_STATUS.md

@@ -5,8 +5,8 @@ This document tracks the coverage of built-in functions, types, and standard lib
 ## Overview
 
 - **Total Items**: 317 (150 builtins + 167 stdlib modules)
-- **Documented**: 382 (174 builtins + 208 stdlib)
-- **Coverage**: 120.5%
+- **Documented**: 387 (174 builtins + 213 stdlib)
+- **Coverage**: 122.1%
 
 **Note**: Coverage exceeds 100% because comprehensive documentation files (like `exceptions.md`) cover multiple individual items, and we document deprecated/removed modules for historical reference.
 
@@ -203,7 +203,7 @@ Complete coverage of all built-in functions, types, exceptions, and constants:
 
 ## Standard Library Modules
 
-**Coverage: 124.6% (208/167)**
+**Coverage: 127.5% (213/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 (208/208)
+### ✅ ALL MODULES COMPLETE (213/213)
 
-All 105 previously undocumented stdlib modules have been added:
+All 110 previously undocumented stdlib modules have been added:
 
 **Utilities & System (20)**
 - ✅ `ast` - Abstract syntax trees
@@ -416,19 +416,24 @@ All 105 previously undocumented stdlib modules have been added:
 - ✅ `this` - Zen of Python
 - ✅ `readline` - Line-editing support
 
-**System & Locale (5)**
+**System & Locale (7)**
 - ✅ `netrc` - Netrc file handling
 - ✅ `site` - Site-specific configuration
 - ✅ `crypt` - Password hashing (Unix)
 - ✅ `fcntl` - File control (Unix)
 - ✅ `termios` - POSIX terminal I/O control
+- ✅ `resource` - Process resource limits (Unix)
+- ✅ `grp` - Unix group database
 
-**Internal & Testing (5)**
+**Internal & Testing (11)**
 - ✅ `concurrent` - Concurrency (parent package)
 - ✅ `copyreg` - Copy registration
 - ✅ `encodings` - Built-in encodings
 - ✅ `xdrlib` - XDR serialization
 - ✅ `xml` - XML parsing base
+- ✅ `xml.dom` - DOM XML APIs
+- ✅ `xml.sax` - SAX XML APIs
+- ✅ `xml.etree.ElementTree` - ElementTree XML APIs
 - ✅ `binascii` - Binary-ASCII conversion
 - ✅ `marshal` - Object serialization
 - ✅ `webbrowser` - Browser control

data/documentation_audit.json

@@ -168,8 +168,8 @@
   },
   "stdlib": {
     "total": 167,
-    "documented": 208,
-    "coverage_percent": 124.6,
+    "documented": 213,
+    "coverage_percent": 127.5,
     "missing": [
       "audit_documentation",
       "cProfile",
@@ -179,7 +179,7 @@
   },
   "summary": {
     "total_items": 317,
-    "total_documented": 382,
-    "overall_coverage_percent": 120.5
+    "total_documented": 387,
+    "overall_coverage_percent": 122.1
   }
 }

docs/stdlib/grp.md

@@ -0,0 +1,51 @@
+# grp Module
+
+The `grp` module provides access to the Unix group database (e.g., `/etc/group`). It is Unix-only.
+
+!!! warning "Unix-only"
+    The `grp` module is not available on Windows and may not be available on some Python builds.
+
+## Complexity Reference
+
+| Operation | Time | Space | Notes |
+|-----------|------|-------|-------|
+| `grp.getgrnam(name)` | O(n) | O(1) | Linear scan of group database in many implementations |
+| `grp.getgrgid(gid)` | O(n) | O(1) | Linear scan of group database in many implementations |
+| `grp.getgrall()` | O(n) | O(n) | Reads all group entries |
+
+## Common Operations
+
+### Lookup a Group by Name
+
+```python
+import grp
+
+# Lookup group by name - O(n)
+group = grp.getgrnam('staff')
+print(group.gr_name, group.gr_gid)
+```
+
+### Lookup a Group by GID
+
+```python
+import grp
+
+# Lookup group by id - O(n)
+group = grp.getgrgid(20)
+print(group.gr_name, group.gr_mem)
+```
+
+### List All Groups
+
+```python
+import grp
+
+# List all groups - O(n)
+for entry in grp.getgrall():
+    print(entry.gr_name)
+```
+
+## Related Modules
+
+- [pwd Module](pwd.md) - Unix password database
+- [os Module](os.md) - Process and user information

docs/stdlib/queue.md

@@ -1,6 +1,6 @@
 # queue - Synchronized Queue Data Structures
 
-The `queue` module provides thread-safe queue implementations for coordinating work between multiple producer and consumer threads or processes.
+The `queue` module provides thread-safe queue implementations for coordinating work between multiple producer and consumer threads.
 
 ## Complexity Reference
 
@@ -10,11 +10,13 @@ The `queue` module provides thread-safe queue implementations for coordinating w
 | `Queue.get()` | O(1) | O(1) | Remove item (blocks if empty) |
 | `Queue.put_nowait()` | O(1) | O(1) | Add item (raises Full if full) |
 | `Queue.get_nowait()` | O(1) | O(1) | Remove item (raises Empty if empty) |
-| `Queue.qsize()` | O(1) | O(1) | Get approximate size |
-| `PriorityQueue.put()` | O(log n) | O(1) | Add with priority |
-| `PriorityQueue.get()` | O(log n) | O(1) | Get highest priority |
+| `Queue.qsize()` | O(1) | O(1) | Approximate size (not reliable under contention) |
+| `PriorityQueue.put()` | O(log n) | O(1) amortized | Add with priority (heap push) |
+| `PriorityQueue.get()` | O(log n) | O(1) amortized | Remove smallest-priority item (heap pop) |
 | `LifoQueue.put()` | O(1) amortized | O(1) | Add item (LIFO); uses list internally |
 | `LifoQueue.get()` | O(1) | O(1) | Remove item (LIFO) |
+| `SimpleQueue.put()` | O(1) | O(1) | Add item (unbounded, never blocks on size) |
+| `SimpleQueue.get()` | O(1) | O(1) | Remove item (blocks if empty) |
 
 ## Basic Queue (FIFO)
 
@@ -86,7 +88,6 @@ print("All tasks complete")
 
 ```python
 from queue import PriorityQueue
-import heapq
 
 # Create priority queue - O(1)
 pq = PriorityQueue()

docs/stdlib/random.md

@@ -9,12 +9,12 @@ The `random` module provides pseudo-random number generation for various probabi
 | `random.random()` | O(1) | O(1) | Uniform [0.0, 1.0) |
 | `random.randint(a, b)` | O(1) | O(1) | Uniform integer |
 | `random.choice(seq)` | O(1) | O(1) | Random element |
-| `random.choices(seq, k)` | O(k) | O(k) | k items with replacement |
-| `random.sample(seq, k)` | O(k) typical, O(n) worst | O(k) | k items without replacement; O(n) when k is close to n |
+| `random.choices(seq, k)` | O(k) to O(n + k log n) | O(k) to O(n + k) | O(k) if no weights; builds cumulative weights if provided |
+| `random.sample(seq, k)` | O(k) to O(n) | O(k) to O(n) | Copies population when k is large or input is set/dict |
 | `random.shuffle(list)` | O(n) | O(1) | In-place Fisher-Yates shuffle |
 | `random.uniform(a, b)` | O(1) | O(1) | Uniform float |
 | `random.gauss(mu, sigma)` | O(1) | O(1) | Gaussian distribution |
-| `random.seed(a)` | O(1) | O(1) | Set seed |
+| `random.seed(a)` | O(len(a)) | O(1) | Seed processing depends on input type |
 
 ## Basic Random Number Generation
 
@@ -79,13 +79,13 @@ import random
 lst = [1, 2, 3, 4, 5]
 selections = random.choices(lst, k=3)  # [5, 2, 5] - O(3)
 
-# Weighted selection - O(k)
+# Weighted selection - O(n + k log n)
 colors = ['red', 'blue', 'green']
 weights = [0.5, 0.3, 0.2]
-draws = random.choices(colors, weights=weights, k=100)  # O(100)
+draws = random.choices(colors, weights=weights, k=100)  # O(n + k log n)
 
-# Without replacement (sample) - O(k)
-unique = random.sample(lst, k=3)  # [3, 1, 4] - O(3), no duplicates
+# Without replacement (sample) - O(k) to O(n)
+unique = random.sample(lst, k=3)  # [3, 1, 4] - no duplicates
 ```
 
 ### Shuffling
@@ -188,7 +188,7 @@ def random_partition(arr, low, high):
     pivot_idx = random.randint(low, high)  # O(1)
     # ... partition logic
 
-# Shuffle-sort (random sort for testing) - O(n log n) expected
+# Shuffle-sort (bogosort) - expected O(n!) time
 def shuffle_sort(arr):
     while not is_sorted(arr):
         random.shuffle(arr)  # O(n) per iteration
@@ -277,7 +277,7 @@ np.random.shuffle(big_arr)  # O(1000000)
 import random
 from bisect import bisect
 
-# Simple weighted choice with normalization - O(1)
+# Simple weighted choice with normalization - O(n)
 def weighted_choice(choices, weights):
     total = sum(weights)
     r = random.uniform(0, total)
@@ -288,11 +288,11 @@ def weighted_choice(choices, weights):
         upto += weight
     return choices[-1]
 
-# O(k) where k = number of choices
-# Better: use random.choices() - O(k) but optimized in C
+# O(n) where n = number of choices
+# Better: use random.choices() when you want multiple draws
 items = ['a', 'b', 'c']
 weights = [0.5, 0.3, 0.2]
-result = random.choices(items, weights=weights, k=1)[0]  # O(1)
+result = random.choices(items, weights=weights, k=1)[0]  # O(n)
 ```
 
 ## State Management
@@ -357,8 +357,8 @@ array = np.random.random(1000)  # Fast bulk generation
 import random
 import threading
 
-# Random module is NOT thread-safe
-# Each thread should have its own Random instance
+# The module-level RNG is safe to call from multiple threads, but it shares state.
+# Use a per-thread Random instance to avoid contention and interleaved sequences.
 
 def worker(seed):
     rng = random.Random(seed)  # O(1) - thread-safe
@@ -376,8 +376,7 @@ threads = [
 
 - **Python 2.x and 3.x**: Core functions available in all versions
 - **Python 3.6+**: `random.choices()` added
-- **Python 3.9+**: Algorithm improvements for better quality randomness
-- **Different platforms**: May have slight variations in random sequence
+- **Different versions**: Some algorithms (e.g., `randrange`) have changed for quality, so sequences may differ
 
 ## Related Modules
 

docs/stdlib/re.md

@@ -7,29 +7,29 @@ The `re` module provides regular expression matching operations.
 | Operation | Time | Space | Notes |
 |-----------|------|-------|-------|
 | `re.compile(pattern)` | O(n) | O(n) | n = pattern length |
-| `pattern.match(string)` | O(m) typical, O(n*m) worst | O(m) | Worst case with backtracking |
-| `pattern.fullmatch(string)` | O(m) typical, O(n*m) worst | O(m) | Match entire string |
-| `pattern.search(string)` | O(m) typical, O(n*m) worst | O(m) | Searches full string |
-| `pattern.findall(string)` | O(n*m) | O(k) | k = number of matches |
-| `pattern.finditer(string)` | O(n) per match | O(1) per match | Lazy iteration |
-| `pattern.sub(repl, string)` | O(n*m) | O(m) | n = pattern, m = string |
-| `pattern.subn(repl, string)` | O(n*m) | O(m) | Like sub, returns (newstr, count) |
-| `pattern.split(string)` | O(n*m) | O(m) | n = pattern, m = string |
-| `re.match(pattern, string)` | O(n + m) typical | O(m) | Compiles + matches; cached up to ~512; O(n*m) worst with backtracking |
-| `re.search(pattern, string)` | O(n + m) typical | O(m) | Compiles + matches; cached up to ~512; O(n*m) worst with backtracking |
+| `pattern.match(string)` | O(m) typical, O(exp) worst | O(m) | Worst case from backtracking |
+| `pattern.fullmatch(string)` | O(m) typical, O(exp) worst | O(m) | Match entire string |
+| `pattern.search(string)` | O(m) typical, O(exp) worst | O(m) | Searches full string |
+| `pattern.findall(string)` | O(m) typical, O(exp) worst | O(k) | k = total matches |
+| `pattern.finditer(string)` | O(m) typical, O(exp) worst | O(1) | Lazy iteration |
+| `pattern.sub(repl, string)` | O(m) typical, O(exp) worst | O(m) | Match + build output |
+| `pattern.subn(repl, string)` | O(m) typical, O(exp) worst | O(m) | Like sub, returns (newstr, count) |
+| `pattern.split(string)` | O(m) typical, O(exp) worst | O(m) | Split by pattern |
+| `re.match(pattern, string)` | O(n + m) typical, O(exp) worst | O(m) | Compiles on cache miss; cached up to ~512 |
+| `re.search(pattern, string)` | O(n + m) typical, O(exp) worst | O(m) | Compiles on cache miss; cached up to ~512 |
 | `re.escape(string)` | O(n) | O(n) | Escape special regex characters |
-| `re.purge()` | O(1) | O(1) | Clear compiled pattern cache |
-| `re.error` | - | - | Exception for invalid patterns (alias: PatternError in 3.13+) |
+| `re.purge()` | O(c) | O(1) | Clear compiled pattern cache (c = cache size) |
+| `re.error` | - | - | Exception for invalid patterns |
 
-*Note: Worst case for catastrophic backtracking; typical cases are much better.
+*Note: "O(exp)" denotes exponential time in m from catastrophic backtracking; typical cases are much better.
 
 ## Pattern Caching
 
 | Operation | Time | Space | Notes |
 |-----------|------|-------|-------|
-| `re.match(pattern, s)` | O(n + m) | O(n+m) | Pattern compiled, cached up to ~512 |
+| `re.match(pattern, s)` | O(n + m) | O(n+m) | Compiles on cache miss; cached up to ~512 |
 | `compiled = re.compile(p)` | O(n) | O(n) | Explicit compilation |
-| `compiled.match(s)` | O(n*m)* | O(m) | Uses cached pattern |
+| `compiled.match(s)` | O(m) typical, O(exp) worst | O(m) | Uses the already-compiled pattern |
 
 CPython caches the last ~512 compiled patterns automatically.
 
@@ -178,7 +178,7 @@ print(f"Time: {end - start}s")  # Fast!
 ```python
 import re
 
-# Bad: recompiles pattern each time - O(n²)
+# Bad: recompiles pattern each time
 for line in large_file:
     if re.search(r'\d+', line):  # Recompiles each time!
         process(line)
@@ -254,7 +254,7 @@ match = pattern.search(text)  # O(m)
 
 ## Version Notes
 
-- **Python 3.7+**: `regex` module available as alternative
+- **Third-party**: The `regex` package provides additional features
 - **Python 3.x**: `re` module is standard
 - **Python 2.x**: Similar but with different Unicode handling
 

docs/stdlib/reprlib.md

@@ -6,8 +6,8 @@ The `reprlib` module provides an alternative repr() implementation that produces
 
 | Operation | Time | Space | Notes |
 |-----------|------|-------|-------|
-| `repr()` | O(n) | O(n) | n = visible characters |
-| Truncation | O(1) | O(1) | Configurable limit |
+| `repr()` | O(k) | O(k) | k = items/chars visited up to limits |
+| Truncation | O(k) | O(1) | Limit reduces traversal/output, not O(1) |
 
 ## Creating Readable Representations