convert プログラム仕様
ファイル変換ユーティリティモジュール。
このモジュールは、ファイルシステムを走査し、登録されたコンバータを使用して 指定されたファイルを別の形式に変換する機能を提供します。 Pandocなどの外部ツールや他のPythonライブラリと連携し、 様々なファイル形式間の変換をサポートします。
- class converter.convert.ConverterRegistry[ソース]
ベースクラス:
objectConverterSpecオブジェクトを管理するレジストリクラス。
利用可能な変換仕様を登録、取得、一覧表示し、モジュールのインポート中に発生したエラーも記録します。 これにより、プログラムは実行時に利用可能な変換を動的に認識できます。
- get(input_ext: str, output_ext: str) ConverterSpec | None[ソース]
指定された入力拡張子と出力拡張子に対応するConverterSpecを取得します。
拡張子は検索前に正規化されます。
- パラメータ:
- 戻り値:
対応するConverterSpecオブジェクト、または見つからない場合はNone。
- 戻り値の型:
Optional[ConverterSpec]
- list_output_exts()[ソース]
登録されているすべての出力拡張子の一覧を重複なくソートして返します。
- 戻り値:
利用可能な出力拡張子のソート済みリスト。
- 戻り値の型:
List[str]
- list_specs()[ソース]
登録されているすべてのConverterSpecオブジェクトのリストを返します。
- 戻り値:
登録されているConverterSpecオブジェクトのリスト。
- 戻り値の型:
List[ConverterSpec]
- print_available_converters()[ソース]
利用可能なコンバータと、インポートに失敗したモジュールをコンソールに表示します。
コンバータは出力拡張子、入力拡張子、出力モードの順でソートされて表示されます。 インポートエラーがある場合は、そのモジュール名とエラーメッセージも表示されます。
- register(spec: ConverterSpec)[ソース]
指定されたConverterSpecをレジストリに登録します。
入力拡張子と出力拡張子の組み合わせを一意のキーとして使用します。
- パラメータ:
spec (ConverterSpec) -- 登録するConverterSpecオブジェクト。
- class converter.convert.ConverterSpec(input_ext: str, output_ext: str, converter: ~typing.Callable[[...], ~typing.Any], description: str = '', ignore_temp_prefixes: ~typing.Tuple[str, ...] = (), output_mode: str = 'file', options: ~typing.Dict[str, ~typing.Any] = <factory>)[ソース]
ベースクラス:
objectファイル変換の具体的な仕様を定義するデータクラス。
入力ファイルの拡張子、出力ファイルの拡張子、変換を実行するCallableオブジェクト、 および変換に関する追加情報（説明、一時ファイル無視ルール、出力モードなど）を カプセル化します。
- パラメータ:
input_ext (str) -- 入力ファイルの拡張子（例: ".docx", "pptx"）。
output_ext (str) -- 出力ファイルの拡張子（例: ".pdf", ".md"）。
converter (Callable[..., Any]) -- 実際の変換処理を行うCallableオブジェクト。 通常は input_path, output_path, **kwargs を引数に取ります。
description (str) -- このコンバータの簡単な説明。デフォルトは空文字列。
ignore_temp_prefixes (Tuple[str, ...]) -- 変換をスキップすべき一時ファイル名の接頭辞のタプル。 例えば、Wordの一時ファイル"~$"など。
output_mode (str) -- 変換結果の出力モード。 OUTPUT_MODE_FILE (単一ファイル) または OUTPUT_MODE_DIR (ディレクトリ)。
options (Dict[str, Any]) -- 変換関数に渡される追加のキーワード引数を含む辞書。
- converter.convert.build_converter_kwargs(args, output_ext: str) Dict[str, Any][ソース]
コマンドライン引数からコンバータに渡すキーワード引数辞書を構築します。
特にPandoc関連のオプション（pandoc_path, template, css, toc, mathml, no_yaml, verbose, smart_conversion）を、 出力拡張子に基づいて適切に辞書に格納します。
- パラメータ:
args (argparse.Namespace) -- コマンドライン引数を保持するargparse.Namespaceオブジェクト。
output_ext (str) -- 目的の出力拡張子。
- 戻り値:
コンバータに渡すキーワード引数の辞書。
- 戻り値の型:
Dict[str, Any]
- converter.convert.build_output_path(input_path: str, output_ext: str, output_mode: str = 'file') str[ソース]
入力パスと出力拡張子、出力モードに基づいて出力ファイルのパスを構築します。
output_mode が OUTPUT_MODE_FILE の場合は、入力ファイル名のベースに出力拡張子を付けたパスを返します。 OUTPUT_MODE_DIR の場合は、出力拡張子の末尾に"s"を追加したディレクトリのようなパスを返します （例: ".pdf" -> ".pdfs"）。
- converter.convert.convert_file(input_path: str, output_ext: str, registry: ConverterRegistry, update: bool = True, overwrite: bool = False, converter_kwargs: Dict[str, Any] | None = None) bool[ソース]
単一のファイルを指定された出力形式に変換します。
入力パス、出力拡張子、レジストリに基づいて適切なコンバータを見つけ、 update または overwrite の設定に従って変換の要否を判断します。 一時ファイルと見なされるファイルはスキップされます。
- パラメータ:
input_path (str) -- 変換する入力ファイルのパス。
output_ext (str) -- 目的の出力拡張子（例: ".pdf", ".md"）。
registry (ConverterRegistry) -- 利用可能なコンバータを保持するConverterRegistryインスタンス。
update (bool) -- 出力ファイルが存在し、入力ファイルよりも新しい場合にスキップするかどうか。デフォルトはTrue。
overwrite (bool) -- 出力ファイルの存在やタイムスタンプに関わらず常に上書きするかどうか。デフォルトはFalse。
converter_kwargs (Optional[Dict[str, Any]]) -- 変換関数に渡す追加のキーワード引数の辞書。オプション。
- 戻り値:
変換が成功した場合はTrue、それ以外の場合はFalse。
- 戻り値の型:
- converter.convert.get_latest_mtime(path: str, output_mode: str) float | None[ソース]
指定されたパス（ファイルまたはディレクトリ）の最終更新時刻を取得します。
OUTPUT_MODE_FILE の場合、ファイルの最終更新時刻を返します。 OUTPUT_MODE_DIR の場合、指定されたディレクトリとその中のすべてのファイル、サブディレクトリの中から 最も新しい最終更新時刻を再帰的に探して返します。 パスが存在しない場合や、OUTPUT_MODE_DIR で指定されたディレクトリが空の場合はNoneを返します。
- converter.convert.main()[ソース]
プログラムのメインエントリポイント。コマンドライン引数を処理し、ファイル変換を実行します。
コマンドライン引数を解析し、ConverterRegistry を初期化して利用可能なコンバータを登録します。 引数に応じて、利用可能なコンバータの一覧表示、単一ファイルの変換、 または指定されたディレクトリツリーの走査と変換を実行します。 エラーが発生した場合は適切なメッセージを出力し、非ゼロの終了コードを返します。
- 戻り値:
プログラムの終了コード。成功時は0、エラー時は1。
- 戻り値の型:
- converter.convert.matches_target(filename: str, target_patterns: List[str] | None) bool[ソース]
ファイル名が指定されたターゲットパターンリストのいずれかに一致するかどうかを判定します。
target_patterns がNoneまたは空の場合、すべてのファイル名に一致すると見なします。 それ以外の場合、fnmatch.fnmatch を使用して、ファイル名とパターンを大文字小文字を区別せずに比較します。
- converter.convert.normalize_ext(ext: str) str[ソース]
ファイル拡張子を正規化します。
拡張子の前後の空白を削除し、小文字に変換し、必要に応じて先頭に"."を追加します。
- converter.convert.parse_args()[ソース]
コマンドライン引数を解析し、argparse.Namespace オブジェクトとして返します。
この関数は、ファイル変換ツールが受け付ける様々なオプションを定義します。 これには、走査するルートディレクトリ、単一ファイル変換の指定、 目的の出力拡張子、最大走査深度、ファイル名パターンによるフィルタリング、 更新・上書きモード、およびPandoc関連のオプション（パス、テンプレート、CSS、目次など）が含まれます。
- 戻り値:
解析されたコマンドライン引数を含むargparse.Namespaceオブジェクト。
- 戻り値の型:
- converter.convert.parse_target_patterns(target_text: str | None) List[str] | None[ソース]
セミコロンで区切られたターゲットパターン文字列を解析し、リストを返します。
入力文字列がNoneまたは空文字列の場合、Noneを返します。 それ以外の場合、文字列をセミコロンで分割し、各パターンから空白を除去したリストを返します。
- converter.convert.path_exists_for_mode(path: str, output_mode: str) bool[ソース]
指定されたパスが出力モードに応じて存在するかどうかをチェックします。
OUTPUT_MODE_DIR の場合、パスがディレクトリであり、かつその中に何らかのコンテンツが存在するか （ディレクトリが空でないか）を確認します。 OUTPUT_MODE_FILE の場合は、単に指定されたパスが存在するかどうかを確認します。
- converter.convert.safe_import_registry(registry: ConverterRegistry)[ソース]
外部ライブラリを安全にインポートし、利用可能なコンバータをレジストリに登録します。
各変換ライブラリのインポートは`try-except`ブロックで囲まれており、 一部のライブラリが利用できない場合でもプログラム全体がクラッシュせず、 そのエラーがレジストリに記録されるようにします。 これにより、ユーザーはどの機能が利用可能または利用不可であるかを把握できます。
- パラメータ:
registry (ConverterRegistry) -- コンバータの登録を行うConverterRegistryインスタンス。
- converter.convert.should_convert(input_path: str, output_path: str, output_mode: str, update: bool, overwrite: bool) Tuple[bool, str][ソース]
ファイルを変換する必要があるかどうかを判断します。
以下のロジックに基づいて変換の要否を決定します。 1. overwrite がTrueの場合、常に変換を行います。 2. 出力ファイルまたはディレクトリが存在しない場合、変換を行います。 3. update がFalseで出力が存在する場合、変換をスキップします。 4. update がTrueで出力が存在する場合、入力ファイルの最終更新時刻が出力ファイルの最終更新時刻よりも新しい場合に変換を行います。
- パラメータ:
- 戻り値:
変換すべき場合はTrueと理由、スキップすべき場合はFalseと理由のタプル。
- 戻り値の型:
- converter.convert.should_ignore_file(filename: str, spec: ConverterSpec) bool[ソース]
指定されたファイル名が、特定のコンバータ仕様で無視すべき一時ファイルであるかを判定します。
spec.ignore_temp_prefixes に含まれるいずれかの接頭辞でファイル名が始まる場合、 そのファイルは無視されるべき一時ファイルと見なされます。
- パラメータ:
filename (str) -- チェックするファイル名。
spec (ConverterSpec) -- 変換仕様 (ConverterSpec) オブジェクト。
- 戻り値:
ファイルが無視すべき一時ファイルである場合はTrue、それ以外の場合はFalse。
- 戻り値の型:
- converter.convert.walk_and_convert(root_dir: str, output_ext: str, registry: ConverterRegistry, max_level: int = -1, update: bool = True, overwrite: bool = False, target_patterns: List[str] | None = None, converter_kwargs: Dict[str, Any] | None = None)[ソース]
指定されたルートディレクトリを再帰的に走査し、条件に合うファイルを変換します。
os.walk を使用してディレクトリツリーを巡回し、各ファイルに対して convert_file を呼び出します。 最大走査深度、更新オプション、上書きオプション、およびファイル名パターンによるフィルタリングをサポートします。 変換プロセスに関する情報をコンソールに出力します。
- パラメータ:
root_dir (str) -- 走査を開始するルートディレクトリのパス。
output_ext (str) -- 目的の出力拡張子（例: ".pdf", ".md"）。
registry (ConverterRegistry) -- 利用可能なコンバータを保持するConverterRegistryインスタンス。
max_level (int) -- 最大走査深度。-1は無制限。デフォルトは-1。
update (bool) -- 出力ファイルが存在し、入力ファイルよりも新しい場合にスキップするかどうか。デフォルトはTrue。
overwrite (bool) -- 出力ファイルの存在やタイムスタンプに関わらず常に上書きするかどうか。デフォルトはFalse。
target_patterns (Optional[List[str]]) -- 変換対象とするファイル名のfnmatchパターンリスト。オプション。 例: [".pptx", ".docx"]。
converter_kwargs (Optional[Dict[str, Any]]) -- 変換関数に渡す追加のキーワード引数の辞書。オプション。
- 戻り値:
スキャンされたサポート対象ファイル数と実際に変換されたファイル数のタプル。
- 戻り値の型:
- converter.convert.wrap_docx_to_png(docx_to_pdf: Callable[[str, str], Any], pdf_to_images: Callable[[...], Any]) Callable[[...], bool][ソース]
Word (docx) ファイルをPNG画像に変換するパイプラインをラップします。
このラッパーは、最初にdocxファイルを一時的なPDFに変換し、次にそのPDFを 指定された出力ディレクトリにPNG画像として変換します。
- パラメータ:
- 戻り値:
標準の変換関数シグネチャ (input_path, output_path, **kwargs) に適合するラッパー関数。
- 戻り値の型:
Callable[..., bool]
- converter.convert.wrap_image_to_dir(converter: Callable[[...], Any], rename_func: Callable[[str], Any] | None = None) Callable[[...], bool][ソース]
入力ファイルを画像ディレクトリに変換する関数をラップします。
このラッパーは、出力ディレクトリが存在しない場合に作成し、 指定されたコンバータを実行して画像を生成します。 必要に応じて、生成された画像のファイル名を変更するための`rename_func`を呼び出すこともできます。
- パラメータ:
converter (Callable[..., Any]) -- 入力ファイルを画像ディレクトリに変換するCallableオブジェクト。 通常は input_path, output_path, output_format を引数に取ります。
rename_func (Optional[Callable[[str], Any]]) -- 変換後に生成された画像ファイル名を変更するためのCallableオブジェクト。 引数として出力ディレクトリのパスを受け取ります。オプション。
- 戻り値:
標準の変換関数シグネチャ (input_path, output_path, **kwargs) に適合するラッパー関数。
- 戻り値の型:
Callable[..., bool]
- converter.convert.wrap_ipynb_json_to_md(convert_func: Callable[[...], Any]) Callable[[...], bool][ソース]
Jupyter Notebook (.ipynb) またはJSONファイルをMarkdownに変換する関数をラップします。
ラップされた関数は、元の変換関数を実行し、結果がNoneでないか、 または出力ファイルが存在すれば成功と判断します。
- パラメータ:
convert_func (Callable[..., Any]) -- .ipynbまたはJSONをMarkdownに変換するCallableオブジェクト。 input_path, output_path を引数に取ります。
- 戻り値:
標準の変換関数シグネチャ (input_path, output_path, **kwargs) に適合するラッパー関数。
- 戻り値の型:
Callable[..., bool]
- converter.convert.wrap_ipynb_json_to_pdf(ipynb_or_json_to_md: Callable[[...], Any], md_to_pdf: Callable[[...], Any]) Callable[[...], bool][ソース]
Jupyter Notebook (.ipynb) またはJSONファイルをPDFに変換するパイプラインをラップします。
このラッパーは、最初にJupyter NotebookまたはJSONファイルを一時的なMarkdownに変換し、 次にそのMarkdownファイルをPDFに変換します。一時ディレクトリは処理後に削除されます。
- パラメータ:
ipynb_or_json_to_md (Callable[..., Any]) -- .ipynbまたはJSONをMarkdownに変換するCallableオブジェクト。 input_path, output_md_path を引数に取ります。
md_to_pdf (Callable[..., Any]) -- MarkdownをPDFに変換するCallableオブジェクト。 input_md_path, output_pdf_path を引数に取ります。
- 戻り値:
標準の変換関数シグネチャ (input_path, output_path, **kwargs) に適合するラッパー関数。
- 戻り値の型:
Callable[..., bool]
- converter.convert.wrap_md_with_images(convert_func: Callable[[...], Any]) Callable[[...], bool][ソース]
画像を伴うMarkdown変換関数をラップします。
このラッパーは、変換関数がMarkdownファイル本体と、それに付随する画像が保存される ディレクトリパスの両方を引数として受け取ることを想定しています。 変換関数がNoneを返すか、出力ファイルが存在すれば成功と見なします。
- パラメータ:
convert_func (Callable[..., Any]) -- Markdownと関連画像を変換するCallableオブジェクト。 通常は input_path, output_md_path, output_image_dir_path を引数に取ります。
- 戻り値:
標準の変換関数シグネチャ (input_path, output_path, **kwargs) に適合するラッパー関数。
- 戻り値の型:
Callable[..., bool]
- converter.convert.wrap_pandoc(target: str, default_template: str | None = None) Callable[[...], bool][ソース]
Pandocを利用したMarkdown変換関数をラップします。
このラッパーは、pandoc モジュールを動的にインポートし、 convert_md 関数を呼び出してMarkdownファイルを指定されたターゲット形式に変換します。 pandoc_path、template、toc、css などの様々なPandocオプションを キーワード引数として受け渡しできるようにします。
- converter.convert.wrap_pdf2md(convert_func: Callable[[str, str | None], Any]) Callable[[...], bool][ソース]
PDFをMarkdownに変換する関数を、標準のラッパー形式に変換します。
ラップされた関数は、元の変換関数を実行し、結果がNoneでないか、 または出力ファイルが存在すれば成功と判断します。