Abschlussprojekt · Übung
Fehler, Budget und Exit-Codes
Die drei Befehle funktionieren, und jeder gibt entweder seinen Text zurück oder löst einen Fehler aus. Noch entscheidet nichts, was die Person sieht, wenn etwas schiefgeht, oder mit welchem Exit-Code das Programm endet. Das ist die Aufgabe der Grenze des Programms, des Codes zwischen der main(argv=None) aus Kapitel 8 von Python in der Praxis, nur erwachsen geworden: dieselbe Form, wobei jeder Fehler, auf den der Lernassistent stoßen kann, einem von wenigen Exit-Codes zugeordnet wird.
Du schreibst drei Funktionen und dann die Zeile, die das Programm startet.
Von der Ursache zum Exit-Code
Seit Kapitel 3 hast du Code geschrieben, der für jede Art von Fehler einen bestimmten Fehler auslöst. Hier kommen sie alle zusammen, und jeder bekommt einen Code:
1, der Lauf ist fehlgeschlagen. Der Agent hat ohne Antwort aufgehört (
ValueErrorausask_command), eine Antwort oder ein Quiz war auch nach dem erneuten Versuch ungültig (ValidationError, eine ArtValueError, oder der eigeneValueErrorvonask), eine Quiz-Antwort hatte keinen Text (ValueError), eine Antwort wurde beimax_tokensabgeschnitten (ReplyCutOff), ein Stream ist mittendrin abgebrochen (StreamBroken), oder ein Modellfehler war keinen erneuten Versuch wert oder ist auch nach den erneuten Versuchen voncall_modelgeblieben (openai.APIError, was auch einen nicht erreichbaren Dienst abdeckt).3, das Budget ist aufgebraucht.
BudgetExceeded, aus jedem Aufruf des Laufs, den erneuten Versuch vonaskeingeschlossen. Das ist das eigene Limit der Person, mit--budgetgesetzt, also bekommt es einen eigenen Code: Ein Skript, das den Lernassistenten startet, kann „gib ihm mehr Budget“ von „es ist fehlgeschlagen“ unterscheiden.4, die Notiz existiert nicht.
FileNotFoundErrorausquiz_command. Die Person hat sich bei einer ID vertippt.2, die Kommandozeile war falsch. Darum kümmert sich
argparse, bevor dein Code läuft, wie Lektion 1 gezeigt hat.
Alles andere, etwa ein TypeError oder ein KeyError, ist ein Bug im Programm. Er wird nicht abgefangen, also gibt Python seinen Traceback aus, und genau das willst du, wenn das Programm selbst falsch ist.
Das Bild ordnet jedes Ergebnis ein. Die Kommandozeile wird zuerst geprüft, also erreicht ein Bedienungsfehler run_command nie. Danach fängt jede except-Klausel ihre Art von Fehler ab und gibt ihr einen Code, und alles, was keine davon nennt, endet in einem Traceback.

error_line
Die Person sieht eine Zeile auf der Standardfehlerausgabe: Error: und eine kurze Beschreibung. Bei den meisten Fehlern ist die Beschreibung die erste Zeile von str(error): The budget ran out before agent step 2., The reply was cut off at the max_tokens limit. oder der Text eines openai-Fehlers, der aus einer Zeile besteht. Hol sie dir mit str(error).split("\n")[0].
Ein ValidationError von pydantic ist anders. Die erste Zeile seines Texts ist nur eine Überschrift, etwa 1 validation error for CitedAnswer, die nichts darüber sagt, was falsch war. error_lines(error) aus Kapitel 4 liefert eine kurze Zeile pro Problem, also gibt error_line bei einem ValidationError die erste davon zurück, etwa (whole reply): Invalid JSON: expected ident at line 1 column 2.
run_command
run_command(args, *, client, budget, sleep, stdin) führt einen Befehl aus und gibt seinen Exit-Code zurück:
try:
if args.command == "ask":
print(ask_command(args.question, client=client, budget=budget, sleep=sleep))
...
return 0
except BudgetExceeded as error:
print(f"Error: {error_line(error)}", file=sys.stderr)
return 3
Prüfe innerhalb von try args.command und rufe den passenden Befehl auf: Gib bei "ask" aus, was ask_command(args.question, ...) zurückgibt, gib bei "quiz" aus, was quiz_command(args.note_id, args.count, ...) zurückgibt, und rufe bei "chat" chat_command(..., stdin=stdin) auf, das laufend ausgibt. Übergib jedem client, budget und sleep und gib dann 0 zurück.
Dann eine except-Klausel pro Code, in dieser Reihenfolge, die jeweils f"Error: {error_line(error)}" mit file=sys.stderr ausgibt und ihren Code zurückgibt: BudgetExceeded gibt 3 zurück, FileNotFoundError gibt 4 zurück und (ValueError, ReplyCutOff, StreamBroken, openai.APIError) gibt 1 zurück. Bei einem Fehler geht nichts auf die Standardausgabe: Die Befehle geben ihren Text nur zurück, wenn sie erfolgreich sind, also ist das print nie gelaufen. Bei chat steht alles, was vor einem Abbruch gestreamt wurde, schon auf dem Bildschirm und bleibt dort.
print(..., file=sys.stderr) schlägt sys.stderr erst beim Ausführen nach. Wenn eine Prüfung die Standardfehlerausgabe abfängt, landet deine Zeile also in dem, was sie abfängt.
main
main(argv=None, *, client=None, notes_dir=NOTES_DIR, stdin=None, sleep=time.sleep):
args = build_parser().parse_args(argv). Mitargv=Noneliestargparsedie echte Kommandozeile. Ein Bedienungsfehler verlässt das Programm über das eigeneSystemExit(2)vonargparsemit dessen Usage- und Fehlerzeilen, wie in Python in der Praxis; fang ihn nicht ab.use_settings(notes_dir), damit die Kursmodule das Modell und den Notizordner dieses Programms verwenden.Wenn
clientgleichNoneist,client = build_client(). WennstdingleichNoneist,stdin = sys.stdin.budget = {"limit": args.budget, "used": 0}. Das ist das eine Budget des Laufs: Die Schritte des Agenten, der erneute Versuch vonask, ein Quiz und sein erneuter Versuch und jede Runde eines Chats zehren alle von diesem Dictionary.Gib
run_command(args, client=client, budget=budget, sleep=sleep, stdin=stdin)zurück.
main nimmt client, notes_dir, stdin und sleep, damit Tests und Prüfungen das ganze Programm mit einem Fake-Client, einem eigenen Notizordner, getippter Eingabe und ohne Warten ausführen können. Die Ausgabestreams nimmt es nicht: Die Befehle geben aus, und eine gestreamte Antwort wird Stück für Stück innerhalb von chat_turn ausgegeben. Tests fangen deshalb ab, was ausgegeben wird, mit contextlib.redirect_stdout und redirect_stderr, wie es die Prüfungen in Python in der Praxis getan haben.
Ersetze zum Schluss den Kommentar am Ende der Datei durch den Guard:
if __name__ == "__main__":
raise SystemExit(main())
SystemExit(code) beendet das Programm mit diesem Exit-Code, sodass das, was main zurückgibt, zum Exit-Code des Programms wird. Beim Importieren der Datei läuft nichts, und so verwenden stages.py und die Prüfungen sie.
Ausführen
Wenn alles geschrieben ist, führe python stages.py aus. Der Block von Lektion 6 ruft main einmal für jeden Exit-Code auf. Jeder Aufruf gibt die Argumentliste und dann den Exit-Code aus; dazwischen steht, was das Programm geschrieben hat, Standardfehlerausgabe und Standardausgabe auf demselben Bildschirm:
Lesson 6: main and its exit codes
--- main(['ask', 'How do I make an independent copy of a list?'])
Use scores.copy() or list(scores). Both build a new list, so a change made through one name no longer shows through the other.
Sources: 03-lists#4
exit code 0
--- main(['--budget', '1000', 'ask', 'How do I make an independent copy of a list?'])
Error: The budget ran out before agent step 2.
exit code 3
--- main(['quiz', '99-magic'])
Error: There is no note called 99-magic.
exit code 4
--- main(['quiz', '03-lists', '--count', '9'])
usage: study_assistant.py quiz [-h] [--count N] NOTE_ID
study_assistant.py quiz: error: argument --count: must be a whole number from 1 to 5
exit code 2
Under the tool-loop scenario:
--- main(['ask', 'How do I make an independent copy of a list?'])
Error: The agent stopped without an answer (stuck).
exit code 1
Under the broken-stream scenario:
--- main(['chat'])
A list is an ordered collection that can hold
Error: The stream stopped before the reply was complete.
exit code 1
Under the rate-limit:2 scenario:
--- main(['ask', 'How do I make an independent copy of a list?'])
(waiting 1.0 s)
(waiting 1.0 s)
Use scores.copy() or list(scores). Both build a new list, so a change made through one name no longer shows through the other.
Sources: 03-lists#4
exit code 0
Mit --budget 1000 lag die Schätzung für Schritt 1 bei 146 + 800 = 946 Tokens, was gepasst hat. Der erste Schritt hat 159 verbraucht, sodass 841 übrig blieben, und die Anfrage von Schritt 2 enthielt zusätzlich das Suchergebnis mit 763 Zeichen, also lag ihre Schätzung bei 1136.75, was nicht gepasst hat. Unter tool-loop bittet das Modell erneut um dieselbe Suche, und die Schleifenerkennung aus Kapitel 7 stoppt den Agenten. Unter broken-stream hat der Chat den Anfang einer Antwort ausgegeben und ist dann gescheitert. Unter rate-limit:2 übergibt stages.py das sleep_and_say aus Kapitel 9, das sagt, wie lange es wartet, und call_model hat zwei 429-Antworten abgewartet; vorher setzt stages.py den Zähler des geskripteten Modells zurück. Danach geht stages.py weiter zum Eval-Bericht von Lektion 8.
Wenn llm-api nicht erreichbar ist, hält python stages.py beim Block von Lektion 2 mit Could not reach llm-api an, weil dieser Block run_agent direkt aufruft. main selbst fängt das ab: Im python study_assistant.py ask "..." Error: Connection error. aus und endet mit Exit-Code 1, wie bei jedem anderen Modellfehler.
Sobald der Guard da ist, probiere die Befehle im Terminal aus. echo $? zeigt den Exit-Code des vorherigen Befehls:
$ python study_assistant.py --budget 1000 ask "How do I make an independent copy of a list?"
Error: The budget ran out before agent step 2.
$ echo $?
3
$ python study_assistant.py quiz 99-magic
Error: There is no note called 99-magic.
$ echo $?
4
Warum bekommt BudgetExceeded Exit-Code 3 statt der 1, die jeder andere fehlgeschlagene Lauf bekommt?
Ein Fehler in ask_command löst einen KeyError aus. Was macht das Programm?
Aufgabe
Schreib in study_assistant.py drei Funktionen und schließe die Datei mit dem Guard ab.
error_line(error): Gib bei einem ValidationError die erste Zeile von error_lines(error) zurück; bei jedem anderen Fehler die erste Zeile von str(error).
run_command(args, *, client, budget, sleep, stdin): Führe innerhalb von try den Befehl aus, den args.command nennt. Gib bei "ask" aus, was ask_command(args.question, ...) zurückgibt; gib bei "quiz" aus, was quiz_command(args.note_id, args.count, ...) zurückgibt; rufe bei "chat" chat_command(..., stdin=stdin) auf. Übergib jedem client, budget und sleep. Gib 0 zurück. Fang dann in dieser Reihenfolge ab und gib dabei jedes Mal f"Error: {error_line(error)}" auf sys.stderr aus:
BudgetExceeded: Gib3zurück;FileNotFoundError: Gib4zurück;ValueError,ReplyCutOff,StreamBrokenoderopenai.APIError: Gib1zurück.
Fang sonst nichts ab.
main(argv=None, *, client=None, notes_dir=NOTES_DIR, stdin=None, sleep=time.sleep): args = build_parser().parse_args(argv), dann use_settings(notes_dir). Verwende build_client(), wenn client gleich None ist, und sys.stdin, wenn stdin gleich None ist. Erzeuge ein einziges budget = {"limit": args.budget, "used": 0} und gib run_command(args, client=client, budget=budget, sleep=sleep, stdin=stdin) zurück.
Ersetze den letzten Kommentar durch if __name__ == "__main__": und darunter raise SystemExit(main()). Führe python stages.py aus, um jeden Exit-Code zu sehen, probiere das Ergebnis selbst in der Shell aus und prüfe dann deine Arbeit.