`convert.py` ドキュメント

概要

convert.py は、各種ファイル形式の変換処理を統一的に管理・実行するためのユーティリティスクリプトです。Word、Excel、PowerPoint、Markdown、画像、PDF などの様々なファイルを、指定した目的の形式に変換します。

ディレクトリ内の再帰的な一括変換や、単一ファイルの変換をサポートしており、ファイルの更新日時を比較して必要なファイルのみを変換する機能（スキップ機能）も備えています。

詳細説明

本スクリプトは、変換対象となるファイルの入力拡張子と出力拡張子の組み合わせに基づいて、適切な変換モジュールを動的に選択する「レジストリシステム」を採用しています。実行時に利用可能なモジュールのみを安全にインポートするため、一部の依存ライブラリが不足していても、インストール済みの変換機能だけで動作を継続できるよう設計されています。

主な機能は以下の通りです。

再帰的な一括変換 指定したルートディレクトリから下層ディレクトリを再帰的に走査し、条件に合致するファイルを一括変換します。
単一ファイル変換 特定のファイルのみを指定して変換を実行できます。
差分更新 変換先のファイルが既に存在し、かつ入力ファイルよりも新しい更新日時を持つ場合、変換をスキップして処理時間を短縮します。
一時ファイルのスキップ Excelの作業中一時ファイル（~$ で始まるファイルなど）を自動的にスキップします。
出力モードの分岐 単一のファイルを出力するモードと、画像群のようにディレクトリを生成して出力するモードをサポートします。

非標準ライブラリ

本スクリプトは、変換処理を外部のモジュールに委譲しています。インポート文から確認できる主な非標準ライブラリ（または連携スクリプト）は以下の通りです。実行する変換の組み合わせに応じて、該当するモジュールが必要となります。

docx2pdf
xlsx2pdf
pptx2pdf
pptx2pdf_with_notes_importable
html2pdf_importable
md2pdf_importable, md2pdf
txt2pdf_importable
img2pdf_importable
docx2md
pptx2md2
pdf2md
pdf2pptx
pptx2img
docx2img
pdf2img
ipynb2md
pandoc

入出力仕様

入力仕様

入力元として、ディレクトリパスまたは単一ファイルのパスを指定します。対象となる入力ファイルの拡張子は、利用可能なモジュールに依存しますが、コード上では以下のような拡張子が登録対象として定義されています。

ドキュメント：.docx, .xlsx, .pptx, .pdf, .html, .htm, .md, .txt, .ipynb, .json
画像：.png, .jpg, .jpeg, .bmp, .tif, .tiff, .webp

出力仕様

出力ファイルの拡張子（例：.pdf, .md, .pptx, .docx, .html, .png）を指定することで、対応するフォーマットへ変換されます。

ファイル出力モード 入力ファイルと同じディレクトリに、指定した出力拡張子を持つファイルが生成されます。
ディレクトリ出力モード PDFやドキュメントをページごとに複数の画像（例：.png）へ分割出力するような場合、入力ファイル名に拡張子と s を付与したディレクトリ（例：.pngs）が生成され、その内部にファイルが出力されます。

主要なCLIオプション

root_dir 走査を開始するルートディレクトリを指定します（デフォルト: .）。
output_ext 出力先の拡張子を指定します（デフォルト: .pdf）。
--infile 指定した場合、再帰的なディレクトリ走査をスキップし、指定された単一ファイルのみを変換します。
--max_level ディレクトリを走査する際の最大再帰深度を指定します（デフォルト: -1 で無制限）。
--target セミコロン（;）区切りで変換対象のファイル名パターンを指定できます（例: --target="*.pptx;*.docx"）。
--update 1 の場合、出力先ファイルが存在し、入力ファイルより新しい場合は変換をスキップします。0 に設定するとスキップしません（デフォルト: 1）。
--overwrite 1 の場合、更新日時に関わらず常に上書き変換を行います（デフォルト: 0）。
--list 現在利用可能な変換器の一覧と、利用できないモジュールを標準出力に表示して終了します。
Pandoc連携オプション --pandoc_path, --template_docx, --template_pptx, --css, --toc, --mathml, --no_yaml, --verbose, --smart_conversion
PDFからPPTXへの変換オプション --pdf-dpi, --pdf-slide-size, --pdf-margin, --pdf-split-vertical-half

実行例

利用可能な変換器（コンバータ）の一覧を表示する

python convert.py --list

カレントディレクトリとその下層にあるすべてのファイルを PDF (.pdf) に変換する

python convert.py . .pdf

特定のディレクトリ（./docs）内にある .md ファイルのみを抽出し、Wordファイル (.docx) に変換する

python convert.py ./docs .docx --target="*.md"

単一の PowerPoint ファイルをMarkdownファイル (.md) に変換する

python convert.py --infile="presentation.pptx" .md

ファイルの更新日時に関わらず、指定ディレクトリ内のファイルを強制的に上書き変換する

python convert.py ./report .pdf --overwrite=1

PDF ファイルを PowerPoint ファイル (.pptx) に変換し、余白などのオプションを指定する

python convert.py --infile="document.pdf" .pptx --pdf-slide-size="standard" --pdf-margin=0.5

convert.py ドキュメント

概要