Tag 7: Nebenläufigkeit – urlcheck
Ziel: Ein CLI
urlcheckbauen, das hunderte URLs parallel mit asyncio prüft · Dauer: ca. 120 min · Voraussetzung: Tag 6
Briefing
- Warten auf Netz ist I/O-bound: asyncio erledigt tausende Wartezeiten in einem Thread.
asyncio.TaskGroupstartet Tasks und räumt bei Fehlern sauber auf;Semaphorebegrenzt die Parallelität.- Ein gemeinsamer
httpx.AsyncClientteilt Verbindungen – nicht einen pro URL erzeugen. - CPU-bound braucht Prozesse; Threads helfen dort erst mit free-threaded Python (3.14t).
- Getestet wird gegen einen lokalen Lab-Server und
MockTransport– nie gegen fremde Server.
urls.txt --> TaskGroup --> [Semaphore: max c] --> AsyncClient --> Lab-Server :8765
| /ok /slow
list[Result] <-- Status, Sekunden, Fehler <-- /status/503 /redirect
Drill 1: Projekt und Lab-Server
cd ~/py-lab
uv init -q --package --name urlcheck tag07-urlcheck
cd tag07-urlcheck && mkdir tests
uv add -q httpx typer
uv add -q --dev pytest ruff
cat > labserver.py <<'EOF'
"""Lab-Server für urlcheck: /ok, /slow, /status/<code>, /redirect."""
import time
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
class Handler(BaseHTTPRequestHandler):
def do_GET(self) -> None:
if self.path.startswith("/slow"):
time.sleep(0.5)
if self.path.startswith("/redirect"):
self.send_response(301)
self.send_header("Location", "/ok")
self.end_headers()
return
code = 200
if self.path.startswith("/status/"):
code = int(self.path.rsplit("/", 1)[1])
self.send_response(code)
self.send_header("Content-Type", "text/plain")
self.end_headers()
self.wfile.write(b"lab\n")
def log_message(self, *args) -> None: # kein Log pro Request
pass
class Server(ThreadingHTTPServer):
request_queue_size = 256 # Standard 5 ist zu klein für viele Verbindungen
if __name__ == "__main__":
print("Lab-Server auf http://127.0.0.1:8765")
Server(("127.0.0.1", 8765), Handler).serve_forever()
EOFIn einem zweiten Terminal starten und dort laufen lassen:
cd ~/py-lab/tag07-urlcheck && uv run python labserver.pyErwartet:
Lab-Server auf http://127.0.0.1:8765
Zurück im ersten Terminal: URL-Liste erzeugen und den Server testen.
python3 - > urls.txt <<'EOF'
base = "http://127.0.0.1:8765"
print("# Lab-URLs für urlcheck")
for i in range(200):
path = ["ok", "slow", "slow", "redirect", "ok"][i % 5]
print(f"{base}/{path}?n={i}")
print(f"{base}/status/404")
print(f"{base}/status/503")
print("http://127.0.0.1:9/ok")
print("http://10.255.255.1/timeout")
EOF
wc -l urls.txt
for p in ok slow status/503 redirect; do
curl -s -o /dev/null -w "%{http_code} %{time_total}s /$p\n" "http://127.0.0.1:8765/$p"
doneErwartet:
205 urls.txt
200 0.000985s /ok
200 0.510480s /slow
503 0.000498s /status/503
301 0.000359s /redirect
Warum? Port 9 (discard) ist lokal geschlossen und liefert sofort
„Connection refused”, 10.255.255.1 läuft in den Timeout –
beide Fehlerarten sind damit im Lab.
Fortschritt speichern? Kostenlos registrieren
Drill 2: Die Messlatte – sequenziell
uv run python - <<'EOF'
import time
import httpx
urls = [line.strip() for line in open("urls.txt") if line.startswith("http")][:20]
start = time.perf_counter()
with httpx.Client(follow_redirects=True, timeout=5) as client:
codes = [client.get(u).status_code for u in urls]
elapsed = time.perf_counter() - start
print(len(codes), "URLs sequenziell:", f"{elapsed:.2f}s", set(codes))
EOFErwartet:
20 URLs sequenziell: 4.13s {200}
Warum? 8 von 20 URLs sind /slow (0,5 s): 8 × 0,5 s ≈ 4
s, fast nur Warten. Für alle 200 wären es über 40 s.
Fortschritt speichern? Kostenlos registrieren
Drill 3: asyncio in fünf Minuten
async def definiert eine Coroutine, await
gibt die Kontrolle an die Event-Loop ab, asyncio.run()
startet alles.
uv run python - <<'EOF'
import asyncio
import time
async def job(name: str, sec: float) -> str:
await asyncio.sleep(sec) # wartet, ohne den Thread zu blockieren
return f"{name} nach {sec}s"
async def main() -> None:
start = time.perf_counter()
async with asyncio.TaskGroup() as tg:
tasks = [tg.create_task(job(n, s)) for n, s in [("a", 1), ("b", 1), ("c", 0.5)]]
print([t.result() for t in tasks], f"{time.perf_counter() - start:.2f}s")
asyncio.run(main())
EOFErwartet:
['a nach 1s', 'b nach 1s', 'c nach 0.5s'] 1.00s
Drei Jobs, 2,5 s Wartezeit, 1 s Laufzeit. Und wenn ein Task scheitert?
uv run python - <<'EOF'
import asyncio
async def ok() -> None:
try:
await asyncio.sleep(2)
print("ok fertig")
except asyncio.CancelledError:
print("ok wurde abgebrochen")
raise
async def kaputt() -> None:
await asyncio.sleep(0.1)
raise ValueError("kaputt")
async def main() -> None:
try:
async with asyncio.TaskGroup() as tg:
tg.create_task(ok())
tg.create_task(kaputt())
except* ValueError as eg:
print("gefangen:", eg.exceptions)
asyncio.run(main())
EOFErwartet:
ok wurde abgebrochen
gefangen: (ValueError('kaputt'),)
Warum? Die TaskGroup bricht bei einem Fehler alle
Geschwister ab und wirft eine ExceptionGroup, die du mit
except* zerlegst. Deshalb fängt unser Prüfkern Netzfehler
pro URL selbst ab – eine tote URL darf nicht die anderen 199
abbrechen.
Achtung:
CancelledErrorimmer weiterwerfen (raise). Wer sie schluckt, bricht das Aufräumen der Gruppe.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Der Prüfkern
cat > src/urlcheck/__init__.py <<'EOF'
"""urlcheck – viele URLs parallel prüfen."""
EOF
cat > src/urlcheck/checker.py <<'EOF'
"""Asynchroner Prüfkern: TaskGroup + Semaphore + ein gemeinsamer AsyncClient."""
import asyncio
import time
from collections.abc import Iterable
from dataclasses import dataclass
import httpx
@dataclass(frozen=True, slots=True)
class Result:
url: str
status: int | None
seconds: float
error: str | None = None
@property
def ok(self) -> bool:
return self.status is not None and self.status < 400
async def check_one(
client: httpx.AsyncClient, sem: asyncio.Semaphore, url: str
) -> Result:
async with sem: # höchstens N gleichzeitig
start = time.perf_counter()
try:
async with client.stream("GET", url) as resp: # Body nicht laden
status, error = resp.status_code, None
except httpx.HTTPError as exc: # Timeout, DNS, Connect, ...
status, error = None, type(exc).__name__
return Result(url, status, round(time.perf_counter() - start, 3), error)
async def check_all(
urls: Iterable[str],
concurrency: int = 20,
timeout: float = 5.0,
transport: httpx.AsyncBaseTransport | None = None,
) -> list[Result]:
sem = asyncio.Semaphore(concurrency)
client = httpx.AsyncClient(
timeout=httpx.Timeout(timeout, connect=min(timeout, 2.0)),
follow_redirects=True,
limits=httpx.Limits(max_connections=concurrency),
transport=transport,
)
async with client, asyncio.TaskGroup() as tg:
tasks = [tg.create_task(check_one(client, sem, u)) for u in urls]
return [t.result() for t in tasks]
EOF
uv run python - <<'EOF'
import asyncio
import time
from urlcheck.checker import check_all
urls = [line.strip() for line in open("urls.txt") if "8765" in line][:200]
for c in (10, 50, 200):
start = time.perf_counter()
results = asyncio.run(check_all(urls, concurrency=c))
bad = sum(not r.ok for r in results)
secs = time.perf_counter() - start
print(f"c={c:<3} {len(results)} URLs {secs:5.2f}s, {bad} kaputt")
EOFErwartet:
c=10 200 URLs 4.16s, 0 kaputt
c=50 200 URLs 1.08s, 0 kaputt
c=200 200 URLs 0.60s, 0 kaputt
Warum? client.stream() liest nur Statuszeile und Header,
nicht den Body – bei großen Seiten spart das Bandbreite.
Semaphore und Limits(max_connections=...) sind
doppelte Absicherung: Die Semaphore begrenzt Tasks, das Limit die
TCP-Verbindungen im Pool. Die Reihenfolge der Ergebnisse bleibt die der
Eingabe, weil wir die Task-Liste auswerten.
Tipp: Statt
TaskGroupgeht auchasyncio.gather(*coros). DieTaskGroup(seit 3.11) ist die strukturierte Variante: Kein Task überlebt denasync with-Block.
Fortschritt speichern? Kostenlos registrieren
Drill 5: Das CLI
Das CLI bleibt synchron; asyncio.run() ist die eine
Brücke in die async-Welt.
cat > src/urlcheck/cli.py <<'EOF'
"""CLI: urlcheck urls.txt [-c 50] [-t 5] [--all] [--json]"""
import asyncio
import json
import sys
import time
from dataclasses import asdict
from pathlib import Path
from typing import Annotated
import typer
from urlcheck.checker import check_all
app = typer.Typer(add_completion=False)
def read_urls(text: str) -> list[str]:
"""Eine URL pro Zeile; Leerzeilen und #-Kommentare überspringen."""
urls = [line.strip() for line in text.splitlines()]
return [u for u in urls if u and not u.startswith("#")]
@app.command()
def main(
source: Annotated[str, typer.Argument(help="Datei mit URLs oder - für stdin")],
concurrency: Annotated[int, typer.Option("-c", min=1, max=500)] = 50,
timeout: Annotated[float, typer.Option("-t", help="Sekunden pro URL")] = 5.0,
show_all: Annotated[bool, typer.Option("--all", help="auch OKs zeigen")] = False,
as_json: Annotated[bool, typer.Option("--json")] = False,
) -> None:
"""Prüft viele URLs parallel und meldet die kaputten."""
text = sys.stdin.read() if source == "-" else Path(source).read_text()
urls = read_urls(text)
start = time.perf_counter()
results = asyncio.run(check_all(urls, concurrency, timeout))
elapsed = time.perf_counter() - start
bad = [r for r in results if not r.ok]
shown = results if show_all else bad
if as_json:
typer.echo(json.dumps([asdict(r) for r in shown], indent=2))
else:
for r in shown:
mark = "✔" if r.ok else "✘"
typer.echo(f"{mark} {r.status or r.error:<14} {r.seconds:5.2f}s {r.url}")
typer.echo(f"{len(urls)} URLs, {len(bad)} kaputt, {elapsed:.2f}s")
raise typer.Exit(code=1 if bad else 0)
EOF
cat > src/urlcheck/__init__.py <<'EOF'
"""urlcheck – viele URLs parallel prüfen."""
from urlcheck.cli import app
def main() -> None:
app()
EOF
cat > src/urlcheck/__main__.py <<'EOF'
from urlcheck import main
main()
EOF
cat >> pyproject.toml <<'EOF'
[tool.ruff.lint]
extend-select = ["E501", "B", "UP", "SIM"]
[tool.pytest.ini_options]
testpaths = ["tests"]
EOF
grep -m3 slow urls.txt | uv run urlcheck --all -c 1 -Erwartet:
✔ 200 0.51s http://127.0.0.1:8765/slow?n=1
✔ 200 0.50s http://127.0.0.1:8765/slow?n=2
✔ 200 0.51s http://127.0.0.1:8765/slow?n=6
3 URLs, 0 kaputt, 1.54s
Warum? Mit -c 1 siehst du den sequenziellen Fall: 3 ×
0,5 s. - liest von stdin – so passt urlcheck
in jede Pipe.
Fortschritt speichern? Kostenlos registrieren
Drill 6: Tests ohne Netz
MockTransport funktioniert auch mit
AsyncClient und akzeptiert sogar einen async Handler. Die
Tests rufen asyncio.run() selbst auf – kein Plugin
nötig.
cat > tests/test_checker.py <<'EOF'
import asyncio
import httpx
from urlcheck.checker import check_all
def run(urls, handler, concurrency=5):
transport = httpx.MockTransport(handler)
return asyncio.run(check_all(urls, concurrency, transport=transport))
def test_status_and_errors():
def handler(req: httpx.Request) -> httpx.Response:
if req.url.host == "down.invalid":
raise httpx.ConnectError("refused", request=req)
return httpx.Response(int(req.url.path.strip("/")))
urls = ["http://lab.invalid/200", "http://lab.invalid/503", "http://down.invalid/"]
ok, bad, down = run(urls, handler)
assert (ok.ok, ok.status) == (True, 200)
assert (bad.ok, bad.status) == (False, 503)
assert (down.ok, down.error) == (False, "ConnectError")
def test_order_is_kept():
urls = [f"http://lab.invalid/{i}" for i in range(30)]
results = run(urls, lambda req: httpx.Response(200))
assert [r.url for r in results] == urls
def test_semaphore_limits_concurrency():
active = peak = 0
async def handler(req: httpx.Request) -> httpx.Response:
nonlocal active, peak
active += 1
peak = max(peak, active)
await asyncio.sleep(0.01)
active -= 1
return httpx.Response(200)
run([f"http://lab.invalid/{i}" for i in range(40)], handler, concurrency=7)
assert peak == 7
EOF
cat > tests/test_cli.py <<'EOF'
from typer.testing import CliRunner
from urlcheck import cli
from urlcheck.checker import Result
def test_read_urls_skips_comments():
text = "# Kommentar\n\nhttp://a.invalid\n http://b.invalid \n"
assert cli.read_urls(text) == ["http://a.invalid", "http://b.invalid"]
def test_cli_exit_code_and_output(monkeypatch):
async def fake_check_all(urls, concurrency, timeout):
return [Result(urls[0], 200, 0.1), Result(urls[1], None, 2.0, "ReadTimeout")]
monkeypatch.setattr(cli, "check_all", fake_check_all)
result = CliRunner().invoke(cli.app, ["-"], input="http://a\nhttp://b\n")
assert result.exit_code == 1
assert "ReadTimeout" in result.stdout
assert "http://a" not in result.stdout # OKs nur mit --all
EOF
uv run pytest -q && uv run ruff check . && uv run ruff format --check .Erwartet:
..... [100%]
5 passed in 0.10s
All checks passed!
8 files already formatted
Warum? test_semaphore_limits_concurrency misst die echte
Spitzenlast im Handler – so beweist der Test, dass die Semaphore wirkt,
statt es nur zu behaupten.
Tipp: Für viele async Tests lohnt
pytest-asynciooder das anyio-Plugin (@pytest.mark.anyio, kommt mit httpx). Für fünf Tests reichtasyncio.run().
Fortschritt speichern? Kostenlos registrieren
Drill 7: Threads, Prozesse, free-threaded
asyncio hilft nur beim Warten. Was passiert bei echter Rechenlast?
cat > cpu.py <<'EOF'
"""CPU-Last: sequenziell vs. Threads vs. Prozesse."""
import sys
import time
from concurrent.futures import ProcessPoolExecutor, ThreadPoolExecutor
def burn(n: int) -> int:
return sum(i * i for i in range(n))
def timed(label: str, fn) -> None:
start = time.perf_counter()
fn()
print(f"{label:<10} {time.perf_counter() - start:5.2f}s")
if __name__ == "__main__":
jobs = [3_000_000] * 8
print(sys.version.split()[0], "GIL aktiv:", sys._is_gil_enabled())
timed("seriell", lambda: [burn(n) for n in jobs])
with ThreadPoolExecutor(max_workers=8) as pool:
timed("Threads", lambda: list(pool.map(burn, jobs)))
with ProcessPoolExecutor(max_workers=8) as pool:
timed("Prozesse", lambda: list(pool.map(burn, jobs)))
EOF
uv run python cpu.pyErwartet (10 Kerne, Werte schwanken):
3.14.8 GIL aktiv: True
seriell 0.69s
Threads 0.66s
Prozesse 0.24s
Warum? Der GIL lässt immer nur einen Thread Python-Bytecode ausführen
– Threads bringen bei CPU-Last nichts. Prozesse haben je einen eigenen
Interpreter, kosten aber Startzeit und Pickling der Argumente. Der
if __name__ == "__main__"-Schutz ist Pflicht, weil macOS
neue Prozesse per spawn startet und das Modul dabei neu
importiert.
Jetzt dasselbe mit dem free-threaded Build (PEP 703, ab 3.14 offiziell unterstützt). uv lädt ihn bei Bedarf in seinen Python-Cache:
uv run --no-project -p 3.14t python cpu.pyErwartet (gekürzt, kann je nach Version abweichen):
3.14.2 GIL aktiv: False
seriell 0.57s
Threads 0.19s
Prozesse 0.25s
Ohne GIL skalieren Threads auf alle Kerne. Danach aufräumen, damit uv
nicht versehentlich den 3.14t-Build für neue Projekte wählt:
uv python uninstall 3.14t.
Faustregel:
| Last | Werkzeug | Beispiel |
|---|---|---|
| viel Warten (Netz, Disk) | asyncio | urlcheck, API-Clients |
| Warten, aber nur sync-Bibliothek | ThreadPoolExecutor |
boto3, alte SDKs |
| CPU-Last | ProcessPoolExecutor |
Parsing, Hashing |
| CPU-Last, 3.14t | Threads | nur wenn alle C-Extensions mitspielen |
Achtung: Viele C-Extensions sind noch nicht free-threaded-fähig und schalten den GIL beim Import wieder ein. Für Produktion bleibt der Standard-Build die sichere Wahl.
Fortschritt speichern? Kostenlos registrieren
Drill 8: Das Tool ist fertig
uv run urlcheck urls.txt
echo "exit=$?"
uv run urlcheck --json urls.txt | jq -r '.[] | "\(.status) \(.error) \(.url)"'Erwartet:
✘ 404 0.01s http://127.0.0.1:8765/status/404
✘ 503 0.01s http://127.0.0.1:8765/status/503
✘ ConnectError 0.00s http://127.0.0.1:9/ok
✘ ConnectTimeout 2.00s http://10.255.255.1/timeout
204 URLs, 4 kaputt, 2.62s
exit=1
404 null http://127.0.0.1:8765/status/404
503 null http://127.0.0.1:8765/status/503
null ConnectError http://127.0.0.1:9/ok
null ConnectTimeout http://10.255.255.1/timeout
204 URLs in 2,6 s – und davon sind 2 s der eine Connect-Timeout. Sequenziell wären es über 40 s.
Sicherheit: Hunderte parallele Requests gegen fremde Server sind ein kleiner DoS. Gegen Systeme, die dir nicht gehören, nur mit niedrigem
-cund nach Absprache.
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
#!/usr/bin/env bash
check() { if eval "$2" >/dev/null 2>&1; then echo "✔ $1"; else echo "✘ $1"; fi; }
cd ~/py-lab/tag07-urlcheck
check "Tests grün" "uv run pytest -q"
check "ruff sauber" "uv run ruff check . && uv run ruff format --check ."
check "Lab-Server läuft" "curl -sf http://127.0.0.1:8765/ok"
check "genau 4 kaputte URLs" \
"uv run urlcheck --json urls.txt | jq -e 'length == 4'"
check "Exit 1 bei Fehlern" "! uv run urlcheck urls.txt"
check "OK-URLs unter 5 s" \
"grep 8765/ok urls.txt | uv run urlcheck -c 100 - | grep -E ', [0-4]\\.[0-9]+s$'"Erwartet:
✔ Tests grün
✔ ruff sauber
✔ Lab-Server läuft
✔ genau 4 kaputte URLs
✔ Exit 1 bei Fehlern
✔ OK-URLs unter 5 s
Aufräumen: Lab-Server im zweiten Terminal mit Ctrl-C beenden.
Challenge
Bei vielen URLs auf demselben Host ist -c 200 unhöflich.
Ergänze ein Limit pro Host (Standard 10), zusätzlich zum globalen
Limit.
Hinweis: Ein
defaultdict(lambda: asyncio.Semaphore(per_host)), Schlüssel
ist urlsplit(url).netloc; async with nimmt
mehrere Kontextmanager.
Lösung
In src/urlcheck/checker.py Importe ergänzen und beide
Funktionen anpassen:
from collections import defaultdict
from urllib.parse import urlsplit
...
async def check_one(
client: httpx.AsyncClient,
sem: asyncio.Semaphore,
url: str,
hosts: defaultdict[str, asyncio.Semaphore],
) -> Result:
async with sem, hosts[urlsplit(url).netloc]: # global UND pro Host
start = time.perf_counter()
try:
async with client.stream("GET", url) as resp: # Body nicht laden
status, error = resp.status_code, None
except httpx.HTTPError as exc: # Timeout, DNS, Connect, ...
status, error = None, type(exc).__name__
return Result(url, status, round(time.perf_counter() - start, 3), error)
async def check_all(
urls: Iterable[str],
concurrency: int = 20,
timeout: float = 5.0,
transport: httpx.AsyncBaseTransport | None = None,
per_host: int = 10,
) -> list[Result]:
sem = asyncio.Semaphore(concurrency)
hosts = defaultdict(lambda: asyncio.Semaphore(per_host))
client = httpx.AsyncClient(
timeout=httpx.Timeout(timeout, connect=min(timeout, 2.0)),
follow_redirects=True,
limits=httpx.Limits(max_connections=concurrency),
transport=transport,
)
async with client, asyncio.TaskGroup() as tg:
tasks = [tg.create_task(check_one(client, sem, u, hosts)) for u in urls]
return [t.result() for t in tasks]Test in tests/test_checker.py anhängen:
def test_per_host_limit():
active: dict[str, int] = {}
peak: dict[str, int] = {}
async def handler(req: httpx.Request) -> httpx.Response:
host = req.url.host
active[host] = active.get(host, 0) + 1
peak[host] = max(peak.get(host, 0), active[host])
await asyncio.sleep(0.01)
active[host] -= 1
return httpx.Response(200)
urls = [f"http://h{i % 2}.invalid/{i}" for i in range(40)]
transport = httpx.MockTransport(handler)
asyncio.run(check_all(urls, 20, transport=transport, per_host=3))
assert peak == {"h0.invalid": 3, "h1.invalid": 3}uv run ruff check --fix . && uv run pytest -qErwartet:
All checks passed!
...... [100%]
6 passed in 0.30s
Im CLI noch --per-host als Option ergänzen und an
check_all durchreichen. Gegen den Lab-Server (ein Host)
dauern 200 URLs dann wieder rund 4 s – genau das ist der Sinn.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Monitoring-Checks gehören in Blackbox-Exporter/Prometheus;
urlcheckist das Werkzeug für Migrationen, Linkchecks und Ad-hoc-Diagnose. - Firmen-Proxy:
httpx.AsyncClientliestHTTPS_PROXY/NO_PROXY; interne CAs perverify=ssl.create_default_context(cafile=...). - Interne Ziele (Kubernetes-Services, Vault-Cluster) haben Rate-Limits
und WAFs – Parallelität pro Host begrenzen und
User-Agentsetzen, damit Betreiber dich erkennen. - Für sehr große Listen (100 000+) Ergebnisse streamen
(
asyncio.as_completed) statt alles im Speicher zu sammeln. - Free-threaded Python erst einsetzen, wenn alle Abhängigkeiten Wheels
für
cp314tliefern; im CI beide Builds testen.