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.