add_docstring プログラム仕様

PythonコードにSphinx形式のDocstringを自動追加するツール。

このスクリプトは、指定されたPythonソースコードファイルにAI(LiteLLM経由)を用いて Sphinx形式のDocstringを自動的に生成し、追加します。 ワイルドカードパターンによる複数ファイルの処理、INIファイルによるプロンプト設定、 AIモデルとプロバイダーの選択、既存ファイルの更新・上書き制御などの機能を持ちます。

tkai_lib_litellm ライブラリと連携し、AIからの出力を整形してファイルに書き込みます。

プログラム add_docstring.py の技術ドキュメント

ai.add_docstring.initialize()

コマンドラインパーサーを初期化し、利用可能な引数を定義します。

この関数は ArgumentParser オブジェクトを設定し、スクリプトの実行に必要な さまざまなオプション(入力ファイルパターン、出力ファイル名、INIファイルパス、 AIプロバイダー、モデルなど)を定義します。

戻り値:

argparse.ArgumentParser: 初期化されたコマンドラインパーサーオブジェクト。

ai.add_docstring.main()

スクリプトの主要な処理フローを実行します。

コマンドライン引数の解析、INIファイルの読み込み、指定されたファイルパターンに 一致するファイルの処理を行います。各ファイルに対してAIを呼び出し、 Docstringを生成して出力ファイルに書き込みます。 更新モードや上書きモードの制御、エラーハンドリングも含まれます。

戻り値:

None

ai.add_docstring.read_args(parser)

コマンドライン引数をパースし、その値を表示します。

initialize 関数で定義されたパーサーを使用して引数を解析し、 デバッグ目的でパースされた引数の詳細を標準出力に表示します。

パラメータ:

parser (argparse.ArgumentParser) -- 初期化されたコマンドラインパーサー。

戻り値:

argparse.Namespace: パースされた引数を格納したオブジェクト。

ai.add_docstring.read_ini(inifile=None)

INIファイルを読み込み、設定を辞書として返します。

セクションを持たないシンプルなINIファイルを想定しており、キーと値のペアを処理します。 複数行の値(トリプルクォーテーションで囲まれたもの)や、 読み込まれた変数を使った値の展開($VAR形式)もサポートしています。 コメント行(#または;で始まる行)はスキップされます。

パラメータ:

inifile (str) -- 読み込むINIファイルのパス。Noneの場合、search_file で見つかったデフォルトのINIファイルを使用します。

戻り値:

dict: INIファイルから読み込まれた設定を格納した辞書。

例外:

FileNotFoundError -- 指定されたINIファイルが見つからない場合。

ai.add_docstring.resolve_model(args)

コマンドライン引数または環境変数から使用するAIモデル名を解決します。

--model オプションが指定されている場合はそれを優先し、 それ以外の場合は --api オプションに応じて対応する環境変数 (例: openai_model, gemini_model) を参照します。

パラメータ:

args (argparse.Namespace) -- コマンドライン引数を格納したオブジェクト。

戻り値:

strまたはNone: 解決されたAIモデル名。見つからない場合はNone。

ai.add_docstring.resolve_provider(api_name)

旧式のAPI名をLiteLLM互換のプロバイダー名に変換します。

--api オプションで指定されるプロバイダー名を、LiteLLMライブラリが認識する 内部的なプロバイダー名にマッピングします。

パラメータ:

api_name (str) -- コマンドライン引数で指定されたAPIプロバイダー名 (例: 'openai', 'google', 'lmstudio')。

戻り値:

str: LiteLLM互換のプロバイダー名 (例: 'openai', 'gemini', 'lmstudio')。

ai.add_docstring.search_file(infile=None)

指定されたファイルをカレントディレクトリまたはスクリプトディレクトリから検索します。

まずカレントディレクトリを検索し、見つからない場合はスクリプトが配置されている ディレクトリを検索します。

パラメータ:

infile (str) -- 検索対象のファイル名。Noneの場合、スクリプト名に拡張子.iniを付加したファイル名を使用します。

戻り値:

strまたはNone: 見つかったファイルの絶対パス。見つからない場合はNone。