Tag 6: HTTP und APIs – ghrel
Ziel: Ein CLI
ghrelbauen, das robust die neuesten GitHub-Releases abfragt · Dauer: ca. 120 min · Voraussetzung: Tag 5
Briefing
httpxist der moderne HTTP-Client: sync und async mit derselben API, Timeouts Pflicht.- Antworten landen nie als nacktes
dictim Code, sondern als validiertespydantic-Modell. - Retries nur bei 429/5xx und Netzfehlern, mit exponentiellem Backoff,
Jitter und
Retry-After. - Tests laufen ohne Netz über
httpx.MockTransport. - Token kommt aus
GITHUB_TOKEN, nie aus Argumenten.
ghrel owner/repo ... --> retry.get() --> httpx.Client --> api.github.com
| |
Backoff/Jitter JSON --> Release (pydantic)
Drill 1: Projekt und erster Request
mkdir -p ~/py-lab && cd ~/py-lab
uv init -q --package --name ghrel tag06-ghrel
cd tag06-ghrel && mkdir tests
uv add -q httpx pydantic typer
uv add -q --dev pytest ruff
uv run python - <<'EOF'
import httpx
r = httpx.get(
"https://api.github.com/repos/astral-sh/uv/releases/latest",
headers={"Accept": "application/vnd.github+json"},
timeout=10,
)
print(r.status_code, r.headers["x-ratelimit-remaining"], r.json()["tag_name"])
open("release.json", "wb").write(r.content)
EOFErwartet (Version und Zähler ändern sich):
200 55 0.13.0
Warum? Ohne Token erlaubt GitHub 60 Anfragen pro Stunde und IP; der
Header zeigt den Rest. release.json (rund 100 KB) dient
gleich als Anschauungsmaterial.
uv run python -c 'import json; print(sorted(json.load(open("release.json"))))'Erwartet (gekürzt):
['assets', 'assets_url', 'author', 'body', 'created_at', 'draft', 'html_url', ...
Fortschritt speichern? Kostenlos registrieren
Drill 2: Antwort als pydantic-Modell
Wir modellieren nur die Felder, die wir brauchen. Alles andere ignoriert pydantic standardmäßig.
cat > src/ghrel/__init__.py <<'EOF'
"""ghrel – neueste GitHub-Releases im Terminal."""
EOF
cat > src/ghrel/models.py <<'EOF'
"""Pydantic-Modelle: nur die Felder, die wir wirklich brauchen."""
from datetime import UTC, datetime
from pydantic import BaseModel, HttpUrl
class Release(BaseModel):
tag_name: str
name: str | None = None
published_at: datetime
html_url: HttpUrl
prerelease: bool = False
def age_days(self, now: datetime | None = None) -> int:
now = now or datetime.now(UTC)
return (now - self.published_at).days
EOF
uv run python - <<'EOF'
import json
from pydantic import ValidationError
from ghrel.models import Release
rel = Release.model_validate(json.load(open("release.json")))
print(repr(rel.tag_name), rel.published_at, type(rel.published_at).__name__)
print(rel.model_dump_json())
try:
Release.model_validate({"tag_name": "v1", "published_at": "gestern"})
except ValidationError as exc:
print(exc)
EOFErwartet (gekürzt):
'0.13.0' 2026-10-09 19:49:55+00:00 datetime
{"tag_name":"0.13.0","name":"0.13.0","published_at":"2026-10-09T19:49:55Z",...}
2 validation errors for Release
published_at
Input should be a valid datetime or date, input is too short [type=datetime_...
html_url
Field required [type=missing, input_value={'tag_name': 'v1', ...}, ...]
Warum? Der ISO-String wird zu einem zeitzonenbewussten
datetime, fehlende oder kaputte Felder fallen sofort mit
präziser Meldung auf – nicht erst drei Funktionen später als
KeyError.
Tipp:
uv init --packagehat insrc/ghrel/__init__.pyein Hallo-Welt-main()angelegt. Wir ersetzen es vorerst durch einen Docstring; in Drill 5 startetmain()dann das typer-CLI.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Timeouts, Retries, Backoff
Erst sehen, was ein Timeout ist. 10.255.255.1 ist eine
nicht routbare Adresse.
uv run python - <<'EOF'
import httpx
try:
httpx.get("http://10.255.255.1", timeout=httpx.Timeout(5.0, connect=1.0))
except httpx.TransportError as exc:
print(type(exc).__name__, "->", exc)
EOFErwartet (nach ca. 1 s):
ConnectTimeout -> timed out
Jetzt die Retry-Logik. sleep ist ein Parameter, damit
Tests nicht wirklich warten.
cat > src/ghrel/retry.py <<'EOF'
"""GET mit Timeouts, Retries, exponentiellem Backoff und Retry-After."""
import logging
import random
import time
from collections.abc import Callable
import httpx
log = logging.getLogger(__name__)
RETRY_STATUS = {429, 500, 502, 503, 504}
def backoff(attempt: int, base: float = 0.5, cap: float = 8.0) -> float:
"""Full Jitter: zufällig zwischen 0 und min(cap, base * 2**attempt)."""
return random.uniform(0, min(cap, base * 2**attempt))
def get(
client: httpx.Client,
url: str,
*,
retries: int = 3,
sleep: Callable[[float], None] = time.sleep,
) -> httpx.Response:
for attempt in range(retries + 1):
try:
resp = client.get(url)
except httpx.TransportError as exc: # Connect-Fehler, Timeouts
if attempt == retries:
raise
wait, reason = backoff(attempt), type(exc).__name__
else:
if resp.status_code not in RETRY_STATUS or attempt == retries:
return resp
ra = resp.headers.get("Retry-After", "")
wait = float(ra) if ra.isdigit() else backoff(attempt)
reason = str(resp.status_code)
log.warning("Versuch %d: %s, warte %.2fs", attempt + 1, reason, wait)
sleep(wait)
raise AssertionError("unreachable")
EOF
uv run python -c 'from ghrel.retry import backoff
print([round(backoff(a), 2) for a in range(6)])'Erwartet (zufällig, aber nie über 0.5, 1, 2, 4, 8, 8):
[0.3, 0.2, 1.82, 2.37, 5.07, 3.51]
Warum? Full Jitter verteilt die Wiederholungen vieler Clients zufällig – sonst hämmern alle gleichzeitig auf einen Server, der sich gerade erholt. 404 oder 401 werden nie wiederholt: Ein zweiter Versuch ändert nichts.
Der Test baut einen Fake-Server mit MockTransport, der
nacheinander 503, 429 und 200 liefert:
cat > tests/test_retry.py <<'EOF'
import httpx
from ghrel import retry
def client_for(*codes: int) -> httpx.Client:
it = iter(codes)
transport = httpx.MockTransport(
lambda req: httpx.Response(next(it), headers={"Retry-After": "2"})
)
return httpx.Client(base_url="https://lab.invalid", transport=transport)
def test_retry_until_success():
waits: list[float] = []
resp = retry.get(client_for(503, 429, 200), "/x", sleep=waits.append)
assert resp.status_code == 200
assert waits == [2.0, 2.0] # Retry-After schlägt Backoff
def test_retry_gives_up_after_retries():
resp = retry.get(client_for(502, 502, 502, 502), "/x", sleep=lambda s: None)
assert resp.status_code == 502
def test_no_retry_on_404():
waits: list[float] = []
resp = retry.get(client_for(404), "/x", sleep=waits.append)
assert resp.status_code == 404
assert waits == []
EOF
uv run pytest -q tests/test_retry.pyErwartet:
... [100%]
3 passed in 0.13s
Fortschritt speichern? Kostenlos registrieren
Drill 4: Der GitHub-Client
Ein httpx.Client mit base_url, festen
Headern und Timeout – einmal erzeugt, für alle Requests wiederverwendet
(Connection-Pooling).
cat > src/ghrel/github.py <<'EOF'
"""Dünner GitHub-Client: Header, Token, Fehlerbehandlung."""
import re
import httpx
from ghrel import retry
from ghrel.models import Release
API = "https://api.github.com"
REPO_RE = re.compile(r"^[\w.-]+/[\w.-]+$")
class GhError(Exception):
"""Fachlicher Fehler mit verständlicher Meldung."""
def make_client(
token: str | None = None, transport: httpx.BaseTransport | None = None
) -> httpx.Client:
headers = {
"Accept": "application/vnd.github+json",
"X-GitHub-Api-Version": "2022-11-28",
"User-Agent": "ghrel/0.1",
}
if token:
headers["Authorization"] = f"Bearer {token}"
return httpx.Client(
base_url=API,
headers=headers,
timeout=httpx.Timeout(10.0, connect=3.0),
transport=transport,
)
def latest_release(client: httpx.Client, repo: str) -> Release:
if not REPO_RE.match(repo):
raise GhError(f"{repo}: erwartet owner/name")
resp = retry.get(client, f"/repos/{repo}/releases/latest")
if resp.status_code == 404:
raise GhError(f"{repo}: kein Release oder Repo nicht gefunden")
remaining = resp.headers.get("x-ratelimit-remaining")
if resp.status_code in (403, 429) and remaining == "0":
raise GhError("Rate-Limit erreicht – GITHUB_TOKEN setzen")
resp.raise_for_status()
return Release.model_validate(resp.json())
EOFWarum? transport ist der Test-Hebel: Produktion nutzt
das Netz, Tests einen MockTransport. Der Repo-Name wird vor
dem Request per Regex geprüft – so landet kein ../ in der
URL.
Die Test-Antwort liegt als Fixture in conftest.py und
steht damit allen Testdateien zur Verfügung:
cat > tests/conftest.py <<'EOF'
import pytest
@pytest.fixture
def release() -> dict:
"""Gekürzte echte Antwort von /repos/astral-sh/uv/releases/latest."""
return {
"tag_name": "0.13.0",
"name": "0.13.0",
"published_at": "2026-10-09T19:49:55Z",
"html_url": "https://github.com/astral-sh/uv/releases/tag/0.13.0",
"prerelease": False,
"assets": [], # Extra-Felder ignoriert pydantic
}
EOF
cat > tests/test_github.py <<'EOF'
from datetime import UTC, datetime
import httpx
import pytest
from ghrel.github import GhError, latest_release, make_client
from ghrel.models import Release
def fake(handler) -> httpx.Client:
return make_client(transport=httpx.MockTransport(handler))
def test_model_parses_and_ages(release):
rel = Release.model_validate(release)
assert rel.published_at.tzinfo is not None
assert rel.age_days(datetime(2026, 10, 19, 20, tzinfo=UTC)) == 10
def test_latest_release_sends_token(release):
def handler(req):
assert req.url.path == "/repos/astral-sh/uv/releases/latest"
assert req.headers["Authorization"] == "Bearer lab-token-123" # Lab-Wert
return httpx.Response(200, json=release)
client = make_client("lab-token-123", httpx.MockTransport(handler))
assert latest_release(client, "astral-sh/uv").tag_name == "0.13.0"
@pytest.mark.parametrize(
("status", "headers", "msg"),
[
(404, {}, "nicht gefunden"),
(403, {"x-ratelimit-remaining": "0"}, "Rate-Limit"),
],
)
def test_latest_release_errors(status, headers, msg):
client = fake(lambda r: httpx.Response(status, headers=headers))
with pytest.raises(GhError, match=msg):
latest_release(client, "acme/nope")
def test_invalid_repo_name():
with pytest.raises(GhError, match="owner/name"):
latest_release(fake(lambda r: httpx.Response(200)), "kein-slash")
EOF
uv run pytest -qErwartet:
........ [100%]
8 passed in 0.72s
Sicherheit:
lab-token-123ist ein Lab-Wert. Echte Tokens nie in Tests, Code oder Shell-History – immer aus der Umgebung.
Fortschritt speichern? Kostenlos registrieren
Drill 5: Das CLI mit typer
typer baut aus Typ-Hints und Annotated ein CLI samt
--help (Tag 3).
cat > src/ghrel/cli.py <<'EOF'
"""CLI: ghrel owner/repo [owner/repo ...]"""
import json
import logging
import os
from typing import Annotated
import httpx
import typer
from ghrel.github import GhError, latest_release, make_client
app = typer.Typer(add_completion=False)
@app.command()
def main(
repos: Annotated[list[str], typer.Argument(help="owner/name, mehrere möglich")],
as_json: Annotated[bool, typer.Option("--json", help="JSON statt Tabelle")] = False,
verbose: Annotated[bool, typer.Option("-v", help="Retries loggen")] = False,
) -> None:
"""Zeigt das neueste Release je GitHub-Repo."""
logging.basicConfig(level=logging.INFO if verbose else logging.ERROR)
rows, failed = [], 0
with make_client(os.environ.get("GITHUB_TOKEN")) as client:
for repo in repos:
try:
rel = latest_release(client, repo)
except (GhError, httpx.HTTPError) as exc:
typer.echo(f"✘ {exc}", err=True)
failed += 1
continue
rows.append(
{
"repo": repo,
"tag": rel.tag_name,
"published": rel.published_at.date().isoformat(),
"age_days": rel.age_days(),
"url": str(rel.html_url),
}
)
if as_json:
typer.echo(json.dumps(rows, indent=2))
else:
for r in rows:
typer.echo(
f"{r['repo']:<24} {r['tag']:<12} {r['published']} "
f"vor {r['age_days']} Tagen"
)
raise typer.Exit(code=1 if failed else 0)
EOF
cat > src/ghrel/__init__.py <<'EOF'
"""ghrel – neueste GitHub-Releases im Terminal."""
from ghrel.cli import app
def main() -> None:
app()
EOF
cat > src/ghrel/__main__.py <<'EOF'
from ghrel import main
main()
EOF
uv run ghrel --helpErwartet (gekürzt):
Usage: ghrel [OPTIONS] {repos}...
Zeigt das neueste Release je GitHub-Repo.
│ * repos <str> owner/name, mehrere möglich [required] │
│ --json JSON statt Tabelle │
│ -v Retries loggen │
Warum? [project.scripts] zeigt weiter auf
ghrel:main – das startet jetzt die typer-App,
__main__.py ermöglicht zusätzlich
python -m ghrel. Ein Fehler bei einem Repo bricht nicht
alles ab: Meldung auf stderr, weiter mit dem nächsten, am Ende Exit-Code
1. Das ist das Verhalten, das du in Shell-Pipelines und CI willst.
Fortschritt speichern? Kostenlos registrieren
Drill 6: CLI-Test und Lint
Der CLI-Test tauscht per monkeypatch nur
make_client aus – der Rest läuft echt.
cat > tests/test_cli.py <<'EOF'
import json
import httpx
from typer.testing import CliRunner
from ghrel import cli
from ghrel.github import make_client
def test_cli_json_and_exit_code(monkeypatch, release):
def handler(req):
if "missing" in req.url.path:
return httpx.Response(404)
return httpx.Response(200, json=release)
transport = httpx.MockTransport(handler)
monkeypatch.setattr(cli, "make_client", lambda tok: make_client(tok, transport))
result = CliRunner().invoke(cli.app, ["astral-sh/uv", "acme/missing", "--json"])
assert result.exit_code == 1
assert json.loads(result.stdout)[0]["tag"] == "0.13.0"
assert "acme/missing" in result.stderr
EOF
cat >> pyproject.toml <<'EOF'
[tool.ruff.lint]
extend-select = ["E501", "B", "UP", "SIM"]
[tool.pytest.ini_options]
testpaths = ["tests"]
EOF
uv run pytest -q && uv run ruff check . && uv run ruff format --check .Erwartet:
......... [100%]
9 passed in 0.21s
All checks passed!
11 files already formatted
Fortschritt speichern? Kostenlos registrieren
Drill 7: Das Tool ist fertig
Mit Token steigt das Limit auf 5000 Anfragen pro Stunde. Hast du die GitHub-CLI, holst du den Token ohne ihn je anzuzeigen:
export GITHUB_TOKEN="$(gh auth token)"
uv run ghrel astral-sh/uv astral-sh/ruff openbao/openbao acme/gibtsnicht-xyz
echo "exit=$?"
uv run ghrel --json pydantic/pydantic
uv run ghrel -v astral-sh/uvErwartet (Versionen und Daten ändern sich):
✘ acme/gibtsnicht-xyz: kein Release oder Repo nicht gefunden
astral-sh/uv 0.13.0 2026-10-09 vor 0 Tagen
astral-sh/ruff 0.17.0 2026-10-09 vor 0 Tagen
openbao/openbao v2.7.1 2026-10-01 vor 8 Tagen
exit=1
[
{
"repo": "pydantic/pydantic",
"tag": "v2.14.0",
"published": "2026-10-08",
"age_days": 1,
"url": "https://github.com/pydantic/pydantic/releases/tag/v2.14.0"
}
]
INFO:httpx:HTTP Request: GET https://api.github.com/repos/astral-sh/uv/releases/...
astral-sh/uv 0.13.0 2026-10-09 vor 0 Tagen
Warum steht die Fehlermeldung oben? Fehler meldet ghrel
sofort, die Tabelle erst nach der Schleife. Mit --json und
jq wird ghrel zum Baustein:
uv run ghrel --json astral-sh/uv | jq -r '.[0].tag'.
Tipp: Kein
gh? Dann ein Fine-grained Token ohne Rechte (nur öffentliche Repos) anlegen und perread -s GITHUB_TOKEN; export GITHUB_TOKENsetzen – so landet er nicht in der History.
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/tag06-ghrel
check "Tests grün" "uv run pytest -q"
check "ruff sauber" "uv run ruff check . && uv run ruff format --check ."
check "Mock statt Netz in Tests" "grep -q MockTransport tests/test_github.py"
check "kein Token im Code" "! grep -rqE 'gh[pousr]_[A-Za-z0-9]{20,}' src tests"
check "falscher Name -> Exit 1" "! uv run ghrel kein-slash"
check "Live-Abfrage" "uv run ghrel astral-sh/uv | grep -q astral-sh/uv"Erwartet:
✔ Tests grün
✔ ruff sauber
✔ Mock statt Netz in Tests
✔ kein Token im Code
✔ falscher Name -> Exit 1
✔ Live-Abfrage
Challenge
Baue einen ETag-Cache: ghrel merkt sich pro Repo
ETag und Release in ~/.cache/ghrel.json und
schickt beim nächsten Lauf If-None-Match. Ein
304 Not Modified zählt bei authentifizierten Requests nicht
gegen das Rate-Limit.
Hinweis: retry.get braucht einen
zusätzlichen Parameter headers, latest_release
einen optionalen cache: dict.
Lösung
In src/ghrel/retry.py den Parameter ergänzen und
durchreichen:
retries: int = 3,
headers: dict[str, str] | None = None,
sleep: Callable[[float], None] = time.sleep,
...
resp = client.get(url, headers=headers)In src/ghrel/github.py die Funktion
latest_release ersetzen:
def latest_release(
client: httpx.Client, repo: str, cache: dict | None = None
) -> Release:
if not REPO_RE.match(repo):
raise GhError(f"{repo}: erwartet owner/name")
cached = (cache or {}).get(repo)
headers = {"If-None-Match": cached["etag"]} if cached else {}
resp = retry.get(client, f"/repos/{repo}/releases/latest", headers=headers)
if resp.status_code == 304 and cached: # zählt nicht gegen das Rate-Limit
return Release.model_validate(cached["data"])
if resp.status_code == 404:
raise GhError(f"{repo}: kein Release oder Repo nicht gefunden")
remaining = resp.headers.get("x-ratelimit-remaining")
if resp.status_code in (403, 429) and remaining == "0":
raise GhError("Rate-Limit erreicht – GITHUB_TOKEN setzen")
resp.raise_for_status()
rel = Release.model_validate(resp.json())
if cache is not None and "etag" in resp.headers:
cache[repo] = {
"etag": resp.headers["etag"],
"data": rel.model_dump(mode="json"),
}
return relIn src/ghrel/cli.py Cache laden, durchreichen und
speichern:
from pathlib import Path
...
CACHE = Path(os.environ.get("GHREL_CACHE", Path.home() / ".cache" / "ghrel.json"))
...
cache = json.loads(CACHE.read_text()) if CACHE.exists() else {}
with make_client(os.environ.get("GITHUB_TOKEN")) as client:
for repo in repos:
try:
rel = latest_release(client, repo, cache)
...
CACHE.parent.mkdir(parents=True, exist_ok=True)
CACHE.write_text(json.dumps(cache))Damit der CLI-Test nicht in dein echtes ~/.cache
schreibt, in tests/test_cli.py die Signatur um
tmp_path erweitern und als erste Zeile im Test
ergänzen:
def test_cli_json_and_exit_code(monkeypatch, release, tmp_path):
monkeypatch.setattr(cli, "CACHE", tmp_path / "ghrel.json")Test in tests/test_github.py anhängen:
def test_etag_cache_uses_304(release):
seen: list[str | None] = []
def handler(req):
seen.append(req.headers.get("If-None-Match"))
if req.headers.get("If-None-Match") == '"abc"':
return httpx.Response(304)
return httpx.Response(200, json=release, headers={"ETag": '"abc"'})
cache: dict = {}
client = fake(handler)
assert latest_release(client, "astral-sh/uv", cache).tag_name == "0.13.0"
assert latest_release(client, "astral-sh/uv", cache).tag_name == "0.13.0"
assert seen == [None, '"abc"']uv run pytest -q
export GHREL_CACHE=$PWD/cache.json
uv run ghrel -v astral-sh/uv 2>&1 | grep HTTP
uv run ghrel -v astral-sh/uv 2>&1 | grep HTTPErwartet (gekürzt):
10 passed in 0.34s
INFO:httpx:HTTP Request: GET https://api.github.com/.../latest "HTTP/1.1 200 OK"
INFO:httpx:HTTP Request: GET https://api.github.com/.../latest "HTTP/1.1 304 Not ...
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- GitHub Enterprise Server hat eine andere Basis-URL
(
https://ghe.example.com/api/v3) –APIper Umgebungsvariable konfigurierbar machen. - Firmen-Proxy und eigene CA: httpx liest
HTTPS_PROXY; die CA überSSL_CERT_FILEoderhttpx.Client(verify=ssl_context). Nieverify=False. - Für Automationen statt persönlicher Tokens eine GitHub App oder ein Fine-grained Token mit minimalen Rechten nutzen; Token aus Vault/OpenBao oder dem CI-Secret-Store.
- Retries brauchen ein Budget: Bei vielen Clients begrenzen Circuit Breaker und globale Rate-Limits, wie viel Last Wiederholungen erzeugen.
- Logs ohne
Authorization-Header: httpx loggt keine Header, eigene Debug-Ausgaben müssen Secrets maskieren.