API

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
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)

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.

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):

{
  "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):

{
  "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):

{
  "type": "finish",
  "translate_result": {
    "original_pdf_path": "pdf2zh_files/<session>/table.pdf",
    "mono_pdf_path": "pdf2zh_files/<session>/table.zh-CN.mono.pdf",
    "dual_pdf_path": "pdf2zh_files/<session>/table.zh-CN.dual.pdf",
    "no_watermark_mono_pdf_path": "pdf2zh_files/<session>/table.no_watermark.zh-CN.mono.pdf",
    "no_watermark_dual_pdf_path": "pdf2zh_files/<session>/table.no_watermark.zh-CN.dual.pdf",
    "auto_extracted_glossary_path": "pdf2zh_files/<session>/table.zh-CN.glossary.csv",
    "total_seconds": 42.83,
    "peak_memory_usage": 4651.55
  }
}

Fehlerereignis (Beispiel):

{
  "type": "error",
  "error": "Babeldoc translation error: <message>",
  "error_type": "BabeldocError",
  "details": "<optional original error or traceback>"
}

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.

API