はじめに
Python ドキュメント変換ライブラリ
エンジン非依存のリクエスト、結果、バッチ、診断を使って、型付きの DOCX、PDF、HTML、Markdown、YAML、JSON、画像変換を Python アプリケーションに追加します。
ライブラリ概要
公開 API はエンジン非依存の型付きモデルを使います。統合の要件を満たす最小の入口を選んでください。
| 入口 | 用途 |
|---|---|
| ConversionRequest.from_source | パスからソース形式を推定して検証する |
| convert(request) | 1 件の変換を実行し 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)オプションと strict ポリシー
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() でログや API 向けの安定した JSON 互換のプリミティブにシリアライズできます。ドキュメントの内容や機微なパスは記録しないでください。
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]