Update: stdlib docs

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**: 387 (174 builtins + 213 stdlib)
-- **Coverage**: 122.1%
+- **Documented**: 389 (174 builtins + 215 stdlib)
+- **Coverage**: 122.7%
 
 **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: 127.5% (213/167)**
+**Coverage: 128.7% (215/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.
 
@@ -224,6 +224,7 @@ All standard library modules are fully documented, including new Python 3.14 mod
 - ✅ `imp` - Import machinery (deprecated)
 - ✅ `plistlib` - Property list format
 - ✅ `sndhdr` - Sound file format detection
+- ✅ `select` - I/O multiplexing
 
 ### ⊘ Excluded Items (4 - intentionally out of scope)
 
@@ -305,11 +306,11 @@ All file and I/O modules now documented:
 - ✅ `shutil` - High-level file operations
 - ✅ `tempfile` - Temporary files
 
-### ✅ ALL MODULES COMPLETE (213/213)
+### ✅ ALL MODULES COMPLETE (215/215)
 
-All 110 previously undocumented stdlib modules have been added:
+All 112 previously undocumented stdlib modules have been added:
 
-**Utilities & System (20)**
+**Utilities & System (22)**
 - ✅ `ast` - Abstract syntax trees
 - ✅ `dis` - Disassembler for bytecode
 - ✅ `doctest` - Testing via docstrings
@@ -327,8 +328,10 @@ All 110 previously undocumented stdlib modules have been added:
 - ✅ `pydoc` - Documentation viewer
 - ✅ `runpy` - Run Python modules
 - ✅ `sched` - Event scheduler
+- ✅ `select` - I/O multiplexing
 - ✅ `stat` - File status constants
 - ✅ `sysconfig` - System configuration
+- ✅ `syslog` - System logger
 - ✅ `trace` - Trace execution
 
 **String & Text Processing (4)**

data/documentation_audit.json

@@ -168,8 +168,8 @@
   },
   "stdlib": {
     "total": 167,
-    "documented": 213,
-    "coverage_percent": 127.5,
+    "documented": 215,
+    "coverage_percent": 128.7,
     "missing": [
       "audit_documentation",
       "cProfile",
@@ -179,7 +179,7 @@
   },
   "summary": {
     "total_items": 317,
-    "total_documented": 387,
-    "overall_coverage_percent": 122.1
+    "total_documented": 389,
+    "overall_coverage_percent": 122.7
   }
 }

docs/stdlib/secrets.md

@@ -126,6 +126,7 @@ def generate_secure_password(length=12):
 
 ```python
 import secrets
+from datetime import datetime, timedelta
 
 # Generate tokens for authentication - O(n)
 def create_session_token():
@@ -151,11 +152,12 @@ session = {
 import secrets
 
 def lottery_selection(participants, winners=5):
-    # O(1) per selection
+    # O(1) per selection (swap with last element, then pop)
     selected = []
     for _ in range(min(winners, len(participants))):
         idx = secrets.randbelow(len(participants))
-        selected.append(participants.pop(idx))
+        participants[idx], participants[-1] = participants[-1], participants[idx]
+        selected.append(participants.pop())
     return selected
 
 participants = list(range(100))

docs/stdlib/select.md

@@ -0,0 +1,134 @@
+# select Module
+
+The `select` module provides low-level I/O multiplexing primitives that wait for file
+descriptors to become ready for reading or writing.
+
+## Complexity Reference
+
+| Operation | Time | Space | Notes |
+|-----------|------|-------|-------|
+| `select.select()` | O(n) | O(n) | n = total fds passed; scans all sets |
+| `poll.register()` / `poll.unregister()` / `poll.modify()` | O(1) avg | O(1) | Per fd; Python bookkeeping + OS registration |
+| `poll.poll()` | O(n) | O(k) | n = registered fds, k = ready fds |
+| `epoll.register()` / `epoll.unregister()` / `epoll.modify()` | O(1) avg | O(1) | Per fd; OS-dependent |
+| `epoll.poll()` | O(k) typical | O(k) | k = ready fds; OS-dependent |
+| `kqueue.control()` | O(m + k) | O(k) | m = changelist length; k = ready events |
+
+!!! warning "Platform availability"
+    `poll`, `epoll`, and `kqueue` are not available on all platforms.
+    Always guard with `hasattr(select, "poll")`, `hasattr(select, "epoll")`,
+    or `hasattr(select, "kqueue")`.
+
+## Waiting with select()
+
+```python
+import select
+import socket
+
+# Create a connected socket pair (cross-platform in Python 3.5+)
+left, right = socket.socketpair()
+
+# Send data so right becomes readable
+left.sendall(b"ping")
+
+# Wait for readability - O(n) where n = len(rlist) + len(wlist) + len(xlist)
+rlist, wlist, xlist = select.select([right], [], [], 1.0)
+if rlist:
+    data = right.recv(4096)
+    print(data)  # b'ping'
+
+left.close()
+right.close()
+```
+
+## Polling with poll()
+
+```python
+import select
+import socket
+
+if hasattr(select, "poll"):
+    left, right = socket.socketpair()
+    poller = select.poll()
+
+    # Register for read events - O(1) average
+    poller.register(right, select.POLLIN)
+
+    left.sendall(b"hello")
+
+    # Wait for events - O(n) for n registered fds
+    events = poller.poll(1000)  # timeout in ms
+    for fd, event in events:  # O(k) for k ready
+        if event & select.POLLIN:
+            print(right.recv(4096))  # b'hello'
+
+    poller.unregister(right)  # O(1) average
+    left.close()
+    right.close()
+```
+
+## Using epoll (Linux)
+
+```python
+import select
+import socket
+
+if hasattr(select, "epoll"):
+    left, right = socket.socketpair()
+    ep = select.epoll()
+
+    # Register read interest - O(1) average
+    ep.register(right, select.EPOLLIN)
+
+    left.sendall(b"event")
+
+    # Wait for ready fds - typically O(k)
+    events = ep.poll(1.0)
+    for fd, event in events:
+        if event & select.EPOLLIN:
+            print(right.recv(4096))  # b'event'
+
+    ep.unregister(right)  # O(1) average
+    ep.close()
+    left.close()
+    right.close()
+```
+
+## Using kqueue (BSD/macOS)
+
+```python
+import select
+import socket
+
+if hasattr(select, "kqueue"):
+    left, right = socket.socketpair()
+    kq = select.kqueue()
+
+    # Register a read event - O(1) average
+    kev = select.kevent(right, filter=select.KQ_FILTER_READ, flags=select.KQ_EV_ADD)
+    kq.control([kev], 0, 0)
+
+    left.sendall(b"kq")
+
+    # Wait for events - O(m + k) where m = changelist length
+    events = kq.control([], 1, 1.0)
+    if events:
+        print(right.recv(4096))  # b'kq'
+
+    kq.close()
+    left.close()
+    right.close()
+```
+
+## Notes and Best Practices
+
+!!! warning "select() scalability limits"
+    `select.select()` must scan all fds each call and may be limited by the
+    platform's FD set size. For large numbers of connections, prefer `selectors`
+    or an `epoll`/`kqueue`-based approach.
+
+## Related Modules
+
+- [selectors Module](selectors.md)
+- [socket Module](socket.md)
+- [asyncio Module](asyncio.md)

docs/stdlib/selectors.md

@@ -254,10 +254,10 @@ def connect_many(hosts_ports):
         sel.register(sock, selectors.EVENT_WRITE, data=(host, port))
         sockets.append(sock)
 
-    # Wait for connections: O(n log n)
-    # n = number of sockets
+    # Wait for connections: O(n) for select, O(k) for epoll/kqueue
+    # n = registered sockets, k = ready sockets
     while True:
-        events = sel.select()  # O(n log n)
+        events = sel.select()  # O(n) for select, O(k) for epoll/kqueue
 
         if not events:
             break
@@ -298,9 +298,9 @@ def main():
     with open('file.txt') as f:
         sel.register(f, selectors.EVENT_READ)  # O(1)
 
-    # Event loop: O(n log n) where n = files
+    # Event loop: O(n) for select, O(k) for epoll/kqueue
     while True:
-        events = sel.select()  # O(n log n)
+        events = sel.select()  # O(n) for select, O(k) for epoll/kqueue
 
         for key, mask in events:  # O(k) ready
             if key.fileobj == sys.stdin: