Floke/Brancheneinstufung2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Enhance migration guide with detailed Python syntax troubleshooting for f-strings and persistent SyntaxErrors

Browse Source
This commit is contained in:
Floke
2025-12-31 14:50:49 +00:00
parent 0ec88d5aba
commit 6f12f3b3aa
1 changed files with 28 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
BUILDER_APPS_MIGRATION.md
View File

@@ -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`).
---