はじめに
GordonKit ドキュメントコンバーター
DOCX をはじめとするドキュメント形式を、Python ライブラリ、CLI、HTTP API から PDF、HTML、Markdown、画像などへ変換します。
このプロジェクトについて
この GordonKit オープンソースプロジェクトは、Microsoft Word、LibreOffice、Gotenberg、Pandoc を組み合わせてドキュメントを組版します。エンジンの選択、検証、フォールバックの報告、変換結果を明示的で診断しやすい状態に保ちます。
利用方法
ワークフローに合った利用方法を選べます。どの方法も同じ application service を経由し、構造化された結果、エンジンポリシー、診断情報を保持します。
Python ライブラリ
型付きの公開契約を使って、単一変換、独立したバッチ処理、エンジン調査、service injection を実行します。
from gordon_doc_converter import convertCLI
変換、比較、エンジン確認を実行し、スクリプトや CI ワークフロー向けに安定した JSON 結果を出力します。
gordon-doc convert report.docx --to pdfHTTP API
FastAPI extra をインストールし、認証 hook、レート制限、上限付き並行実行を備えたプライベート配備を構築します。
POST /conversions対応フォーマット：ローカルインストール
何を変換できるかは、どのインターフェースから呼び出すかではなく、その配備が備えるエンジンで決まります。この表は、PATH 上に LibreOffice、Pandoc、wkhtmltopdf があり、ページ画像用に images extra が導入されていること、Word COM ポリシーについては Word を備えた対話的な Windows デスクトップであることを前提とします。
| 入力 | DOCX | ODT | HTML | Markdown | YAML | JSON | ページ画像 | |
|---|---|---|---|---|---|---|---|---|
| DOCX | 該当なし | Auto | LO | ✓ | ✓ | ✓ | ✓ | |
| R | 該当なし | R | ✓ | ✓ | ✓ | ✓ | ✓ | |
| ODT | LO | LO | 該当なし | ✓ | ✓ | ✓ | ✓ | |
| HTML | P | W | LO | 該当なし | ✓ | ✓ | ✓ | |
| Markdown | P | W | LO | ✓ | 該当なし | ✓ | ✓ |
対応フォーマット：コンテナイメージ
公式イメージには libreoffice-writer と api、gotenberg の extra が入るため、wkhtmltopdf または Pandoc を優先する経路はすべて LibreOffice が代わりに組版し、置き換えたエンジンを示す ENGINE_FALLBACK warning を返します。イメージが提供する HTTP API は DOCX から PDF への変換のみで、表のそれ以外の経路は cli Compose profile から利用します。
| 入力 | DOCX | ODT | HTML | Markdown | YAML | JSON | ページ画像 | |
|---|---|---|---|---|---|---|---|---|
| DOCX | 該当なし | Auto | LO | ✓ | ✓ | ✓ | ✓ | — |
| R! | 該当なし | R | ✓ | ✓ | ✓ | ✓ | — | |
| ODT | LO | LO | 該当なし | ✓ | ✓ | ✓ | ✓ | — |
| HTML | LO! | LO! | LO | 該当なし | ✓ | ✓ | ✓ | — |
| Markdown | LO! | LO! | LO | ✓ | 該当なし | ✓ | ✓ | — |
インストール
まずコアパッケージをインストールし、配備に必要な任意機能だけを追加します。
uv add gordon-doc-converter
uv add 'gordon-doc-converter[images,gotenberg]'最初の変換
ソースパスからリクエストを作成します。サービスはポリシーが許可するエンジンを選択し、一時出力を検証し、検証に成功した場合のみ結果を公開します。
from pathlib import Path
from gordon_doc_converter import ConversionRequest, convert
request = ConversionRequest.from_source(Path("report.docx"))
result = convert(request)
print(result.artifacts[0].path)