Zum Inhalt springen
Trainingslager IT-Trainingslager

Anhang A: Spickzettel

Getestet mit Python 3.14.8, uv 0.9.26, ruff 0.17, pytest 9.1, mypy 2.4, typer 0.27, httpx 0.28, pydantic 2.14, openai 3.28, mcp 2.3 und Ollama (ministral-3:3b, all-minilm). Jeder Python-Block läuft für sich mit uv run python datei.py.

Syntax und Idiome

# f-Strings: Ausrichtung, Tausender, Prozent, Datum, Debug mit =
n, rate, name = 1234567, 0.0842, "logsum"
print(f"{name:<8}|{n:>12,}|{rate:.1%}|{n=}")
# Comprehensions: Liste, Dict, Set, Generator (lazy)
squares = [x * x for x in range(5) if x % 2 == 0]
lengths = {w: len(w) for w in ("vault", "bao")}
total = sum(x * x for x in range(1_000_000))
# Walrus: zuweisen und prüfen in einem Ausdruck
if (m := len(squares)) > 2:
    print(m, squares, lengths, total)
# Entpacken, Rest sammeln, tauschen
first, *rest = [1, 2, 3]
a, b = 1, 2
a, b = b, a
# match: Struktur prüfen und zerlegen
match {"status": 503, "path": "/api"}:
    case {"status": 200}:
        print("ok")
    case {"status": s, "path": p} if s >= 500:
        print(f"Serverfehler {s} auf {p}")
# dict.get mit Default, setdefault, Merge mit |
cfg = {"timeout": 5} | {"retries": 3}
print(cfg.get("proxy", "kein Proxy"), first, rest, a, b)
# dataclass: Werte-Objekt mit Defaults, unveränderlich und schlank
from dataclasses import dataclass, field


@dataclass(frozen=True, slots=True)
class Target:
    host: str
    port: int = 443
    tags: tuple[str, ...] = ()


@dataclass
class Report:
    targets: list[Target] = field(default_factory=list)  # nie: = []


r = Report()
r.targets.append(Target("vault.lab", 8200, ("prod",)))
print(r)
# Typ-Hints: Union mit |, Optional, Callable, Generics (PEP 695), TypedDict
from collections.abc import Callable, Iterator
from typing import TypedDict


class Row(TypedDict):
    name: str
    cost: float


def first[T](items: list[T], default: T | None = None) -> T | None:
    return items[0] if items else default


def apply(fn: Callable[[int], int], xs: list[int]) -> Iterator[int]:
    yield from (fn(x) for x in xs)


row: Row = {"name": "EC2", "cost": 12.5}
print(first([3, 4]), first([]), list(apply(lambda x: x * 2, [1, 2])), row)
# Fehler: eigene Exception, Ursache anhängen, mehrere Typen, finally
class ToolError(Exception):
    """Fachlicher Fehler des Tools."""


def load(path: str) -> str:
    try:
        with open(path, encoding="utf-8") as f:
            return f.read()
    except FileNotFoundError as err:
        raise ToolError(f"fehlt: {path}") from err
    except PermissionError, IsADirectoryError:  # 3.14: ohne Klammern (ohne as)
        raise ToolError(f"nicht lesbar: {path}") from None


try:
    load("/gibt/es/nicht")
except ToolError as err:
    print(err, "| Ursache:", type(err.__cause__).__name__)

Standardbibliothek für Tools

Modul Wofür Tag
pathlib Pfade, glob, read_text, Path.move() (3.14) 1, 3
argparse CLI ohne Abhängigkeit 2
subprocess Systembefehle: run([...], check=True) 3
logging Diagnose nach stderr, Level per Option 4
json, tomllib, csv Formate lesen (TOML nur lesen) 3, 8
sqlite3 eingebettete Datenbank 8
re Regex: compile, benannte Gruppen 2
collections Counter, defaultdict 2, 15
datetime Zeit, immer mit Zeitzone (UTC) 2, 4
hashlib, secrets Prüfsummen, sichere Zufallswerte 9, 15
concurrent.futures Thread- und Prozess-Pools 7, 14
asyncio viele gleichzeitige Netzaufrufe 7
functools cache, lru_cache, partial 14
cProfile, tracemalloc, timeit messen statt raten 14
zipapp Tool als eine ausführbare Datei 14
# Die Handgriffe, die in fast jedem Tool vorkommen
import hashlib
import json
import logging
import os
import secrets
import subprocess
from collections import Counter
from datetime import UTC, datetime
from pathlib import Path

log = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s: %(message)s")

here = Path.cwd()
pys = sorted(p.name for p in here.glob("*.py"))
r = subprocess.run(["uname", "-s"], capture_output=True, text=True, check=True)
digest = hashlib.sha256(b"lab").hexdigest()[:12]
token = secrets.token_urlsafe(16)  # Lab-Token, z. B. für Tests
now = datetime.now(UTC).isoformat(timespec="seconds")
words = Counter("abaca").most_common(1)
debug = os.environ.get("TOOL_DEBUG", "0") == "1"
log.info("%s Dateien, OS %s", len(pys), r.stdout.strip())
print(json.dumps({"sha": digest, "now": now, "top": words, "debug": debug}))

uv

# Python und Projekte
uv python install 3.14
uv init -p 3.14 --package --name tool tool       # src-Layout + Konsolenskript
uv add httpx 'typer>=0.27'                         # Laufzeit-Abhängigkeit
uv add --dev pytest ruff mypy                      # nur für Entwicklung
uv remove httpx
uv sync --locked                                   # CI: Lockfile muss passen
uv lock --upgrade-package httpx
uv tree --depth 1
# Ausführen
uv run tool --help                                 # Projekt-venv, Paket editable
uv run --with polars script.py                     # Zusatzpaket nur für den Lauf
uv run --no-project -p 3.14t python cpu.py         # free-threaded Build
uvx ruff check                                     # Werkzeug ohne Installation
uvx --from actionlint-py actionlint                # Paketname != Befehl
# Version, Bauen, Installieren
uv version --bump minor                            # 0.1.0 => 0.2.0
uv version --short
uv build                                           # dist/*.whl + dist/*.tar.gz
uv tool install dist/tool-0.2.0-py3-none-any.whl
uv tool install --editable .                       # während der Entwicklung
uv tool list
uv tool uninstall tool

ruff, pytest, mypy

uv run ruff check                  # Lint (Exit 1 bei Fund)
uv run ruff check --fix            # sichere Fixes anwenden
uv run ruff format                 # formatieren; --check nur prüfen
uv run ruff rule S602              # Regel erklären lassen
uv run pytest -q                   # alle Tests
uv run pytest -q -k parse -x       # nur passende, beim ersten Fehler stoppen
uv run pytest -v --lf              # nur die zuletzt fehlgeschlagenen
uv run pytest --cov=tool --cov-report=term-missing --cov-fail-under=85
uv run mypy                        # mit [tool.mypy] strict = true, files = ["src"]
uv run --with mypy mypy --strict src   # ohne Dev-Abhängigkeit
[tool.ruff.lint]
extend-select = ["E501", "B", "UP", "SIM", "I", "S"]

[tool.ruff.lint.per-file-ignores]
"tests/*" = ["S101"]

[tool.mypy]
strict = true
files = ["src"]

[[tool.mypy.overrides]]
module = ["sklearn.*", "joblib.*"]   # Pakete ohne Typ-Informationen
ignore_missing_imports = true

[tool.pytest.ini_options]
testpaths = ["tests"]
# pytest: Fixture, parametrize, tmp_path, monkeypatch, raises, Mock
from unittest.mock import MagicMock

import pytest


def parse_port(s: str) -> int:
    port = int(s)
    if not 0 < port < 65536:
        raise ValueError(f"Port außerhalb: {port}")
    return port


@pytest.fixture
def config(tmp_path):
    path = tmp_path / "tool.toml"
    path.write_text('port = "8200"\n', encoding="utf-8")
    return path


@pytest.mark.parametrize(("raw", "port"), [("80", 80), ("8200", 8200)])
def test_parse_port(raw, port):
    assert parse_port(raw) == port


def test_parse_port_fehler():
    with pytest.raises(ValueError, match="außerhalb"):
        parse_port("70000")


def test_env_und_mock(config, monkeypatch):
    monkeypatch.setenv("TOOL_PORT", "8200")
    client = MagicMock()
    client.get.return_value.status_code = 200
    assert client.get("/health").status_code == 200
    client.get.assert_called_once_with("/health")
    assert config.read_text(encoding="utf-8").startswith("port")

Ausführen: als tests/test_spick.py speichern, dann uv run pytest -q tests/test_spick.py.

typer

# CLI mit Unterbefehlen, Argument/Option per Annotated, Exit-Codes
from pathlib import Path
from typing import Annotated

import typer

app = typer.Typer(help="Lab-Tool", no_args_is_help=True, add_completion=False)
Dir = Annotated[Path, typer.Argument(exists=True, file_okay=False)]


@app.command()
def scan(
    directory: Dir,
    limit: Annotated[int, typer.Option("--limit", "-n", min=1)] = 10,
    dry_run: Annotated[bool, typer.Option(help="nichts ändern")] = True,
) -> None:
    """Listet Dateien. Exit 1, wenn keine gefunden wurden."""
    files = sorted(p for p in directory.iterdir() if p.is_file())[:limit]
    for p in files:
        typer.echo(p.name)
    if not files:
        typer.echo("nichts gefunden", err=True)  # nach stderr
        raise typer.Exit(1)


@app.command()
def version() -> None:
    typer.echo("lab 0.1.0")


if __name__ == "__main__":
    app()
Exit-Code Konvention im Buch
0 alles in Ordnung
1 fachlicher Befund (Duplikate, Konflikte, Fehler gefunden)
2 Bedienfehler (typer/argparse, typer.BadParameter)
3 Umgebung kaputt (Netz, Systembefehl, Nagios: UNKNOWN)

httpx

# Client mit Timeout, Basis-URL, Header; Retry mit Backoff; Tests ohne Netz
import random
import time

import httpx


def backoff(attempt: int, base: float = 0.5, cap: float = 8.0) -> float:
    return min(cap, base * 2**attempt) * random.uniform(0.5, 1.0)


def get_json(client: httpx.Client, path: str, retries: int = 3) -> object:
    for attempt in range(retries + 1):
        try:
            r = client.get(path)
            if r.status_code not in (429, 500, 502, 503, 504):
                r.raise_for_status()  # 4xx: sofort Fehler, kein Retry
                return r.json()
        except httpx.TransportError:  # Timeout, DNS, Verbindung
            if attempt == retries:
                raise
        time.sleep(backoff(attempt))
    r.raise_for_status()
    return r.json()


def handler(request: httpx.Request) -> httpx.Response:
    return httpx.Response(200, json={"path": request.url.path})


client = httpx.Client(
    base_url="https://api.lab",
    timeout=httpx.Timeout(5.0, connect=2.0),
    headers={"User-Agent": "lab-tool/0.1"},
    transport=httpx.MockTransport(handler),  # nur im Test
)
print(get_json(client, "/v1/status"))

pydantic

# Validieren an der Grenze: JSON rein, geprüftes Objekt raus
from datetime import datetime

from pydantic import BaseModel, Field, HttpUrl, ValidationError


class Release(BaseModel):
    tag: str = Field(alias="tag_name")
    url: HttpUrl = Field(alias="html_url")
    published: datetime = Field(alias="published_at")
    prerelease: bool = False


raw = (
    '{"tag_name": "v1.2.0", "html_url": "https://github.com/lab/x",'
    ' "published_at": "2026-10-01T12:00:00Z", "extra": 1}'
)
rel = Release.model_validate_json(raw)  # unbekannte Felder werden ignoriert
print(rel.tag, rel.published.year, rel.model_dump(mode="json")["url"])
print(Release.model_json_schema()["required"])
try:
    Release.model_validate({"tag_name": "v1", "html_url": "kein-url"})
except ValidationError as err:
    print(err.error_count(), "Fehler:", err.errors()[0]["loc"])

asyncio

# Viele Netzaufrufe gleichzeitig, begrenzt, mit Timeout pro Aufruf
import asyncio

import httpx


async def check(client: httpx.AsyncClient, sem: asyncio.Semaphore, url: str) -> str:
    async with sem:
        try:
            async with asyncio.timeout(2):
                r = await client.get(url)
            return f"{r.status_code} {url}"
        except (TimeoutError, httpx.TransportError) as err:
            return f"ERR {url} {type(err).__name__}"


async def main(urls: list[str], concurrency: int = 20) -> list[str]:
    sem = asyncio.Semaphore(concurrency)
    async with httpx.AsyncClient() as client, asyncio.TaskGroup() as tg:
        tasks = [tg.create_task(check(client, sem, u)) for u in urls]
    return [t.result() for t in tasks]  # Reihenfolge wie die Eingabe


print(asyncio.run(main(["http://127.0.0.1:9/a", "http://127.0.0.1:9/b"])))
Last Werkzeug
viel Warten (Netz, Disk) asyncio + httpx.AsyncClient
Warten, nur sync-Bibliothek ThreadPoolExecutor
CPU-Last ProcessPoolExecutor (Guard if __name__ == "__main__")
CPU-Last, 3.14t Threads, wenn alle C-Extensions mitspielen

Messen und Ausliefern

hyperfine -w 1 -r 5 'uv run tool big.log' 'uv run tool big.log -w 0'
uv run python -m cProfile -s tottime -m tool big.log 2>&1 | head -20
uv run python -m cProfile -o prof.out -m tool big.log     # dann pstats
uv run --with line_profiler python scripts/lineprof.py big.log
uv run python -m timeit -s 'import re; rx = re.compile("a+")' 'rx.match("aaa")'
uvx py-spy top --pid 4711                                  # macOS: sudo
uv run python -m zipapp build/pyz -p '/usr/bin/env python3' -c -o dist/tool.pyz
# Speicher: Spitze und Verursacher mit tracemalloc
import tracemalloc

tracemalloc.start()
data = [str(i) * 10 for i in range(100_000)]
current, peak = tracemalloc.get_traced_memory()
top = tracemalloc.take_snapshot().statistics("lineno")[0]
print(f"Spitze {peak / 2**20:.1f} MiB; größter Posten: {top.size / 2**20:.1f} MiB")

KI: OpenAI-kompatibel gegen Ollama und Cloud

# Ein Client für alles: nur base_url, Key und Modell ändern sich
import os

from openai import OpenAI

BASE_URL = os.environ.get("ASK_BASE_URL", "http://127.0.0.1:11434/v1")
MODEL = os.environ.get("ASK_MODEL", "ministral-3:3b")
client = OpenAI(
    base_url=BASE_URL,
    api_key=os.environ.get("ASK_API_KEY", "ollama"),  # Ollama ignoriert den Key
    timeout=120,
    max_retries=1,
)
resp = client.chat.completions.create(
    model=MODEL,
    messages=[
        {"role": "system", "content": "Antworte in einem Satz auf Deutsch."},
        {"role": "user", "content": "Was ist ein Inode?"},
    ],
    temperature=0,
)
print(resp.choices[0].message.content)
print(resp.usage.prompt_tokens if resp.usage else "-", "Tokens im Prompt")
Ziel base_url Key aus
Ollama lokal http://127.0.0.1:11434/v1 egal (ollama)
vLLM im Cluster http://vllm.lab:8000/v1 Secret-Store
Mistral https://api.mistral.ai/v1 MISTRAL_API_KEY
OpenAI Standard (weglassen) OPENAI_API_KEY
# Streaming mit Token-Zählung
from openai import OpenAI

client = OpenAI(base_url="http://127.0.0.1:11434/v1", api_key="ollama")
stream = client.chat.completions.create(
    model="ministral-3:3b",
    messages=[{"role": "user", "content": "Zähle von 1 bis 5."}],
    stream=True,
    stream_options={"include_usage": True},
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
    if chunk.usage:
        print(f"\n[{chunk.usage.completion_tokens} Tokens]")
# Strukturierte Ausgabe: pydantic-Schema rein, validiertes Objekt raus
from typing import Literal

from openai import OpenAI
from pydantic import BaseModel


class Triage(BaseModel):
    severity: Literal["ok", "warn", "crit"]
    reason: str


client = OpenAI(base_url="http://127.0.0.1:11434/v1", api_key="ollama")
resp = client.chat.completions.parse(
    model="ministral-3:3b",
    messages=[{"role": "user", "content": "Disk 97 % voll auf db-0. Bewerte."}],
    response_format=Triage,
    temperature=0,
)
triage = resp.choices[0].message.parsed
print(triage)
# Embeddings + Kosinus-Ähnlichkeit mit numpy
import numpy as np
from openai import OpenAI

client = OpenAI(base_url="http://127.0.0.1:11434/v1", api_key="ollama")
docs = ["Vault entsiegeln mit Unseal-Keys", "Pod hängt in CrashLoopBackOff"]
query = "how to unseal vault"
resp = client.embeddings.create(model="all-minilm", input=[*docs, query])
vecs = np.array([d.embedding for d in resp.data])
vecs /= np.linalg.norm(vecs, axis=1, keepdims=True)  # normieren
scores = vecs[:-1] @ vecs[-1]  # Kosinus = Skalarprodukt normierter Vektoren
best = int(np.argmax(scores))
print(vecs.shape, [round(float(s), 2) for s in scores], docs[best])
# Tool Calling: Modell wählt Funktion, du führst sie aus (nur erlaubte!)
import json
import os

from openai import OpenAI


def disk_free_gb(path: str = "/") -> float:
    st = os.statvfs(path)
    return round(st.f_bavail * st.f_frsize / 1e9, 1)


TOOLS = {"disk_free_gb": disk_free_gb}
SCHEMA = [
    {
        "type": "function",
        "function": {
            "name": "disk_free_gb",
            "description": "Freier Platz in GB für einen Pfad",
            "parameters": {
                "type": "object",
                "properties": {"path": {"type": "string"}},
                "required": ["path"],
            },
        },
    }
]
client = OpenAI(base_url="http://127.0.0.1:11434/v1", api_key="ollama")
messages = [{"role": "user", "content": "Wie viel Platz ist auf / frei?"}]
for _ in range(3):  # harte Obergrenze für die Schleife
    msg = client.chat.completions.create(
        model="ministral-3:3b", messages=messages, tools=SCHEMA, temperature=0
    ).choices[0].message
    if not msg.tool_calls:
        print(msg.content)
        break
    messages.append(msg.model_dump(exclude_none=True))
    for call in msg.tool_calls:
        fn = TOOLS.get(call.function.name)  # Allowlist statt eval
        args = json.loads(call.function.arguments)
        result = fn(**args) if fn else "unbekanntes Tool"
        messages.append(
            {"role": "tool", "tool_call_id": call.id, "content": json.dumps(result)}
        )
# MCP-Server (mcp >= 2: MCPServer statt FastMCP) und Client im selben Prozess
import asyncio
import shutil

from mcp import Client
from mcp.server.mcpserver import MCPServer
from mcp.types import ToolAnnotations

server = MCPServer("lab-tools", instructions="Read-only Infos.")


def disk_usage(path: str = "/") -> dict[str, float]:
    """Belegung des Dateisystems in GB."""
    u = shutil.disk_usage(path)
    return {"total_gb": round(u.total / 1e9, 1), "free_gb": round(u.free / 1e9, 1)}


server.add_tool(disk_usage, annotations=ToolAnnotations(read_only_hint=True))


async def main() -> None:
    async with Client(server) as client:
        tools = await client.list_tools()
        result = await client.call_tool("disk_usage", {"path": "/"})
        print([t.name for t in tools.tools], result.structured_content)


asyncio.run(main())  # als Dienst stattdessen: server.run()  (stdio)

Sicherheit: LLM-Ausgaben sind Daten, nie Befehle. Tools nur aus einer Allowlist, Argumente validieren, nichts an subprocess mit shell=True geben, Schleifen mit Obergrenze. Keys nur aus der Umgebung oder einem Secret-Store.