Docs: Update stdlib gc-gzip

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**: 376 (174 builtins + 202 stdlib)
-- **Coverage**: 118.6%
+- **Documented**: 377 (174 builtins + 203 stdlib)
+- **Coverage**: 118.9%
 
 **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: 121.0% (202/167)**
+**Coverage: 121.6% (203/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,15 +305,16 @@ All file and I/O modules now documented:
 - ✅ `shutil` - High-level file operations
 - ✅ `tempfile` - Temporary files
 
-### ✅ ALL MODULES COMPLETE (202/202)
+### ✅ ALL MODULES COMPLETE (203/203)
 
 All 100 previously undocumented stdlib modules have been added:
 
-**Utilities & System (19)**
+**Utilities & System (20)**
 - ✅ `ast` - Abstract syntax trees
 - ✅ `dis` - Disassembler for bytecode
 - ✅ `doctest` - Testing via docstrings
 - ✅ `errno` - Error number constants
+- ✅ `gc` - Garbage collection interface
 - ✅ `getopt` - Command-line option parsing
 - ✅ `gettext` - Internationalization
 - ✅ `keyword` - Python keywords

data/documentation_audit.json

@@ -168,8 +168,8 @@
   },
   "stdlib": {
     "total": 167,
-    "documented": 202,
-    "coverage_percent": 121.0,
+    "documented": 203,
+    "coverage_percent": 121.6,
     "missing": [
       "audit_documentation",
       "cProfile",
@@ -179,7 +179,7 @@
   },
   "summary": {
     "total_items": 317,
-    "total_documented": 376,
-    "overall_coverage_percent": 118.6
+    "total_documented": 377,
+    "overall_coverage_percent": 118.9
   }
 }

docs/stdlib/gc.md

@@ -0,0 +1,89 @@
+# gc Module
+
+The `gc` module provides access to the garbage collector for tracking and controlling cyclic
+references in Python.
+
+## Complexity Reference
+
+| Operation | Time | Space | Notes |
+|-----------|------|-------|-------|
+| `enable()` | O(1) | O(1) | Enable cyclic GC |
+| `disable()` | O(1) | O(1) | Disable cyclic GC |
+| `isenabled()` | O(1) | O(1) | Check GC status |
+| `collect()` | O(n) | O(n) | n = tracked objects |
+| `set_threshold()` | O(1) | O(1) | Update generation thresholds |
+| `get_threshold()` | O(1) | O(1) | Read thresholds |
+| `get_count()` | O(1) | O(1) | Generation allocation counts |
+| `get_stats()` | O(1) | O(1) | GC stats per generation |
+| `set_debug()` | O(1) | O(1) | Set debug flags |
+| `get_debug()` | O(1) | O(1) | Read debug flags |
+| `get_objects()` | O(n) | O(n) | Return tracked objects |
+| `get_referrers()` | O(n) | O(n) | Find objects referring to targets |
+| `get_referents()` | O(n) | O(n) | Find objects referenced by targets |
+| `is_tracked()` | O(1) | O(1) | Check GC tracking |
+| `is_finalized()` | O(1) | O(1) | Check finalization state |
+| `freeze()` | O(n) | O(n) | Freeze tracked objects |
+| `unfreeze()` | O(n) | O(n) | Unfreeze tracked objects |
+| `get_freeze_count()` | O(1) | O(1) | Count frozen objects |
+
+## Common Operations
+
+### Trigger Collection
+
+```python
+import gc
+
+# Force collection - O(n)
+collected = gc.collect()
+print(collected)
+```
+
+### Enable or Disable GC
+
+```python
+import gc
+
+# Disable cyclic GC - O(1)
+gc.disable()
+
+# Enable cyclic GC - O(1)
+gc.enable()
+
+# Check state - O(1)
+if gc.isenabled():
+    print("GC enabled")
+```
+
+### Inspect Thresholds and Counters
+
+```python
+import gc
+
+thresholds = gc.get_threshold()  # O(1)
+counts = gc.get_count()          # O(1)
+```
+
+### Reference Inspection
+
+```python
+import gc
+
+obj = []
+referrers = gc.get_referrers(obj)  # O(n)
+referents = gc.get_referents(obj)  # O(n)
+```
+
+## Debugging Flags
+
+Common flags include:
+
+- `DEBUG_STATS`
+- `DEBUG_COLLECTABLE`
+- `DEBUG_UNCOLLECTABLE`
+- `DEBUG_SAVEALL`
+- `DEBUG_LEAK`
+
+## Related Documentation
+
+- [sys Module](sys.md)
+- [weakref Module](weakref.md)

docs/stdlib/genericpath.md

@@ -6,52 +6,24 @@ The `genericpath` module provides generic pathname utilities shared by `posixpat
 
 | Operation | Time | Space | Notes |
 |-----------|------|-------|-------|
-| `commonpath(list)` | O(n*m) | O(n) | Find common path prefix |
 | `commonprefix(list)` | O(n*m) | O(n) | Find common string prefix |
 | `exists(path)` | O(1) | O(1) | Check if path exists |
+| `lexists(path)` | O(1) | O(1) | Check if path exists (even if broken symlink) |
 | `isfile(path)` | O(1) | O(1) | Check if file |
 | `isdir(path)` | O(1) | O(1) | Check if directory |
 | `islink(path)` | O(1) | O(1) | Check if symlink |
+| `isjunction(path)` | O(1) | O(1) | Check Windows junction |
+| `isdevdrive(path)` | O(1) | O(1) | Check Windows Dev Drive |
 | `getsize(path)` | O(1) | O(1) | Get file size |
 | `getmtime(path)` | O(1) | O(1) | Get modification time |
 | `getatime(path)` | O(1) | O(1) | Get access time |
 | `getctime(path)` | O(1) | O(1) | Get creation time |
+| `samefile(a, b)` | O(1) | O(1) | Compare underlying file identity |
+| `samestat(stat1, stat2)` | O(1) | O(1) | Compare stat results |
+| `sameopenfile(fd1, fd2)` | O(1) | O(1) | Compare open file descriptors |
 
 ## Path Comparison
 
-### commonpath()
-
-#### Time Complexity: O(n*m)
-
-Where n = number of paths, m = length of shortest path.
-
-```python
-import genericpath
-
-# Find common path: O(n*m)
-paths = ['/home/user/docs', '/home/user/downloads', '/home/user/desktop']
-common = genericpath.commonpath(paths)  # O(n*m)
-# Result: '/home/user'
-
-# Single path
-common = genericpath.commonpath(['/home/user/file'])  # O(1)
-# Result: '/home/user/file'
-
-# No common path
-common = genericpath.commonpath(['/home', '/var', '/usr'])  # O(n*m)
-# Result: '/'
-```
-
-#### Space Complexity: O(n)
-
-```python
-import genericpath
-
-# Result and temporary storage
-paths = ['/path1', '/path2', '/path3']
-common = genericpath.commonpath(paths)  # O(n) space for result
-```
-
 ### commonprefix()
 
 #### Time Complexity: O(n*m)
@@ -82,9 +54,23 @@ paths = ['a' * 1000, 'a' * 1000, 'b' * 1000]
 prefix = genericpath.commonprefix(paths)  # O(m) space for result
 ```
 
+File identity helpers can compare paths or stat results:
+
+```python
+import genericpath
+import os
+
+same = genericpath.samefile("a.txt", "b.txt")  # O(1)
+same = genericpath.sameopenfile(os.open("a.txt", os.O_RDONLY),
+                                os.open("a.txt", os.O_RDONLY))  # O(1)
+stat1 = os.stat("a.txt")
+stat2 = os.stat("b.txt")
+same = genericpath.samestat(stat1, stat2)  # O(1)
+```
+
 ## Path Existence and Type Checks
 
-### exists(), isfile(), isdir()
+### exists(), lexists(), isfile(), isdir()
 
 #### Time Complexity: O(1)
 
@@ -95,6 +81,9 @@ import genericpath
 if genericpath.exists('/path/to/file'):  # O(1) stat
     print('exists')
 
+if genericpath.lexists('/path/to/maybe-link'):  # O(1) lstat
+    print('exists (even if broken symlink)')
+
 if genericpath.isfile('/path/to/file'):  # O(1) stat
     print('is file')
 
@@ -136,6 +125,18 @@ import genericpath
 is_link = genericpath.islink('/path')  # O(1) space
 ```
 
+Windows-only checks also include junctions and Dev Drives:
+
+```python
+import genericpath
+
+if genericpath.isjunction('C:\\\\path\\\\to\\\\junction'):  # O(1)
+    print('is junction')
+
+if genericpath.isdevdrive('C:\\\\path'):  # O(1)
+    print('is dev drive')
+```
+
 ## File Statistics
 
 ### getsize(), getmtime(), getatime(), getctime()
@@ -328,6 +329,8 @@ size = stat_info.st_size
 # Both O(1), os.stat more flexible
 ```
 
+`ALLOW_MISSING` is a public sentinel used by `os.path.realpath()` to allow missing path components.
+
 ## Platform Independence
 
 ```python
@@ -340,6 +343,7 @@ exists = genericpath.exists(path)  # O(1) on any platform
 size = genericpath.getsize(path)   # O(1) on any platform
 ```
 
+
 ## Version Notes
 
 - **Python 3.x**: Full Unicode support

docs/stdlib/getopt.md

@@ -7,6 +7,7 @@ The `getopt` module provides command-line argument parsing using the GNU getopt(
 | Operation | Time | Space | Notes |
 |-----------|------|-------|-------|
 | `getopt.getopt()` | O(n) | O(n) | n = command-line args |
+| `getopt.gnu_getopt()` | O(n) | O(n) | GNU-style parsing |
 | Argument parsing | O(n) | O(n) | Parse and store |
 
 ## Parsing Command-Line Arguments
@@ -35,6 +36,7 @@ for opt, arg in opts:
         print(f"Version: {arg}")
 ```
 
+
 ## Related Documentation
 
 - [argparse Module](argparse.md)

docs/stdlib/getpass.md

@@ -8,6 +8,9 @@ The `getpass` module provides utilities for prompting the user for passwords wit
 |-----------|------|-------|-------|
 | `getpass()` | O(n) | O(n) | n = password length |
 | `getuser()` | O(1) | O(1) | Get current user |
+| `fallback_getpass()` | O(n) | O(n) | Fallback prompt (echoed) |
+| `unix_getpass()` | O(n) | O(n) | Unix-specific prompt |
+| `win_getpass()` | O(n) | O(n) | Windows-specific prompt |
 
 ## Common Operations
 
@@ -27,6 +30,9 @@ password = getpass.getpass(prompt="Enter secret: ")
 # Input is not echoed to screen
 ```
 
+If terminal control isn't available, `getpass()` may fall back to `fallback_getpass()` and raise
+`GetPassWarning`. Platform-specific helpers `unix_getpass()` and `win_getpass()` are also exposed.
+
 ### Getting Current User
 
 ```python

docs/stdlib/gettext.md

@@ -7,6 +7,10 @@ The `gettext` module provides internationalization (i18n) support for Python app
 | Operation | Time | Space | Notes |
 |-----------|------|-------|-------|
 | `gettext.install()` | O(n) | O(n) | Load translations |
+| `translation()` | O(n) | O(n) | Load translation catalog |
+| `find()` | O(n) | O(1) | Locate translation file |
+| `bindtextdomain()` | O(1) | O(1) | Set global locale dir |
+| `textdomain()` | O(1) | O(1) | Set default domain |
 | Message lookup | O(1) | O(1) | Hash-based dict |
 | `ngettext()` | O(1) | O(1) | Plural form selection |
 

docs/stdlib/glob.md

@@ -10,6 +10,11 @@ The `glob` module provides Unix shell-style pathname expansion using wildcard pa
 | `iglob()` function | O(1) init | O(1) per item | Iterator, lazy evaluation |
 | Pattern matching | O(n) | O(1) | n = files in directory |
 | Recursive search `**` | O(d) | O(1) per file | d = depth of directory tree |
+| `escape()` | O(n) | O(n) | Escape metacharacters |
+| `has_magic()` | O(n) | O(1) | Detect pattern magic |
+| `glob0()` | O(1) | O(1) | Single-directory literal/implicit match |
+| `glob1()` | O(n) | O(n) | One-level pattern match |
+| `translate()` | O(n) | O(n) | Convert glob to regex |
 
 ## Basic Globbing
 
@@ -234,6 +239,7 @@ pattern = glob.escape(filename)
 result = glob.glob(pattern)
 ```
 
+
 ## Common Use Cases
 
 ### Find Recent Files

docs/stdlib/graphlib.md

@@ -12,6 +12,7 @@ The `graphlib` module provides a topological sort implementation for resolving d
 | `get_ready()` | O(1) amortized | O(k) | Get all ready nodes as tuple, k = ready count |
 | `done(node)` | O(d) | O(1) | Mark done, d = node degree |
 | `static_order()` | O(v + e) | O(v + e) | Complete topological sort |
+| `CycleError` | O(1) | O(1) | Exception raised on cycles |
 
 ## Basic Topological Sort
 

docs/stdlib/gzip.md

@@ -11,6 +11,8 @@ The `gzip` module provides GZIP compression and decompression functionality.
 | `GzipFile.write(data)` | O(n) | O(k) | Compress and write, n = input size, k = buffer |
 | `compress(data)` | O(n) | O(n) | Compress bytes (DEFLATE is linear in practice) |
 | `decompress(data)` | O(m) | O(m) | Decompress bytes |
+| `GzipFile()` | O(1) | O(1) | Create file object |
+| `BadGzipFile` | O(1) | O(1) | Exception for invalid gzip data |
 
 ## Opening Files