Files

Jan Novak 16fff2f964 docs: add usage-phases.md beside usage-simple.md in python/configs/

- Rename python/configs/usage.md → usage-simple.md so both scripts have a
  parallel runnable reference file in the same directory
- Add python/configs/usage-phases.md: runnable sh commands + real expected
  output for phases.py against every error-path config, including a note on
  the key difference from simple.py (HTTP 4xx exits 0 in phases.py vs 1 in
  simple.py because phases.py completes at the network level)
- Update doc cross-links in docs/usage/py-simple.md and py-phases.md

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-07-01 12:11:53 +02:00

2.3 KiB

Raw Blame History

`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:

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-simple.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.

2.3 KiB Raw Blame History

simple.py — Site Reachability Checker