> [!NOTE] > Diese Dokumentation kann KI-generierte Inhalte enthalten. Obwohl wir auf Genauigkeit achten, kann es zu Ungenauigkeiten kommen. Bitte melden Sie etwaige Probleme über: > > - [GitHub Issues](https://github.com/PDFMathTranslate-next/PDFMathTranslate-next/issues) > - Gemeinschaftsbeiträge (PRs sind willkommen!) ## Python API: do_translate_async_stream ### Übersicht - do_translate_async_stream ist der Low-Level-Async-Einstiegspunkt, der eine einzelne PDF übersetzt und einen Stream von Ereignissen (Fortschritt/Fehler/Fertigstellung) liefert. - Es eignet sich zum Erstellen Ihrer eigenen Benutzeroberfläche oder Kommandozeile, bei der Sie Echtzeit-Fortschritt und volle Kontrolle über die Ergebnisse wünschen. - Es akzeptiert ein validiertes SettingsModel und einen Dateipfad und gibt einen asynchronen Generator von Dict-Ereignissen zurück. ### Signatur - Import: `from pdf2zh_next.high_level import do_translate_async_stream` - Aufruf: `async for event in do_translate_async_stream(settings, file): ...` - Parameter: - settings: SettingsModel. Muss gültig sein; die Funktion ruft `settings.validate_settings()` auf. - file: str | pathlib.Path. Die einzelne zu übersetzende PDF. Muss existieren. Hinweis: - `settings.basic.input_files` wird von dieser Funktion ignoriert; nur die angegebene `file` wird übersetzt. - Wenn `settings.basic.debug` True ist, läuft die Übersetzung im Hauptprozess; andernfalls läuft sie in einem Unterprozess. Das Ereignisschema ist für beide identisch. ### Event-Stream-Vertrag Der asynchrone Generator liefert JSON-ähnliche Dict-Ereignisse mit den folgenden Typen: - Stufenzusammenfassungsereignis: `stage_summary` (optional, kann zuerst erscheinen) - Felder - `type`: "stage_summary" - `stages`: Liste von Objekten `{ "name": str, "percent": float }`, die die geschätzte Arbeitsverteilung beschreiben - `part_index`: kann für dieses Zusammenfassungsereignis 0 sein - `total_parts`: Gesamtzahl der Teile (>= 1) - Fortschrittsereignisse: `progress_start`, `progress_update`, `progress_end` - Gemeinsame Felder - `type`: einer der oben genannten - `stage`: menschenlesbarer Stufenname (z. B. "PDF parsen und Zwischendarstellung erstellen", "Absätze übersetzen", "PDF speichern") - `stage_progress`: Float in [0, 100], der den Fortschritt innerhalb der aktuellen Stufe anzeigt - `overall_progress`: Float in [0, 100], der den Gesamtfortschritt anzeigt - `part_index`: aktueller Teilindex (typischerweise 1-basiert für Fortschrittsereignisse) - `total_parts`: Gesamtzahl der Teile (>= 1). Große Dokumente können automatisch aufgeteilt werden. - `stage_current`: aktueller Schritt innerhalb der Stufe - `stage_total`: Gesamtschritte innerhalb der Stufe - Abschlussereignis: `finish` - Felder - `type`: "finish" - `translate_result`: ein **Objekt**, das die endgültigen Ausgaben bereitstellt (HINWEIS: kein Wörterbuch, sondern eine Klasseninstanz) - `original_pdf_path`: Pfad zur Eingabe-PDF - `mono_pdf_path`: Pfad zur einsprachig übersetzten PDF (oder None) - `dual_pdf_path`: Pfad zur zweisprachig übersetzten PDF (oder None) - `no_watermark_mono_pdf_path`: Pfad zur einsprachigen Ausgabe ohne Wasserzeichen (falls erstellt), sonst None - `no_watermark_dual_pdf_path`: Pfad zur zweisprachigen Ausgabe ohne Wasserzeichen (falls erstellt), sonst None - `auto_extracted_glossary_path`: Pfad zur automatisch extrahierten Glossar-CSV (oder None) - `total_seconds`: verstrichene Sekunden (Float) - `peak_memory_usage`: ungefährer Spitzenspeicherverbrauch während der Übersetzung (Float; implementierungsabhängige Einheiten) - Fehlerereignis: `error` - Felder - `type`: "error" - `error`: menschenlesbare Fehlermeldung - `error_type`: einer von `BabeldocError`, `SubprocessError`, `IPCError`, `SubprocessCrashError`, etc. - `details`: optionale Details (z. B. ursprünglicher Fehler oder Traceback) Wichtiges Verhalten: - Ein optionales `stage_summary` kann ausgegeben werden, bevor der Fortschritt beginnt. - Bei bestimmten Fehlern wird der Generator zuerst ein `error`-Ereignis liefern und dann eine Ausnahme auslösen, die von `TranslationError` abgeleitet ist. Sie sollten sowohl auf Fehlerereignisse prüfen als auch darauf vorbereitet sein, Ausnahmen abzufangen. - `progress_update`-Ereignisse können sich mit identischen Werten wiederholen; Verbraucher sollten bei Bedarf entprellen. - Beenden Sie den Verbrauch des Streams, wenn Sie ein `finish`-Ereignis erhalten. ### Minimales Verwendungsbeispiel (Async) ```python import asyncio from pathlib import Path from pdf2zh_next.high_level import do_translate_async_stream # Assume you already have a valid SettingsModel instance named `settings` # and a PDF file path async def translate_one(settings, pdf_path: str | Path): try: async for event in do_translate_async_stream(settings, pdf_path): etype = event.get("type") if etype == "stage_summary": # Optional pre-flight summary of stages stages = event.get("stages", []) print("Stage summary:", ", ".join(f"{s['name']}:{s['percent']:.2f}" for s in stages)) elif etype in {"progress_start", "progress_update", "progress_end"}: stage = event.get("stage") stage_prog = event.get("stage_progress") # 0..100 overall = event.get("overall_progress") # 0..100 part_i = event.get("part_index") part_n = event.get("total_parts") print(f"[{etype}] {stage} | stage {stage_prog:.1f}% | overall {overall:.1f}% (part {part_i}/{part_n})") elif etype == "error": # You will also get a raised exception after this yield print("[error]", event.get("error"), event.get("error_type")) elif etype == "finish": result = event["translate_result"] print("Done in", getattr(result, "total_seconds", None), "s") print("Mono:", getattr(result, "mono_pdf_path", None)) print("Dual:", getattr(result, "dual_pdf_path", None)) print("No-watermark Mono:", getattr(result, "no_watermark_mono_pdf_path", None)) print("No-watermark Dual:", getattr(result, "no_watermark_dual_pdf_path", None)) print("Glossary:", getattr(result, "auto_extracted_glossary_path", None)) print("Peak memory:", getattr(result, "peak_memory_usage", None)) break except Exception as exc: # Catch exceptions raised by the stream after an error event print("Translation failed:", exc) # asyncio.run(translate_one(settings, "/path/to/file.pdf")) ``` ### Stornierung Sie können die Aufgabe abbrechen, die den Stream verbraucht. Die Stornierung wird an den zugrunde liegenden Übersetzungsprozess weitergegeben. ```python import asyncio from pdf2zh_next.high_level import do_translate_async_stream async def cancellable(settings, pdf): task = asyncio.create_task(_consume(settings, pdf)) await asyncio.sleep(1.0) # let it start task.cancel() try: await task except asyncio.CancelledError: print("Cancelled") async def _consume(settings, pdf): async for event in do_translate_async_stream(settings, pdf): if event["type"] == "finish": break ``` ### Beispielhafte Ereignisformen Stadiumszusammenfassungsereignis (Beispiel): ```json { "type": "stage_summary", "stages": [ {"name": "Parse PDF and Create Intermediate Representation", "percent": 0.1086}, {"name": "DetectScannedFile", "percent": 0.0188}, {"name": "Parse Page Layout", "percent": 0.1079} // ... more stages ... ], "part_index": 0, "total_parts": 1 } ``` Progress-Ereignis (Beispiel): ```json { "type": "progress_update", "stage": "Translate Paragraphs", "stage_progress": 2.04, "stage_current": 1, "stage_total": 49, "overall_progress": 53.44, "part_index": 1, "total_parts": 1 } ``` Finish-Ereignis (Beispiel): ```json { "type": "finish", "translate_result": { "original_pdf_path": "pdf2zh_files//table.pdf", "mono_pdf_path": "pdf2zh_files//table.zh-CN.mono.pdf", "dual_pdf_path": "pdf2zh_files//table.zh-CN.dual.pdf", "no_watermark_mono_pdf_path": "pdf2zh_files//table.no_watermark.zh-CN.mono.pdf", "no_watermark_dual_pdf_path": "pdf2zh_files//table.no_watermark.zh-CN.dual.pdf", "auto_extracted_glossary_path": "pdf2zh_files//table.zh-CN.glossary.csv", "total_seconds": 42.83, "peak_memory_usage": 4651.55 } } ``` Fehlerereignis (Beispiel): ```json { "type": "error", "error": "Babeldoc translation error: ", "error_type": "BabeldocError", "details": "" } ``` ### Hinweise & Best Practices - Sowohl Fehlerereignisse als auch Ausnahmen vom Generator müssen immer behandelt werden. - Unterbrechen Sie die Schleife bei `finish`, um unnötige Arbeit zu vermeiden. - Stellen Sie sicher, dass die `file` existiert und `settings.validate_settings()` erfolgreich ist, bevor Sie die Funktion aufrufen. - Große Dokumente können aufgeteilt werden; verwenden Sie `part_index/total_parts` und `overall_progress`, um Ihre Benutzeroberfläche zu steuern. - Entprellen Sie `progress_update`, wenn Ihre Benutzeroberfläche empfindlich auf wiederholte, identische Aktualisierungen reagiert. - `report_interval` (SettingsModel): Steuert nur die Ausgaberate von `progress_update`-Ereignissen. Es beeinflusst nicht `stage_summary`, `progress_start`, `progress_end` oder `finish`. Der Standardwert ist 0,1s und das zulässige Minimum ist 0,05s. Gemäß der Fortschrittsmonitor-Logik werden bei `stage_total <= 3` Aktualisierungen nicht durch `report_interval` gedrosselt.
Ein Teil des Inhalts dieser Seite wurde von GPT übersetzt und kann Fehler enthalten.