Jan Novak
49838e9e4c
- 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>
80 lines
2.3 KiB
Markdown
80 lines
2.3 KiB
Markdown
# `simple.py` — Site Reachability Checker
|
|
|
|
## What it does
|
|
|
|
Reads a plain-text list of URLs, issues an HTTP GET to each one, and reports
|
|
whether the site responded and how long it took (full wall-clock time including
|
|
body download). This is the simplest possible latency check — one line of
|
|
output per site, nothing more.
|
|
|
|
## Flags / arguments
|
|
|
|
```
|
|
python simple.py [sites.txt]
|
|
```
|
|
|
|
| Argument | Default | Meaning |
|
|
|----------|---------|---------|
|
|
| `sites.txt` | `sites.txt` in the current directory | Path to the plain-text config file |
|
|
|
|
**Config file format:**
|
|
- One URL per line.
|
|
- Lines starting with `#` are comments and are ignored.
|
|
- Blank lines are ignored.
|
|
- Future `key=value` tokens after the URL (e.g. `https://x.com budget=200ms`)
|
|
are silently ignored, so the file format is forward-compatible.
|
|
|
|
**Exit codes:**
|
|
|
|
| Code | Meaning |
|
|
|------|---------|
|
|
| 0 | All sites responded |
|
|
| 1 | One or more sites failed, or a usage/config error |
|
|
|
|
## Example
|
|
|
|
**Config (`sites.txt`):**
|
|
```
|
|
https://example.com
|
|
https://www.google.com
|
|
# https://httpbin.org/get # uncomment to include
|
|
```
|
|
|
|
**Run:**
|
|
```sh
|
|
python simple.py sites.txt
|
|
```
|
|
|
|
**Expected output (latencies vary):**
|
|
```
|
|
OK 147.11 ms https://example.com
|
|
OK 83.42 ms https://www.google.com
|
|
```
|
|
|
|
**With an unreachable host:**
|
|
```
|
|
OK 147.11 ms https://example.com
|
|
FAIL (nodename nor servname provided, or not known) https://nonexistent.invalid
|
|
```
|
|
Exit code: `1`
|
|
|
|
## Example config files
|
|
|
|
`python/configs/` contains purpose-built config files targeting every distinct
|
|
failure class (DNS, connection-refused, timeout, TLS-cert errors, HTTP 4xx/5xx,
|
|
and a mixed scenario). Each file includes a comment explaining what it exercises.
|
|
|
|
See [`python/configs/usage.md`](../../python/configs/usage.md) for the runnable
|
|
shell commands and expected output for each file.
|
|
|
|
## Limitations
|
|
|
|
- Measures total wall-clock time (DNS + TCP + TLS + server + transfer) as a
|
|
single number. Use `phases.py` for a per-phase breakdown.
|
|
- Always uses GET; no auth, no custom headers, no redirect control.
|
|
- Timeout is hard-coded at 10 s. Use `phases.py` or `latprobe/` for a `--timeout`
|
|
flag.
|
|
- HTTP error statuses (4xx, 5xx) are reported as `FAIL` — `urllib.request.urlopen`
|
|
raises `HTTPError` for non-2xx responses, so a 404 is treated as a failure,
|
|
not a success.
|