Docs: Add math and mmap

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**: 377 (174 builtins + 203 stdlib)
-- **Coverage**: 118.9%
+- **Documented**: 379 (174 builtins + 205 stdlib)
+- **Coverage**: 119.6%
 
 **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.6% (203/167)**
+**Coverage: 122.8% (205/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 (203/203)
+### ✅ ALL MODULES COMPLETE (205/205)
 
-All 100 previously undocumented stdlib modules have been added:
+All 102 previously undocumented stdlib modules have been added:
 
 **Utilities & System (20)**
 - ✅ `ast` - Abstract syntax trees
@@ -368,6 +368,9 @@ All 100 previously undocumented stdlib modules have been added:
 - ✅ `tty` - Terminal control
 - ✅ `zipimport` - Zip import support
 
+**Memory Mapping (1)**
+- ✅ `mmap` - Memory-mapped file access
+
 **Parsing & Compilation (12)**
 - ✅ `codeop` - Compile Python source
 - ✅ `code` - Code evaluation
@@ -382,7 +385,8 @@ All 100 previously undocumented stdlib modules have been added:
 - ✅ `symtable` - Symbol table
 - ✅ `token` - Token types
 
-**Number Operations (1)**
+**Number Operations (2)**
+- ✅ `math` - Floating-point math functions
 - ✅ `zoneinfo` - IANA time zone database
 
 **GUI & Interface (4)**

data/documentation_audit.json

@@ -168,8 +168,8 @@
   },
   "stdlib": {
     "total": 167,
-    "documented": 203,
-    "coverage_percent": 121.6,
+    "documented": 205,
+    "coverage_percent": 122.8,
     "missing": [
       "audit_documentation",
       "cProfile",
@@ -179,7 +179,7 @@
   },
   "summary": {
     "total_items": 317,
-    "total_documented": 377,
-    "overall_coverage_percent": 118.9
+    "total_documented": 379,
+    "overall_coverage_percent": 119.6
   }
 }

docs/stdlib/mailbox.md

@@ -6,8 +6,8 @@ The `mailbox` module provides classes for reading, writing, and manipulating var
 
 | Operation | Time | Space | Notes |
 |-----------|------|-------|-------|
-| Open mailbox | O(n) | O(n) | n = messages |
-| Add message | O(1) amortized | O(1) | Append operation |
+| Open mailbox | Varies | Varies | Depends on mailbox format and indexing |
+| Add message | Varies | Varies | Depends on mailbox type and file I/O |
 | Iterate messages | O(n) | O(1) | Sequential access |
 
 ## Working with Mailboxes
@@ -17,7 +17,7 @@ The `mailbox` module provides classes for reading, writing, and manipulating var
 ```python
 import mailbox
 
-# Open mbox - O(n)
+# Open mbox - cost depends on format and file size
 mbox = mailbox.mbox('mail.mbox')
 
 # Iterate - O(n)
@@ -34,18 +34,18 @@ mbox.close()
 import mailbox
 from email.message import EmailMessage
 
-# Open - O(n)
+# Open - cost depends on format and file size
 mbox = mailbox.mbox('mail.mbox')
 
 # Create message - O(1)
 msg = EmailMessage()
 msg['Subject'] = 'Test'
 msg.set_content('Hello')
 
-# Add - O(1)
+# Add - cost depends on mailbox type and I/O
 key = mbox.add(msg)
 
-# Flush to disk - O(n)
+# Flush to disk - cost depends on pending changes
 mbox.flush()
 mbox.close()
 ```

docs/stdlib/math.md

@@ -0,0 +1,100 @@
+# math Module Complexity
+
+The `math` module provides fast floating-point math functions and a few integer-specific helpers.
+
+## Complexity Reference
+
+| Operation | Time | Space | Notes |
+|-----------|------|-------|-------|
+| `math.sqrt(x)` | O(1) | O(1) | Floating-point operation |
+| `math.log(x[, base])` | O(1) | O(1) | Floating-point operation |
+| `math.sin/cos/tan(x)` | O(1) | O(1) | Floating-point operation |
+| `math.hypot(*coords)` | O(n) | O(1) | n = number of coordinates |
+| `math.fsum(iterable)` | O(n) | O(1) | Accurate summation of n values |
+| `math.isclose(a, b)` | O(1) | O(1) | Floating-point comparison |
+| `math.gcd(a, b)` | Varies | O(1) | Depends on integer size |
+| `math.lcm(a, b)` | Varies | O(1) | Depends on integer size |
+| `math.factorial(n)` | Varies | Varies | Big-int cost grows with n |
+| `math.comb(n, k)` | Varies | Varies | Big-int cost grows with n and k |
+| `math.perm(n, k)` | Varies | Varies | Big-int cost grows with n and k |
+
+!!! warning "Floating-point precision"
+    Most `math` functions operate on binary floating-point numbers. Results are fast but may be imprecise
+    for some decimal fractions. Use `decimal` for exact decimal arithmetic.
+
+## Common Operations
+
+### Basic Transcendentals
+
+```python
+import math
+
+x = 2.0
+
+# O(1)
+root = math.sqrt(x)
+log2 = math.log(x, 2)
+angle = math.sin(math.pi / 6)
+```
+
+### Hypotenuse and Distance
+
+```python
+import math
+
+# O(n) in number of coordinates
+r2 = math.hypot(3.0, 4.0)          # 5.0
+r3 = math.hypot(1.0, 2.0, 2.0)     # 3.0
+```
+
+### Accurate Summation
+
+```python
+import math
+
+values = [1e100, 1.0, -1e100]
+
+# Regular sum may lose precision
+regular = sum(values)       # 0.0
+
+# fsum keeps extra precision
+accurate = math.fsum(values)  # 1.0
+```
+
+### Integers: gcd, lcm, factorial, comb, perm
+
+```python
+import math
+
+# gcd/lcm
+g = math.gcd(84, 30)   # 6
+l = math.lcm(6, 10)    # 30
+
+# factorial, combinations, permutations
+f = math.factorial(10)     # 3628800
+c = math.comb(10, 3)       # 120
+p = math.perm(10, 3)       # 720
+```
+
+### Robust Comparisons
+
+```python
+import math
+
+# Avoid direct equality for floats
+math.isclose(0.1 + 0.2, 0.3)  # True
+```
+
+## Performance Notes
+
+- Floating-point operations are typically constant time and CPU-bound.
+- Integer-heavy functions (`factorial`, `comb`, `perm`, `gcd`, `lcm`) scale with operand size.
+- `fsum` provides better accuracy with a small constant-factor cost over `sum`.
+
+## Related Modules
+
+- [cmath Module](cmath.md) - Complex-number math
+- [decimal Module](decimal.md) - Decimal arithmetic
+- [fractions Module](fractions.md) - Rational arithmetic
+- [statistics Module](statistics.md) - Descriptive statistics
+- [random Module](random.md) - Random numbers

docs/stdlib/mimetypes.md

@@ -10,7 +10,7 @@ The `mimetypes` module provides support for working with MIME types, mapping fil
 | `guess_type(url)` | O(1) | O(1) | Lookup MIME type |
 | `guess_extension(type)` | O(1) | O(1) | Get extension |
 | `add_type(type, ext)` | O(1) | O(1) | Register mapping |
-| `read(filename)` | O(n) | O(n) | n = file size |
+| `read_mime_types(filename)` | O(n) | O(n) | n = file size |
 
 ## Common Operations
 
@@ -43,7 +43,7 @@ ext = mimetypes.guess_extension('application/pdf')
 
 # Get all possible extensions - O(k) where k = extension count
 exts = mimetypes.guess_all_extensions('text/plain')
-# Returns: ['.txt', '.asc', '.c', .h', ...]
+# Returns: ['.txt', '.asc', '.c', '.h', ...]
 ```
 
 ## Common Use Cases
@@ -61,16 +61,12 @@ def get_content_type(filename):
     if mime_type is None:
         mime_type = 'application/octet-stream'
 
-    # O(1) to format header
-    content_type = mime_type
-    if encoding:
-        content_type += f'; charset={encoding}'
-    
-    return content_type
+    # encoding from guess_type is compression (e.g., 'gzip')
+    return mime_type, encoding
 
 # Usage - O(1)
-ct = get_content_type('document.pdf')  # 'application/pdf'
-ct = get_content_type('data.csv')      # 'text/csv'
+ct, enc = get_content_type('document.pdf')  # ('application/pdf', None)
+ct, enc = get_content_type('data.csv')      # ('text/csv', None)
 ```
 
 ### Serving Files in Web Applications
@@ -158,7 +154,7 @@ def initialize_mimetypes(custom_files=None):
         for filepath in custom_files:
             if os.path.exists(filepath):
                 # O(n) to read and parse file
-                mimetypes.read(filepath)
+                mimetypes.read_mime_types(filepath)
 
 # Usage - O(n+m)
 initialize_mimetypes(['custom-types.txt'])
@@ -242,6 +238,7 @@ for file in files:
 
 ```python
 import mimetypes
+from pathlib import Path
 
 def get_accurate_type(filename):
     """Get accurate MIME type - O(1)"""

docs/stdlib/mmap.md

@@ -0,0 +1,78 @@
+# mmap Module Complexity
+
+The `mmap` module provides memory-mapped file support for efficient random access to file contents.
+
+## Complexity Reference
+
+| Operation | Time | Space | Notes |
+|-----------|------|-------|-------|
+| `mmap.mmap(fileno, length, ...)` | Varies | Varies | Depends on OS and mapping size |
+| `mmap.read(n)` | O(n) | O(n) | n = bytes read |
+| `mmap.write(data)` | O(n) | O(1) | n = bytes written |
+| `mmap.seek(pos[, whence])` | O(1) | O(1) | Pointer movement |
+| `mmap.find(sub[, start[, end]])` | O(n) | O(1) | n = search range |
+| `mmap.flush()` | Varies | O(1) | Depends on OS and dirty pages |
+| `mmap.close()` | O(1) | O(1) | Unmap and close |
+
+!!! warning "Platform-dependent behavior"
+    `mmap` performance depends on the operating system, filesystem, and page cache behavior.
+    The costs shown here describe typical asymptotic behavior, not wall-clock guarantees.
+
+## Common Operations
+
+### Creating a Mapping
+
+```python
+import mmap
+
+with open('data.bin', 'rb') as f:
+    mm = mmap.mmap(f.fileno(), 0, access=mmap.ACCESS_READ)
+    print(mm.size())  # total size
+    mm.close()
+```
+
+### Reading and Writing
+
+```python
+import mmap
+
+with open('data.bin', 'r+b') as f:
+    mm = mmap.mmap(f.fileno(), 0)
+
+    # Read 16 bytes
+    chunk = mm.read(16)
+
+    # Write bytes in place
+    mm.seek(0)
+    mm.write(b'HELLO')
+
+    mm.flush()
+    mm.close()
+```
+
+### Searching
+
+```python
+import mmap
+
+with open('data.bin', 'rb') as f:
+    mm = mmap.mmap(f.fileno(), 0, access=mmap.ACCESS_READ)
+
+    idx = mm.find(b'needle')  # O(n) search
+    if idx != -1:
+        print('Found at', idx)
+
+    mm.close()
+```
+
+## Performance Notes
+
+- Mapping large files avoids copying data into Python space for random access.
+- Reads/writes still move data between kernel and user space when accessed.
+- For sequential reads of large files, buffered I/O can be comparable or faster.
+
+## Related Modules
+
+- [io Module](io.md)
+- [os Module](os.md)
+- [pathlib Module](pathlib.md)

docs/stdlib/modulefinder.md

@@ -6,8 +6,8 @@ The `modulefinder` module finds all modules that a Python script imports, useful
 
 | Operation | Time | Space | Notes |
 |-----------|------|-------|-------|
-| Find dependencies | O(n) | O(n) | n = imported modules |
-| Build import graph | O(n) | O(n) | Track relationships |
+| Find dependencies | Varies | Varies | Depends on code paths and import hooks |
+| Build import graph | Varies | Varies | Depends on modules discovered |
 
 ## Analyzing Module Dependencies
 
@@ -19,14 +19,14 @@ from modulefinder import ModuleFinder
 # Create finder - O(1)
 mf = ModuleFinder()
 
-# Analyze script - O(n)
+# Analyze script - cost depends on imports and code paths
 mf.run_script('myapp.py')
 
 # Get results - O(1)
 print("Modules:", mf.modules)
 print("Bad imports:", mf.badimports)
 
-# Report - O(n)
+# Report - cost depends on number of modules
 mf.report()
 ```