From 6f12f3b3aa1a252d902869138819f8c3bdaeeb73 Mon Sep 17 00:00:00 2001 From: Floke Date: Wed, 31 Dec 2025 14:50:49 +0000 Subject: [PATCH] docs: Enhance migration guide with detailed Python syntax troubleshooting for f-strings and persistent SyntaxErrors --- BUILDER_APPS_MIGRATION.md | 39 ++++++++++++++++++++++++++++----------- 1 file changed, 28 insertions(+), 11 deletions(-) diff --git a/BUILDER_APPS_MIGRATION.md b/BUILDER_APPS_MIGRATION.md index f2ba044d..72500b03 100644 --- a/BUILDER_APPS_MIGRATION.md +++ b/BUILDER_APPS_MIGRATION.md @@ -51,22 +51,39 @@ Das Projekt nutzt ein geteiltes `helpers.py`, das auf der alten OpenAI Python Li openai==0.28.1 # weitere deps... ### 1.5 Python Syntax & F-Strings -Multi-Line f-Strings sind in Docker-Umgebungen fehleranfällig. -* **Vermeide:** Ternary Operators (`... if x else ...`) innerhalb von Multi-Line f-Strings. Dies führt oft zu `SyntaxError: invalid decimal literal`. -* **Best Practice:** Nutze explizite `if/else` Blöcke zur Definition des Prompts. -* **Vermeide:** Verschachtelte JSON-Dumps (`{...}`) direkt im f-String. Nutze vorher definierte Variablen. +Multi-Line f-Strings sind in Docker-Umgebungen fehleranfällig, besonders wenn sie JSON-Strukturen oder komplexe Texte enthalten. + +* **Wiederkehrender Fehler: `SyntaxError: invalid decimal literal` (oft bei `2. Derive` oder ähnlichen Zeilen in Prompts)** + * **Symptom:** Python meldet einen Syntaxfehler innerhalb eines scheinbar korrekten Multi-Line-Strings (`f"""..."""`). + * **Ursachen:** + 1. **Falsches Escaping von `{}`:** Wenn geschweifte Klammern (`{}`) als Teil eines JSON-Beispiels in einem f-String verwendet werden, müssen sie oft **doppelt** escaped werden (`{{` und `}}`). Wenn es aber kein f-String ist oder die Klammern nicht zur Variableneinfügung dienen, dürfen sie nicht escaped werden (ein `dict()`-Literal ist `{}`). Das ist eine häufige Quelle für Verwirrung. + 2. **Fehlende/Falsche String-Delimiter:** Der Multi-Line-String wurde nicht korrekt mit `"""` geöffnet oder geschlossen, oder eine Zeile davor/danach bricht die String-Definition. + 3. **Unsichtbare Zeichen:** Manchmal können unsichtbare Unicode-Zeichen (z.B. Zero-Width Space) den Parser stören. + 4. **Ternary Operators in f-Strings:** Das ist ein bekannter Anti-Pattern (siehe unten). + +* **Best Practice zur Fehlervermeidung bei Prompts:** + 1. **Nutze explizite `if/else` Blöcke** zur Definition des Prompts, anstatt Ternary Operators (`... if x else ...`) innerhalb von Multi-Line f-Strings. Dies ist die **sicherste Methode**. + 2. **Definiere komplexe JSON-Strukturen** oder sehr lange Textblöcke **vorher als separate Variablen** und füge sie dann in den f-String ein (siehe Beispiel unten). + 3. **Prüfe akribisch die `"""` Delimiter** und die Einrückung des Multi-Line-Strings. + ```python - # Schlecht: - prompt = f"""Daten: {json.dumps(data)}""" if lang=='de' else f"""Data: ...""" + # Beispiel: So sollte es NICHT gemacht werden (fehleranfällig) + # prompt = f"""Daten: {json.dumps(data)}""" if lang=='de' else f"""Data: ...""" - # Gut: - json_data = json.dumps(data) + # Beispiel: So ist es robust (bevorzugte Methode) + json_data_for_prompt = json.dumps(data) # JSON vorformatieren if lang == 'de': - prompt = f"""Daten: {json_data}""" + prompt_template = f""" + Dies ist ein deutscher Prompt mit Daten: {json_data_for_prompt} + """ else: - prompt = f"""Data: {json_data}""" + prompt_template = f""" + This is an English prompt with data: {json_data_for_prompt} + """ + prompt = sys_instr + "\n\n" + prompt_template # System-Instruktion voranstellen ``` -* **Signaturen prüfen:** Shared Libraries (`helpers.py`) haben oft ältere Signaturen. + +* **Signaturen prüfen:** Shared Libraries (`helpers.py`) haben oft ältere Signaturen. Immer die tatsächliche Definition prüfen! * Beispiel: `call_openai_chat` unterstützt oft kein `system_message` Argument. Stattdessen Prompt manuell zusammenbauen (`sys_instr + "\n\n" + prompt`). ---