Tag 2: Funktionen, Typen, Module – logsum
Ziel: Mit Funktionen, Typ-Hints, dataclasses und mehreren Modulen ein Tool
logsumbauen, das Accesslogs auswertet: Statuscodes, Top-Fehler, Zeitfenster · Dauer: ca. 120 min · Voraussetzung: Tag 1
Briefing
- Ein Modul ist eine
.py-Datei, ein Paket ein Ordner mit__init__.py.logsumbekommt drei Module mit klarer Aufgabe. @dataclasserzeugt__init__,__repr__und__eq__aus Typ-Annotationen – der Python-Ersatz für ein Go-struct.- Typ-Hints prüft nicht Python, sondern mypy. Das fängt Fehler, bevor sie in Produktion laufen.
- Keyword-only-Parameter (
*) machen Aufrufe mit vielen Optionen lesbar und robust.
access.log ──► parse.py parse_line() ──► LogEntry (dataclass)
│
stats.py summarize(since=, until=) ──► Summary
│
cli.py main() ──► argparse ──► render() ──► stdout
Drill 1: Projekt und Lab-Log
cd ~/py-lab
uv init -q --package --name logsum tag02-logsum
cd tag02-logsum
uv add -q --dev pytest ruff
cat >> pyproject.toml <<'EOF'
[tool.ruff.lint]
extend-select = ["E501", "B", "UP", "SIM"]
EOF
mkdir -p scripts labEin Generator-Skript erzeugt ein Log, das bei jedem Leser identisch ist:
cat > scripts/genlog.py <<'EOF'
"""Erzeugt ein reproduzierbares Lab-Accesslog im nginx-combined-Format."""
import random
import sys
from datetime import UTC, datetime, timedelta
PATHS = ["/api/orders", "/api/users", "/api/payments", "/login", "/health"]
AGENTS = ["curl/8.7.1", "Mozilla/5.0", "kube-probe/1.31"]
def line(rng: random.Random, ts: datetime) -> str:
path = rng.choice(PATHS)
weights = [70, 5, 10, 15] if path == "/api/payments" else [93, 3, 3, 1]
status = rng.choices([200, 404, 500, 503], weights=weights)[0]
stamp = ts.strftime("%d/%b/%Y:%H:%M:%S %z")
ip = f"10.0.{rng.randint(0, 3)}.{rng.randint(2, 254)}"
size = rng.randint(200, 5000)
agent = rng.choice(AGENTS)
return f'{ip} - - [{stamp}] "GET {path} HTTP/1.1" {status} {size} "-" "{agent}"'
def main() -> None:
count = int(sys.argv[1]) if len(sys.argv) > 1 else 2000
rng = random.Random(42) # fester Seed: jeder Leser bekommt dieselbe Datei
ts = datetime(2026, 10, 10, 8, 0, 0, tzinfo=UTC)
for i in range(count):
ts += timedelta(seconds=rng.randint(0, 3))
print("kaputte Zeile ohne Format" if i % 500 == 499 else line(rng, ts))
if __name__ == "__main__":
main()
EOF
uv run scripts/genlog.py > lab/access.log
head -2 lab/access.log | cut -c1-80
wc -l lab/access.log
shasum lab/access.logErwartet:
10.0.1.59 - - [10/Oct/2026:08:00:00 +0000] "GET /api/orders HTTP/1.1" 200 1343 "
10.0.3.10 - - [10/Oct/2026:08:00:00 +0000] "GET /health HTTP/1.1" 200 444 "-" "c
2000 lab/access.log
15b63b043ae5ba27386a9f87d8dd9bc30dc34b4e lab/access.log
Warum if __name__ == "__main__":? Beim direkten Start
ist __name__ gleich "__main__", beim Import
der Modulname. So bleibt die Datei importierbar, ohne sofort
loszulaufen. Mit random.Random(42) statt dem globalen
random ist der Zufall gekapselt und reproduzierbar.
Tipp:
uv run scripts/genlog.py 1000000 > lab/big.logerzeugt ein großes Log – das brauchst du an Tag 14, wennlogsumschneller werden soll.
Fortschritt speichern? Kostenlos registrieren
Drill 2: Eine dataclass und eine Parse-Funktion
cat > src/logsum/parse.py <<'EOF'
"""Logzeilen im nginx-combined-Format in LogEntry-Objekte verwandeln."""
import re
from dataclasses import dataclass
from datetime import datetime
LINE_RE = re.compile(
r"(?P<ip>\S+) \S+ \S+ \[(?P<time>[^\]]+)\] "
r'"(?P<method>\S+) (?P<path>\S+) \S+" (?P<status>\d{3}) (?P<size>\d+)'
)
TIME_FORMAT = "%d/%b/%Y:%H:%M:%S %z"
@dataclass(frozen=True, slots=True)
class LogEntry:
ip: str
time: datetime
method: str
path: str
status: int
size: int
def parse_line(line: str) -> LogEntry | None:
"""Eine Zeile parsen; None, wenn sie nicht ins Format passt."""
m = LINE_RE.match(line)
if m is None:
return None
return LogEntry(
ip=m["ip"],
time=datetime.strptime(m["time"], TIME_FORMAT),
method=m["method"],
path=m["path"],
status=int(m["status"]),
size=int(m["size"]),
)
EOFre.compileeinmal auf Modulebene, nicht pro Zeile. Benannte Gruppen(?P<name>...)liest du mitm["name"].frozen=Truemacht Einträge unveränderlich (und hashbar),slots=Truespart Speicher pro Objekt – bei Millionen Logzeilen spürbar.LogEntry | Nonesagt jedem Aufrufer: Prüf aufNone. mypy erzwingt das später.
uv run python - <<'EOF'
from pathlib import Path
from logsum.parse import parse_line
line = Path("lab/access.log").read_text(encoding="utf-8").splitlines()[1]
e = parse_line(line)
print(e)
print(e.status, e.time.isoformat(), parse_line("kaputt"))
try:
e.status = 500
except AttributeError as err:
print(type(err).__name__, err)
EOFErwartet (umbrochen):
LogEntry(ip='10.0.3.10', time=datetime.datetime(2026, 10, 10, 8, 0,
tzinfo=datetime.timezone.utc), method='GET', path='/health', status=200, size=444)
200 2026-10-10T08:00:00+00:00 None
FrozenInstanceError cannot assign to field 'status'
Das lesbare repr kommt gratis von
@dataclass. Der Zeitstempel ist timezone-aware
(+0000 aus dem Log) – das wird beim Zeitfenster
wichtig.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Kennzahlen in einem zweiten Modul
cat > src/logsum/stats.py <<'EOF'
"""Kennzahlen aus LogEntry-Listen berechnen."""
from collections import Counter
from collections.abc import Iterable
from dataclasses import dataclass, field
from datetime import datetime
from logsum.parse import LogEntry
@dataclass
class Summary:
total: int = 0
statuses: Counter[int] = field(default_factory=Counter)
errors: Counter[str] = field(default_factory=Counter)
first: datetime | None = None
last: datetime | None = None
@property
def error_rate(self) -> float:
failed = sum(n for code, n in self.statuses.items() if code >= 500)
return failed / self.total if self.total else 0.0
def in_window(
entry: LogEntry, since: datetime | None = None, until: datetime | None = None
) -> bool:
"""True, wenn der Eintrag im halboffenen Zeitfenster [since, until) liegt."""
if since is not None and entry.time < since:
return False
return until is None or entry.time < until
def summarize(
entries: Iterable[LogEntry],
*,
since: datetime | None = None,
until: datetime | None = None,
min_status: int = 500,
) -> Summary:
"""Zählt Statuscodes und Fehlerpfade (Status >= min_status) im Zeitfenster."""
s = Summary()
for e in entries:
if not in_window(e, since, until):
continue
s.total += 1
s.statuses[e.status] += 1
if e.status >= min_status:
s.errors[e.path] += 1
s.first = e.time if s.first is None else min(s.first, e.time)
s.last = e.time if s.last is None else max(s.last, e.time)
return s
EOFfield(default_factory=Counter): JedeSummarybekommt einen eigenen Counter. Ein veränderlicher Default wie= Counter()würde von allen Instanzen geteilt – Pythons klassische Falle, die dataclasses deshalb verbieten.*in der Signatur: Alles danach muss benannt übergeben werden.summarize(entries, since=t)ist eindeutig,summarize(entries, t, None, 400)wäre ein Rätsel.Iterable[LogEntry]stattlist[LogEntry]: Die Funktion nimmt Listen, Generatoren, alles Iterierbare.@propertymacht aus einer Methode ein berechnetes Attribut:s.error_rateohne Klammern.
uv run python - <<'EOF'
from pathlib import Path
from logsum.parse import parse_line
from logsum.stats import summarize
lines = Path("lab/access.log").read_text(encoding="utf-8").splitlines()
entries = [e for line in lines if (e := parse_line(line)) is not None]
s = summarize(entries)
print(s.total, len(lines) - len(entries), f"{s.error_rate:.1%}")
print(s.statuses.most_common())
print(s.errors.most_common(2))
EOFErwartet:
1996 4 8.4%
[(200, 1764), (500, 96), (503, 72), (404, 64)]
[('/api/payments', 107), ('/login', 19)]
Warum :=? Der Walrus-Operator weist zu und gibt den Wert
zurück – so wird jede Zeile nur einmal geparst und trotzdem
gefiltert.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Das CLI-Modul und die Paketstruktur
cat > src/logsum/cli.py <<'EOF'
"""logsum – Accesslogs auswerten: Statuscodes, Top-Fehler, Zeitfenster."""
import argparse
import sys
from datetime import UTC, datetime
from pathlib import Path
from logsum.parse import LogEntry, parse_line
from logsum.stats import Summary, summarize
def parse_time(value: str) -> datetime:
"""ISO-Zeit wie 2026-10-10T08:30; ohne Zeitzone gilt UTC."""
dt = datetime.fromisoformat(value)
return dt if dt.tzinfo else dt.replace(tzinfo=UTC)
def load(path: Path) -> tuple[list[LogEntry], int]:
"""Alle gültigen Einträge und die Zahl der übersprungenen Zeilen."""
entries: list[LogEntry] = []
skipped = 0
with path.open(encoding="utf-8") as f:
for line in f:
entry = parse_line(line)
if entry is None:
skipped += 1
else:
entries.append(entry)
return entries, skipped
def render(s: Summary, top: int) -> str:
out = [f"Anfragen: {s.total} Fehlerquote 5xx: {s.error_rate:.1%}"]
if s.first and s.last:
out.append(f"Zeitraum: {s.first:%H:%M:%S} - {s.last:%H:%M:%S} UTC")
out.append("Statuscodes:")
out += [f" {code} {n:>6}" for code, n in sorted(s.statuses.items())]
out.append(f"Top {top} Fehlerpfade:")
out += [f" {n:>6} {path}" for path, n in s.errors.most_common(top)]
return "\n".join(out)
def main(argv: list[str] | None = None) -> int:
p = argparse.ArgumentParser(prog="logsum", description=__doc__)
p.add_argument("logfile", type=Path, help="Accesslog im combined-Format")
p.add_argument("--top", type=int, default=3, help="Anzahl Fehlerpfade")
p.add_argument("--since", type=parse_time, help="ab Zeitpunkt (inklusive)")
p.add_argument("--until", type=parse_time, help="bis Zeitpunkt (exklusive)")
p.add_argument("--min-status", type=int, default=500, help="Fehler ab Code")
args = p.parse_args(argv)
try:
entries, skipped = load(args.logfile)
except OSError as err:
print(f"logsum: {err}", file=sys.stderr)
return 1
s = summarize(
entries, since=args.since, until=args.until, min_status=args.min_status
)
print(render(s, args.top))
if skipped:
print(f"logsum: {skipped} Zeilen übersprungen (Format)", file=sys.stderr)
return 0
EOF
cat > src/logsum/__init__.py <<'EOF'
"""logsum – Accesslogs auswerten."""
from logsum.cli import main
__all__ = ["main"]
EOF
cat > src/logsum/__main__.py <<'EOF'
from logsum.cli import main
raise SystemExit(main())
EOF
uv run logsum lab/access.logErwartet:
Anfragen: 1996 Fehlerquote 5xx: 8.4%
Zeitraum: 08:00:00 - 08:50:24 UTC
Statuscodes:
200 1764
404 64
500 96
503 72
Top 3 Fehlerpfade:
107 /api/payments
19 /login
16 /api/orders
logsum: 4 Zeilen übersprungen (Format)
pyproject.tomlzeigt weiter auflogsum:main. Das__init__.pyreichtmainausclidurch – die öffentliche Schnittstelle des Pakets bleibt stabil, egal wie du intern umbaust.__all__dokumentiert sie.type=parse_time: argparse ruft deine Funktion für den Wert auf. Jede Funktionstr -> Xist ein gültiger Typ.with path.open(...)schließt die Datei garantiert, auch bei Fehlern, und liest zeilenweise statt alles auf einmal.f"{s.first:%H:%M:%S}": Format-Spezifikationen funktionieren auch fürdatetime.
Achtung: Naive und aware
datetime-Werte lassen sich nicht vergleichen (TypeError). Deshalb machtparse_timejede Eingabe ohne Zeitzone zu UTC.
Fortschritt speichern? Kostenlos registrieren
Drill 5: Typen prüfen mit mypy
Python ignoriert Typ-Hints zur Laufzeit:
uv run python -c \
'from logsum.stats import summarize; print(summarize([], since="x"))'Erwartet:
Summary(total=0, statuses=Counter(), errors=Counter(), first=None, last=None)
mypy nicht. Baue zwei Fehler ein und prüfe mit uvx – das
startet mypy in einer Wegwerf-Umgebung, ohne es zu installieren:
cat > src/logsum/typo.py <<'EOF'
from logsum.stats import summarize
s = summarize([], since="2026-10-10T08:30")
print(s.total + "Anfragen")
EOF
uv run --with mypy mypy src; echo "exit=$?"Erwartet (umbrochen):
src/logsum/typo.py:3: error: Argument "since" to "summarize" has incompatible
type "str"; expected "datetime | None" [arg-type]
src/logsum/typo.py:4: error: Unsupported operand types for + ("int" and "str")
[operator]
Found 2 errors in 1 file (checked 6 source files)
exit=1
rm src/logsum/typo.py
uv run --with mypy mypy --strict srcErwartet:
Success: no issues found in 5 source files
Warum --strict? Es verlangt Typ-Hints an jeder Funktion
und verbietet implizites Any. Für neue Tools ist das der
richtige Standard; an Tag 5 kommt mypy fest in die
Qualitäts-Pipeline.
Fortschritt speichern? Kostenlos registrieren
Drill 6: Tests
mkdir -p tests
cat > tests/test_logsum.py <<'EOF'
from datetime import UTC, datetime
from logsum.cli import parse_time
from logsum.parse import LogEntry, parse_line
from logsum.stats import summarize
LINE = (
'10.0.3.10 - - [10/Oct/2026:08:00:00 +0000] "GET /health HTTP/1.1" '
'503 444 "-" "curl/8.7.1"'
)
def entry(minute: int, status: int = 200, path: str = "/x") -> LogEntry:
t = datetime(2026, 10, 10, 8, minute, tzinfo=UTC)
return LogEntry("10.0.0.1", t, "GET", path, status, 1)
def test_parse_line():
e = parse_line(LINE)
assert e is not None
assert (e.path, e.status, e.time.hour) == ("/health", 503, 8)
def test_parse_line_kaputt():
assert parse_line("kaputte Zeile") is None
def test_summarize_zaehlt_status_und_fehler():
s = summarize([entry(0), entry(1, 500, "/pay"), entry(2, 503, "/pay")])
assert s.total == 3
assert s.statuses[200] == 1
assert s.errors.most_common(1) == [("/pay", 2)]
assert round(s.error_rate, 2) == 0.67
def test_summarize_zeitfenster_ist_halboffen():
entries = [entry(m) for m in range(10)]
s = summarize(entries, since=parse_time("2026-10-10T08:03"), until=entry(6).time)
assert s.total == 3
assert s.first == entry(3).time
assert s.last == entry(5).time
def test_summarize_leer():
s = summarize([])
assert s.total == 0
assert s.error_rate == 0.0
def test_parse_time_setzt_utc():
assert parse_time("2026-10-10T08:30").tzinfo is UTC
EOF
uv run pytest -q
uv run ruff check && uv run ruff format --checkErwartet:
...... [100%]
6 passed in 0.01s
All checks passed!
8 files already formatted
Warum die Hilfsfunktion entry()? Tests bauen ihre Daten
selbst, statt von lab/access.log abzuhängen. Gute
Default-Argumente halten jeden Test bei einer Zeile Setup.
Fortschritt speichern? Kostenlos registrieren
Drill 7: Das Tool ist fertig
uv run logsum lab/access.log --since 2026-10-10T08:30 --until 2026-10-10T08:40 \
--min-status 400 --top 5
uv run logsum lab/access.log --since 08:30; echo "exit=$?"
uv run logsum nix.log; echo "exit=$?"Erwartet:
Anfragen: 390 Fehlerquote 5xx: 8.7%
Zeitraum: 08:30:00 - 08:39:59 UTC
Statuscodes:
200 344
404 12
500 18
503 16
Top 5 Fehlerpfade:
24 /api/payments
10 /login
5 /health
4 /api/users
3 /api/orders
logsum: 4 Zeilen übersprungen (Format)
usage: logsum [-h] [--top TOP] [--since SINCE] [--until UNTIL]
[--min-status MIN_STATUS]
logfile
logsum: error: argument --since: invalid parse_time value: '08:30'
exit=2
logsum: [Errno 2] No such file or directory: 'nix.log'
exit=1
Das Zeitfenster ist halboffen: 08:40:00 gehört nicht
mehr dazu, deshalb endet der Zeitraum bei 08:39:59. So
lassen sich Fenster lückenlos aneinanderreihen.
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/tag02-logsum
check "Lab-Log reproduzierbar" \
"uv run scripts/genlog.py | shasum | grep -q ^15b63b043ae5"
check "1996 Anfragen gezählt" "uv run logsum lab/access.log | grep -q 'Anfragen: 1996'"
check "Top-Fehler /api/payments" \
"uv run logsum lab/access.log --top 1 | grep -q '107 /api/payments'"
check "Zeitfenster greift" "uv run logsum lab/access.log \
--since 2026-10-10T08:30 --until 2026-10-10T08:40 | grep -q 'Anfragen: 390'"
check "falsche Zeit gibt Exit 2" \
"uv run logsum lab/access.log --since gestern; test \$? -eq 2"
check "mypy --strict sauber" "uv run --with mypy mypy --strict src"
check "Tests grün" "uv run pytest -q"
check "ruff sauber" "uv run ruff check && uv run ruff format --check"Erwartet:
✔ Lab-Log reproduzierbar
✔ 1996 Anfragen gezählt
✔ Top-Fehler /api/payments
✔ Zeitfenster greift
✔ falsche Zeit gibt Exit 2
✔ mypy --strict sauber
✔ Tests grün
✔ ruff sauber
Challenge
Ergänze --json: Statt des Textreports gibt
logsum die Summary als JSON aus, damit
jq und andere Tools sie weiterverarbeiten können.
Hinweis: dataclasses.asdict() klingt
passend – probier es mit einem Counter aus und baue das
Dict dann lieber selbst.
Lösung
asdict() kopiert Dicts über ihren Konstruktor; ein
Counter zählt dabei die (key, value)-Paare
statt sie zu übernehmen. Also ein eigenes to_dict() in
src/logsum/cli.py, oben import json
ergänzen:
def to_dict(s: Summary) -> dict[str, object]:
return {
"total": s.total,
"error_rate": round(s.error_rate, 4),
"statuses": {str(code): n for code, n in sorted(s.statuses.items())},
"errors": dict(s.errors.most_common()),
"first": s.first.isoformat() if s.first else None,
"last": s.last.isoformat() if s.last else None,
}In main() die Option ergänzen und die Ausgabe
umschalten:
p.add_argument("--json", action="store_true", help="Ausgabe als JSON")
...
print(json.dumps(to_dict(s), indent=2) if args.json else render(s, args.top))uv run logsum lab/access.log --json --since 2026-10-10T08:45 2>/dev/null
uv run logsum lab/access.log --json 2>/dev/null | jq -r '.errors | to_entries[0].key'
uv run --with mypy mypy --strict src && uv run pytest -qErwartet (gekürzt):
{
"total": 212,
"error_rate": 0.0755,
"statuses": {
"200": 187,
"404": 9,
"500": 9,
"503": 7
},
"errors": {
"/api/payments": 13,
"/login": 2,
"/api/users": 1
},
"first": "2026-10-10T08:45:02+00:00",
"last": "2026-10-10T08:50:24+00:00"
}
/api/payments
Success: no issues found in 5 source files
6 passed in 0.01s
JSON kennt nur String-Schlüssel, deshalb str(code);
datetime wird mit isoformat() zum String.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Echte Logformate variieren (Proxy-IPs,
X-Forwarded-For, Request-Zeit am Zeilenende). Format als Konfiguration halten und kaputte Zeilen zählen, nie still verwerfen. - Für strukturierte Logs (JSON pro Zeile)
json.loadsstatt Regex – und am besten gleich bei der Quelle auf JSON-Logging umstellen. - Zeit immer in UTC rechnen und erst bei der Anzeige umwandeln; Logs aus mehreren Zeitzonen sonst nie mischen.
- Bei GB-großen Logs nicht alles in eine Liste laden: Generatoren und Streaming (Tag 14) oder gleich Loki/Elasticsearch abfragen.
- IP-Adressen sind personenbezogene Daten (DSGVO): Reports, die das Team verlassen, anonymisieren oder kürzen.