Docs: Update stdlib docs and add time

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**: 313 (150 builtins + 163 stdlib modules)
-- **Documented**: 385 (174 builtins + 211 stdlib)
-- **Coverage**: 123.0%
+- **Documented**: 386 (174 builtins + 212 stdlib)
+- **Coverage**: 123.3%
 
 **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: 129.4% (211/163)**
+**Coverage: 130.1% (212/163)**
 
 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.
 
@@ -312,11 +312,11 @@ All file and I/O modules now documented:
 - ✅ `shutil` - High-level file operations
 - ✅ `tempfile` - Temporary files
 
-### ✅ ALL MODULES COMPLETE (211/211)
+### ✅ ALL MODULES COMPLETE (212/212)
 
 All 108 previously undocumented stdlib modules have been added:
 
-**Utilities & System (22)**
+**Utilities & System (23)**
 - ✅ `ast` - Abstract syntax trees
 - ✅ `dis` - Disassembler for bytecode
 - ✅ `doctest` - Testing via docstrings
@@ -338,6 +338,7 @@ All 108 previously undocumented stdlib modules have been added:
 - ✅ `stat` - File status constants
 - ✅ `sysconfig` - System configuration
 - ✅ `syslog` - System logger
+- ✅ `time` - Time-related functions
 - ✅ `trace` - Trace execution
 
 **String & Text Processing (4)**

data/documentation_audit.json

@@ -168,8 +168,8 @@
   },
   "stdlib": {
     "total": 163,
-    "documented": 211,
-    "coverage_percent": 129.4,
+    "documented": 212,
+    "coverage_percent": 130.1,
     "missing": [
       "audit_documentation",
       "cProfile",
@@ -179,7 +179,7 @@
   },
   "summary": {
     "total_items": 313,
-    "total_documented": 385,
-    "overall_coverage_percent": 123.0
+    "total_documented": 386,
+    "overall_coverage_percent": 123.3
   }
 }

docs/stdlib/tabnanny.md

@@ -6,8 +6,7 @@ The `tabnanny` module checks Python source files for mixed tabs and spaces in in
 
 | Operation | Time | Space | Notes |
 |-----------|------|-------|-------|
-| Check file | O(n) | O(n) | n = file lines |
-| Verify indent | O(1) | O(1) | Per line |
+| Check file/directory | O(n) | O(d) | n = file tokens scanned, d = max indent depth |
 
 ## Checking Indentation
 
@@ -17,11 +16,7 @@ The `tabnanny` module checks Python source files for mixed tabs and spaces in in
 import tabnanny
 
 # Check file - O(n)
-result = tabnanny.check('myfile.py')
-
-# Returns True if issues found
-if result:
-    print("File has tab/space issues")
+tabnanny.check('myfile.py')  # Prints diagnostics to stdout; returns None
 
 # Or from command line:
 # python -m tabnanny myfile.py

docs/stdlib/tarfile.md

@@ -6,36 +6,33 @@ The `tarfile` module provides tools for working with TAR archives.
 
 | Operation | Time | Space | Notes |
 |-----------|------|-------|-------|
-| `TarFile.open(name)` | O(n) | O(n) | Open and read directory |
+| `TarFile.open(name)` | O(1) | O(1) | Opens archive; no full header scan |
 | `TarFile.getmembers()` | O(n) | O(n) | Get all member info, n = file count |
-| `TarFile.getmember(name)` | O(n) | O(1) | Linear search through headers |
-| `TarFile.extractfile(name)` | O(m) | O(m) | Extract single file, m = size |
-| `TarFile.extract(name)` | O(m) | O(m) | Extract to filesystem |
-| `TarFile.extractall()` | O(m) | O(m) | Extract all files |
+| `TarFile.getmember(name)` | O(n) | O(n) | Loads member list on first call |
+| `TarFile.extractfile(name)` | O(n) | O(1) | Returns file object; reading is O(m) |
+| `TarFile.extract(name)` | O(n + m) | O(k) | n = members, m = file size, k = buffer |
+| `TarFile.extractall()` | O(n + m) | O(n + k) | Member cache for seekable archives |
 | `TarFile.add(name)` | O(m) | O(k) | Add file, k = buffer size |
 
 ## Opening Archives
 
-### Time Complexity: O(n)
-
-Where n = number of files in archive (reading headers).
+### Time Complexity: O(1)
 
 ```python
 import tarfile
 
-# Opening TAR: O(n) where n = number of files
-# Reads all headers sequentially
+# Opening TAR: O(1) relative to archive size
+# Headers are read lazily when you iterate or call getmembers()
 with tarfile.open('archive.tar', 'r') as tar:
-    # O(n) to process headers
-    members = tar.getmembers()  # O(n)
+    members = tar.getmembers()  # O(n) when called
 ```
 
-### Space Complexity: O(n)
+### Space Complexity: O(1) until you load members
 
 ```python
 import tarfile
 
-# Memory for member information
+# Memory for member information is allocated on getmembers()
 with tarfile.open('archive.tar', 'r') as tar:
     # Stores info for all files: O(n)
     members = tar.getmembers()  # O(n) memory
@@ -52,15 +49,16 @@ import tarfile
 
 with tarfile.open('archive.tar', 'r') as tar:
     # Finding member: O(n) linear search
-    # (no index, searches headers sequentially)
+    # (no index; member list is built by scanning headers)
     member = tar.getmember('file.txt')  # O(n)
 
+    # Getting a file object: O(n)
+    f = tar.extractfile('file.txt')  # O(n)
     # Reading file: O(m)
-    f = tar.extractfile('file.txt')  # O(m)
     content = f.read()  # O(m)
 ```
 
-### Space Complexity: O(m)
+### Space Complexity: O(k) unless you read everything
 
 ```python
 import tarfile
@@ -113,37 +111,40 @@ with tarfile.open('archive.tar', 'r') as tar:
 
 ## Extracting Files
 
-### Time Complexity: O(m)
+### Time Complexity: O(n + m)
 
 Where m = total size of extracted files.
 
 ```python
 import tarfile
 
 with tarfile.open('archive.tar', 'r') as tar:
-    # Extract single file: O(m)
-    # m = file size
-    tar.extract('file.txt')  # O(m)
+    # Extract single file: O(n + m)
+    # n = header scan (if not loaded), m = file size
+    tar.extract('file.txt')  # O(n + m)
 
-    # Extract all: O(sum of sizes)
+    # Extract all: O(n + sum of sizes)
     # Processes each file sequentially
-    tar.extractall()  # O(m) where m = total uncompressed size
+    tar.extractall()  # O(n + m) where m = total uncompressed size
 
-    # Extract with path: O(m) + filesystem I/O
-    tar.extractall(path='output_dir')  # O(m)
+    # Extract with path: O(n + m) + filesystem I/O
+    tar.extractall(path='output_dir')  # O(n + m)
 ```
 
-### Space Complexity: O(k)
+### Space Complexity: O(n + k) for seekable archives
 
 Where k = buffer size during extraction.
 
 ```python
 import tarfile
 
-# Extraction uses streaming buffers
+# Extraction uses streaming buffers; seekable archives cache members
 with tarfile.open('archive.tar', 'r') as tar:
-    tar.extractall()  # O(k) space, k = buffer size
-                      # NOT O(m), memory efficient
+    tar.extractall()  # O(n + k) space (member cache + buffers)
+
+# Stream modes avoid member caching
+with tarfile.open('archive.tar', 'r|*') as tar:
+    tar.extractall()  # O(k) space
 ```
 
 ## Creating Archives
@@ -219,6 +220,16 @@ with tarfile.open('archive.tar.xz', 'w:xz') as tar:
     tar.add('file.txt')  # O(m) with highest constant factor
 ```
 
+### Zstandard Compression (tar.zst)
+
+```python
+import tarfile
+
+# Zstandard: fast with tunable compression
+with tarfile.open('archive.tar.zst', 'w:zst') as tar:
+    tar.add('file.txt')  # O(m) with compression overhead
+```
+
 ## Common Patterns
 
 ### Iterating Members
@@ -340,6 +351,7 @@ with tarfile.open('archive.tar.xz', 'w:xz') as tar:
 - **Python 2.7+**: Enhanced features
 - **Python 3.0+**: Improved compression support
 - **Python 3.3+**: Support for XZ compression
+- **Python 3.14+**: Support for Zstandard compression
 
 ## Related Documentation
 

docs/stdlib/tempfile.md

@@ -6,19 +6,21 @@ The `tempfile` module provides utilities for creating and managing temporary fil
 
 | Operation | Time | Space | Notes |
 |-----------|------|-------|-------|
-| `NamedTemporaryFile()` | O(1) | O(1) initial | Create file; O(n) for data written |
-| `TemporaryFile()` | O(1) | O(1) initial | Create file; O(n) for data written |
-| `TemporaryDirectory()` | O(1) | O(1) initial | Create dir; O(n) for files created |
-| `mktemp()` | O(1) | O(n) | Generate temp name (deprecated) |
-| `mkdtemp()` | O(1) | O(n) | Create temp directory safely |
+| `NamedTemporaryFile()` | O(r) | O(1) initial | r = name attempts (<= TMP_MAX) |
+| `TemporaryFile()` | O(r) | O(1) initial | r = name attempts (<= TMP_MAX) |
+| `TemporaryDirectory()` | O(r) | O(1) initial | r = name attempts (<= TMP_MAX) |
+| `mktemp()` | O(r) | O(1) | Generate temp name (deprecated) |
+| `mkdtemp()` | O(r) | O(1) | Create temp directory safely |
 | `gettempdir()` | O(1) | O(1) | Get system temp directory |
 | `gettempprefix()` | O(1) | O(1) | Get temp filename prefix |
 
 ## Named Temporary Files
 
 ### NamedTemporaryFile()
 
-#### Time Complexity: O(1)
+#### Time Complexity: O(r)
+
+Where r = number of name attempts (<= TMP_MAX).
 
 ```python
 import tempfile
@@ -53,20 +55,22 @@ with tempfile.NamedTemporaryFile() as f:
 
 ### TemporaryFile()
 
-#### Time Complexity: O(1)
+#### Time Complexity: O(r)
+
+Where r = number of name attempts (<= TMP_MAX).
 
 ```python
 import tempfile
 
-# In-memory file (Unix)
+# Unnamed temp file; uses O_TMPFILE when supported, otherwise creates and unlinks
 with tempfile.TemporaryFile(mode='w+') as f:
     f.write('data')
     f.seek(0)
     content = f.read()  # O(n) read
     # Auto-deleted
 
-# File-based fallback (Windows)
-# Operation time still O(1) for creation
+# File-based fallback (e.g., when O_TMPFILE is unsupported)
+# Creation time still O(r) for name attempts
 temp = tempfile.TemporaryFile()
 temp.write(b'content')
 temp.close()
@@ -86,7 +90,9 @@ with tempfile.TemporaryFile() as f:
 
 ### TemporaryDirectory()
 
-#### Time Complexity: O(1)
+#### Time Complexity: O(r)
+
+Where r = number of name attempts (<= TMP_MAX).
 
 ```python
 import tempfile
@@ -124,7 +130,9 @@ with tempfile.TemporaryDirectory() as tmpdir:
 
 ### mkdtemp()
 
-#### Time Complexity: O(1)
+#### Time Complexity: O(r)
+
+Where r = number of name attempts (<= TMP_MAX).
 
 ```python
 import tempfile
@@ -140,13 +148,13 @@ tmpdir = tempfile.mkdtemp(prefix='myapp_')
 tmpdir = tempfile.mkdtemp(suffix='_backup')
 ```
 
-#### Space Complexity: O(n)
+#### Space Complexity: O(1)
 
 ```python
 import tempfile
 
 # Directory name stored
-tmpdir = tempfile.mkdtemp()  # O(n) for path string
+tmpdir = tempfile.mkdtemp()  # O(1) extra memory
 ```
 
 ### gettempdir()
@@ -295,11 +303,6 @@ else:  # Unix/Linux
 tmpdir = tempfile.mkdtemp(dir='/custom/path')
 ```
 
-## Version Notes
-
-- **Python 3.10+**: Improved cleanup with weak references
-- **Python 3.12+**: Enhanced security defaults
-
 ## Related Documentation
 
 - [Pathlib Module](pathlib.md) - Object-oriented filesystem paths

docs/stdlib/termios.md

@@ -32,7 +32,7 @@ try:
         new_settings
     )
 
-    # Now stdin is in raw mode
+    # Now stdin is in non-canonical mode (not full raw mode)
     ch = sys.stdin.read(1)
     print(f"Got: {repr(ch)}")
 

docs/stdlib/textwrap.md

@@ -273,15 +273,13 @@ filled = fill(text, width=80)  # O(n) once
 ```python
 from textwrap import wrap
 
-# For very large text, generator approach
-def wrap_large_text(text, width=80):
-    """Wrap large text efficiently."""
-    for line in wrap(text, width=width):  # O(n)
-        yield line  # Lazy evaluation
-
-# Process one line at a time
-for wrapped_line in wrap_large_text(huge_text):
-    process(wrapped_line)
+# wrap() returns a list, so it still holds all lines in memory
+lines = wrap(huge_text, width=80)  # O(n) memory
+
+# For large inputs, wrap per paragraph to limit peak memory
+for paragraph in huge_text.split("\n\n"):
+    for line in wrap(paragraph, width=80):
+        process(line)
 ```
 
 ## TextWrapper Class

docs/stdlib/this.md

@@ -6,14 +6,14 @@ The `this` module displays the Zen of Python, a philosophy guide for Python prog
 
 | Operation | Time | Space | Notes |
 |-----------|------|-------|-------|
-| Import module | O(1) | O(1) | Decodes and prints Zen text |
+| Import module | O(n) | O(n) | n = Zen text length (decode + print) |
 
 ## The Zen of Python
 
 ### Viewing the Zen
 
 ```python
-import this
+import this  # Prints on import
 
 # Prints:
 # The Zen of Python, by Tim Peters