feat(py): step 1 — simple reachability checker (simple.py)
- python/simple.py: reads a plain-text site list (one URL/line, # comments), issues a GET per site, prints aligned OK/FAIL + elapsed ms, exits 0/1 - Config format forward-compatible with future key=value annotations - HTTPError caught separately from URLError so HTTP status code appears in the FAIL message (e.g. "HTTP Error 404: Not Found") - python/sites.txt: committed example config - Makefile: PYTHON/PY_DIR/SITES vars; py-simple-run, py-phases-run, py-run, py-test, py-check, py-clean targets; umbrella test/check/clean include Python - docs/plans/2026-07-01-10-39-py-simple.md: design plan - docs/usage/py-simple.md: flags, format, examples, limitations Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
47
docs/plans/2026-07-01-10-39-py-simple.md
Normal file
47
docs/plans/2026-07-01-10-39-py-simple.md
Normal file
@@ -0,0 +1,47 @@
|
||||
# Python Port — Step 1: `simple.py`
|
||||
|
||||
## Goal
|
||||
|
||||
The simplest possible latency-checking script: read a plain-text list of sites,
|
||||
issue a GET to each, report whether it was reachable and how long it took.
|
||||
No phase breakdown, no flags beyond the config-file path. ~50 lines.
|
||||
|
||||
## Input
|
||||
|
||||
`python simple.py [sites.txt]`
|
||||
|
||||
- Positional argument: path to the plain-text config (default: `sites.txt` in cwd).
|
||||
- Config format: one URL per line; `#` introduces a comment; blank lines ignored.
|
||||
Forward-compatible with trailing `key=value` tokens that future steps may add
|
||||
(the parser strips everything after the first whitespace token when reading the URL).
|
||||
|
||||
## Output
|
||||
|
||||
One line per site, aligned in three columns:
|
||||
|
||||
```
|
||||
OK 147.11 ms https://example.com
|
||||
FAIL (connection refused) http://localhost:8080
|
||||
FAIL (name or service not known) https://nonexistent.invalid
|
||||
```
|
||||
|
||||
- `OK` / `FAIL` tag (7 chars padded), ms formatted as `%.2f ms`, then URL.
|
||||
- All output goes to `stdout`.
|
||||
- Exit `0` if every site returned a response (any HTTP status); `1` if any failed.
|
||||
|
||||
## Implementation
|
||||
|
||||
- `urllib.request.urlopen(url, timeout=10)` wrapped in a try/except.
|
||||
- Timing: `time.perf_counter()` bracketed around `urlopen` + `resp.read()` (drain
|
||||
body so the number is real wall-clock including transfer).
|
||||
- Catch `urllib.error.URLError` and `Exception` for any network failure; extract
|
||||
the reason string for the FAIL message.
|
||||
- Stdlib only: `urllib.request`, `urllib.error`, `time`, `sys`.
|
||||
|
||||
## Files
|
||||
|
||||
- `python/simple.py` — the script
|
||||
- `python/sites.txt` — example config (committed as a sample)
|
||||
- `docs/usage/py-simple.md` — user-facing doc
|
||||
- Makefile `py-simple-run` and `py-test` (empty stub) targets, wired into umbrella `test`
|
||||
- CHANGELOG.md entry
|
||||
Reference in New Issue
Block a user