Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 6: HTTP und APIs – ghrel

Ziel: Ein CLI ghrel bauen, das robust die neuesten GitHub-Releases abfragt · Dauer: ca. 120 min · Voraussetzung: Tag 5

Briefing

  • httpx ist der moderne HTTP-Client: sync und async mit derselben API, Timeouts Pflicht.
  • Antworten landen nie als nacktes dict im Code, sondern als validiertes pydantic-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)
EOF

Erwartet (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)
EOF

Erwartet (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 --package hat in src/ghrel/__init__.py ein Hallo-Welt-main() angelegt. Wir ersetzen es vorerst durch einen Docstring; in Drill 5 startet main() 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)
EOF

Erwartet (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.py

Erwartet:

...                                                                      [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())
EOF

Warum? 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 -q

Erwartet:

........                                                                 [100%]
8 passed in 0.72s

Sicherheit: lab-token-123 ist 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 --help

Erwartet (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/uv

Erwartet (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 per read -s GITHUB_TOKEN; export GITHUB_TOKEN setzen – 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 rel

In 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 HTTP

Erwartet (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) – API per Umgebungsvariable konfigurierbar machen.
  • Firmen-Proxy und eigene CA: httpx liest HTTPS_PROXY; die CA über SSL_CERT_FILE oder httpx.Client(verify=ssl_context). Nie verify=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.