快速開始
Python 文件轉換函式庫
在 Python 應用程式加入具型別的 DOCX、PDF、HTML、Markdown、YAML、JSON 與圖片轉換，並使用引擎中立的請求、結果、批次及診斷。
函式庫總覽
公開 API 使用引擎中立的具型別模型。請依整合需求選擇最精簡的入口。
| 入口 | 適用情境 |
|---|---|
| ConversionRequest.from_source | 由路徑推斷並驗證來源格式 |
| convert(request) | 執行單一轉換並取得 ConversionResult |
| DocumentConversionService | 注入引擎，或直接使用 service 方法 |
| convert_batch(requests) | 執行依序且失敗隔離的轉換 |
| probe_engines() | 探索 renderer 可用性與註解能力 |
| result.to_dict() | 產生穩定、JSON 相容的結果資料 |
單檔轉換
ConversionRequest.from_source 會驗證允許的副檔名並推斷來源格式。convert 對一般轉換失敗會回傳 ConversionResult，而非直接拋出例外，因此讀取 artifacts 前請先檢查 success 與 error。ConversionError 用於無效請求及相關契約錯誤。
from pathlib import Path
from gordon_doc_converter import ConversionRequest, convert
result = convert(ConversionRequest.from_source(Path('report.docx')))
if not result.success:
raise RuntimeError(result.error.message if result.error else 'conversion failed')
print(result.artifacts[0].path)選項與嚴格政策
使用 ConversionOptions 設定輸出路徑、覆寫行為、逾時、部署模式、明確引擎、註解處理、metadata detail 與影像設定。EngineName 是嚴格選擇：指定的引擎不可用時，會得到可診斷的失敗，而不是靜默改用其他引擎。若轉換路徑支援，ArtifactType 可要求 PDF、DOCX、ODT、HTML、Markdown、YAML、JSON 或頁面影像。
from pathlib import Path
from gordon_doc_converter import (
ArtifactType, ConversionOptions, ConversionRequest, convert,
)
request = ConversionRequest.from_source(
Path('report.docx'),
artifacts=(ArtifactType.YAML, ArtifactType.JSON),
options=ConversionOptions(output_path=Path('report')),
)
result = convert(request)批次、探測與結果處理
DocumentConversionService 支援引擎的 dependency injection 與依環境執行的 orchestration。convert_batch 會依序處理請求並隔離失敗。probe_engines 回傳 EngineProbeResult，包含可用性、版本、支援的修訂模式與註解模式。結果可透過 to_dict() 序列化為穩定、JSON 相容的基本型別，適合日誌或 API；請勿記錄文件內容或敏感路徑。
from gordon_doc_converter import DocumentConversionService
service = DocumentConversionService()
for probe in service.probe_engines():
print(probe.engine, probe.available, probe.version)
results = service.convert_batch(requests)
payload = [result.to_dict() for result in results]