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

プログラムの動作

add_docstring.py は、指定されたPythonソースコードファイルに対し、AI(大規模言語モデル)を利用してSphinx形式のDocstringを自動的に追加するツールです。

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

  • Docstringの自動生成: AIモデルがソースコードの内容を解析し、関数、クラス、モジュール全体に適切なDocstringを生成します。

  • INIファイルによるプロンプト設定: Docstring生成のためのプロンプトやAIのシステムロールは、INIファイルで柔軟に設定可能です。これにより、特定のDocstringスタイルや詳細度合いに合わせたカスタマイズが容易です。

  • 複数のAIプロバイダー対応: OpenAI、Google Gemini、LM Studioなどの多様なAIサービスプロバイダーをサポートし、ユーザーの環境や好みに応じて選択できます。

  • ワイルドカードによる一括処理: 複数のPythonファイルをワイルドカードパターンで指定し、一括でDocstringを追加できます。

  • 更新・上書き制御: 既存の出力ファイルが存在する場合、元のソースコードの更新日時と出力ファイルの更新日時を比較し、最新のファイルのみを処理するモードや、強制的に上書きするモードを提供します。

  • カスタム引数対応: LM StudioのQwen3.8モデルなど、特定のモデルが持つカスタム引数(例: reasoning_effort)にも対応しています。

このプログラムは、手動でのDocstring作成にかかる時間と労力を削減し、プロジェクト全体のコードドキュメントの一貫性と品質向上に貢献します。

原理

add_docstring.py は、主に以下の原理に基づいて動作します。

  1. AI (LLM) によるDocstring生成: プログラムの核となるのは、与えられたPythonコードに対してDocstringを生成する大規模言語モデル(LLM)の利用です。スクリプトは、対象のPythonコードとINIファイルで定義されたプロンプトテンプレートを組み合わせてAIに送信します。AIはコードを理解し、その構造(関数、クラス、モジュールなど)と目的を基に、指定された形式(Sphinx形式)のDocstringを生成します。

  2. プロンプトエンジニアリング: 効果的なDocstringを生成するためには、AIへの適切な指示(プロンプト)が不可欠です。本プログラムでは、INIファイルを通じてプロンプトテンプレート (PROMPT_MAIN) とシステムロール (SYSTEM_ROLE) を設定できます。 PROMPT_MAIN テンプレート内では、{{script_name}}、{{code}}、{{base_name}} のようなプレースホルダーが使用され、実行時に実際のファイル名やコード内容に置換されてAIに送られます。これにより、AIはコンテキストを正確に把握し、関連性の高いDocstringを生成できます。

  3. tkai_lib_litellm を介したAI連携: AIモデルとの通信は、tkai_lib_litellm というラッパーライブラリを介して行われます。このライブラリは、内部的にLiteLLMを利用し、OpenAI、Google Gemini、LM Studioなど、複数のAIプロバイダーへの統一されたインターフェースを提供します。これにより、バックエンドのAIサービスを簡単に切り替えることが可能になります。

  4. INIファイル解析: 設定ファイル(INI形式)の読み込みには、カスタムのread_ini関数が使用されます。この関数は、キーと値のペアを解析するだけでなく、3重引用符で囲まれた複数行の文字列値(Docstringプロンプトなど)も正確に読み取ることができます。また、$VAR形式の変数展開もサポートしており、INIファイル内での設定の再利用性を高めます。

  5. 更新・上書き制御ロジック: ファイルの処理において、不要なAI呼び出しやファイルの書き込みを避けるため、更新・上書き制御が行われます。 --update 1 オプションが指定されている場合、出力ファイルの最終更新日時 \(t_{out}\) と入力ファイルの最終更新日時 \(t_{in}\) を比較します。

    • 出力ファイルが存在しない場合、または出力ファイルが入力ファイルより古い場合 (\(t_{out} < t_{in}\))、処理を実行します。

    • 出力ファイルが存在し、かつ入力ファイルより新しいか同じ場合 (\(t_{out} \ge t_{in}\))、処理をスキップします。

    \[ \text{If } (\text{not exists}(\text{output file})) \lor (t_{out} < t_{in}) \text{ then process else skip} \]

    --overwrite 1 オプションが指定されている場合は、上記の更新日時に関わらず、常に既存の出力ファイルを上書きします。

必要な非標準ライブラリとインストール方法

このプログラムは、AI連携のために tkai_lib_litellm を使用します。 tkai_lib_litellm は、内部的に litellm ライブラリを利用しているため、まず litellm をインストールする必要があります。

  1. litellm のインストール: litellm は pip コマンドでインストールできます。

    pip install litellm
    
  2. tkai_lib_litellm.py の配置: tkai_lib_litellm は、通常の pip でインストールされるパッケージではなく、別途提供されるPythonモジュールです。このモジュールは、add_docstring.py と同じディレクトリ、またはPythonの検索パスが通っている任意の場所に tkai_lib_litellm.py というファイル名で配置する必要があります。

    例: add_docstring.py と同じディレクトリに配置する場合

    .
    ├── add_docstring.py
    └── tkai_lib_litellm.py
    

必要な入力ファイル

プログラムは以下の入力ファイルを必要とします。

  1. Pythonソースコードファイル: Docstringを追加したい対象のPythonスクリプトファイルです。ファイル名やパスは、コマンドライン引数 pattern でワイルドカードを使用して指定します(例: '*.py', 'src/*.py')。

  2. INI設定ファイル: AIへのプロンプトやシステムロールを定義するための設定ファイルです。コマンドライン引数 --inifile でパスを指定します。指定がない場合、デフォルトで add_docstring.ini がカレントディレクトリまたはスクリプトの実行ディレクトリから検索されます。

    ファイル形式: 標準的なINI形式ですが、特に複数行の文字列を3重引用符("""または''')で囲んで記述できます。変数展開 ($VAR) もサポートしています。

    記載例 (add_docstring.ini):

    # Docstring生成のメインプロンプト
    PROMPT_MAIN = """
    与えられたPythonスクリプト "{{script_name}}" のコードを解析し、Sphinx形式のDocstringを関数、クラス、およびモジュール全体に適切に追加してください。
    Docstringは、以下の要素を含めてください:
    - 短い要約
    - 詳細な説明
    - 引数 (`:param <name>: <description>`)
    - 戻り値 (`:returns: <description>`)
    - 例外 (`:raises: <description>`)
    - 必要に応じて型ヒント (`:type <name>: <type>`)
    
    元のコードのロジックやコメントを変更せず、Docstringのみを追加または更新してください。
    最終的な出力は、Docstringが追加された完全なPythonコードとしてください。
    以下のコードです:
    ```python
    {{code}}
    

    """

    AIのシステムロール(AIの役割定義)

    SYSTEM_ROLE = You are a helpful assistant specialized in generating Sphinx-style docstrings for Python code.

    
    
  3. ai.env ファイル (任意): AIサービスのAPIキーなどの環境変数を設定するためのファイルです。tkai_lib_litellm ライブラリがこのファイルを読み込み、API認証情報などをロードします。このファイルは必須ではありませんが、APIキーをコード内に直接記述せず、環境変数として管理する推奨される方法です。

    記載例 (ai.env):

    GEMINI_API_KEY=YOUR_GEMINI_API_KEY_HERE
    OPENAI_API_KEY=YOUR_OPENAI_API_KEY_HERE
    LMSTUDIO_BASE_URL=http://localhost:1234/v1
    

    (注: 実際のAPIキーやエンドポイントは、使用するAIプロバイダーやLM Studioの設定によって異なります。)

生成される出力ファイル

プログラムの実行により、以下の出力ファイルが生成されます。

  • ファイル名:

    • 単一の入力ファイルが指定され、かつ output 引数が与えられた場合: 指定された output 引数の値がファイル名となります。

    • 複数の入力ファイルが指定された場合、または単一ファイルだが output 引数が省略された場合: 各入力ファイル名に _docstring.py が付加されたファイル名となります。 例: 入力ファイルが my_script.py の場合、出力ファイルは my_script_docstring.py となります。

  • 内容: 入力されたPythonソースコードに、AIによって生成されたDocstringが適切に挿入された完全なPythonコードです。DocstringはSphinx形式に従い、モジュール、クラス、関数の定義箇所に挿入されます。元のコードロジックや既存のコメントは変更されません。

コマンドラインでの使用例 (Usage)

add_docstring.py は、以下の書式でコマンドラインから実行します。

python add_docstring.py <pattern> [output] [options]

引数

  • <pattern> (必須): 対象とするPythonファイルのワイルドカードパターン。 例: '*.py', 'src/*.py'

  • [output] (任意): 出力ファイル名。<pattern> で指定されたファイルが単一の場合にのみ有効です。複数ファイルが指定された場合は無視されます。

オプション

  • --inifile PATH: プロンプト設定ファイルのパスを指定します。 デフォルト: add_docstring.ini

  • --api {openai,openai5,google,gemini,lmstudio}: 使用するAIプロバイダーを指定します。 デフォルト: google

  • --model MODEL_NAME: 使用するAIモデル名を指定します。 例: gpt-4o-mini, gemini-1.5-flash, qwen/qwen3.8-27b このオプションが指定されない場合、ai.env ファイルや環境変数から適切なモデルが選択されます。

  • --reasoning-effort {low,medium,xhigh}: LM StudioのQwen3.8モデルに特化した推論量設定です。--api lmstudio と組み合わせてのみ使用できます。 デフォルト: None (モデル既定値)

  • -u 1, --update 1: 更新モードを有効にします。出力ファイルが既存で、かつ入力ファイルより新しい場合に処理をスキップします。 デフォルト: 0

  • -w 1, --overwrite 1: 上書きモードを有効にします。出力ファイルが既存の場合でも、常に上書きします。 デフォルト: 0

  • -p 0, --pause 0: プログラム終了時のポーズを無効にします。 デフォルト: 1 (終了時にEnterキー入力待ち)

コマンドラインでの具体的な使用例

例1: 単一のPythonファイルにDocstringを追加し、別名で出力する

my_script.py というファイルにDocstringを追加し、my_script_with_doc.py として保存します。AIプロバイダーとしてGoogle Gemini、モデルとしてgemini-1.5-flashを使用します。

python add_docstring.py my_script.py my_script_with_doc.py --api gemini --model gemini-1.5-flash

実行結果の説明: my_script.py が解析され、AIによって生成されたDocstringが挿入されたコードが my_script_with_doc.py に書き込まれます。

例2: 複数のPythonファイルに一括でDocstringを追加する

src/ ディレクトリ内のすべてのPythonファイル (.py) に対してDocstringを追加し、それぞれ _docstring.py を付加した名前で出力します。INIファイルはデフォルトの add_docstring.ini を使用します。

python add_docstring.py 'src/*.py' --api openai --model gpt-4o-mini

実行結果の説明: 例えば src/util.py があった場合、Docstringが追加された src/util_docstring.py が生成されます。src/main.py があれば src/main_docstring.py が生成される、といった形で、対象のすべてのファイルが処理されます。

例3: 更新モードとカスタムINIファイルを使用してDocstringを更新する

my_module.py のDocstringを更新します。custom_prompt.ini を設定ファイルとして使用し、更新モード (-u 1) を有効にします。これにより、my_module_docstring.py が my_module.py より新しい場合はスキップされます。

python add_docstring.py my_module.py --inifile custom_prompt.ini -u 1 --api google

実行結果の説明: プログラムは my_module.py と既存の my_module_docstring.py の更新日時を比較します。

  • もし my_module.py が my_module_docstring.py より新しい場合、my_module.py を処理し、Docstringを追加した内容で my_module_docstring.py を更新します。

  • もし my_module_docstring.py が my_module.py と同じかより新しい場合、処理をスキップし、my_module_docstring.py は変更されません。

例4: LM StudioのQwen3.8モデルで推論量を指定してDocstringを生成する

LM StudioでホストされているQwen3.8モデル (qwen/qwen3.8-27b) を使用し、advanced_func.py にDocstringを追加します。この際、LM Studioの特別な引数 --reasoning-effort xhigh を指定して、高い推論レベルでDocstringを生成させます。

python add_docstring.py advanced_func.py --api lmstudio --model qwen/qwen3.8-27b --reasoning-effort xhigh

実行結果の説明: LM Studioを通じてQwen3.8モデルが呼び出され、advanced_func.py の内容に基づいてDocstringが生成されます。--reasoning-effort xhigh の指定により、より詳細で質の高いDocstringが生成される可能性があります。生成されたDocstring付きコードは advanced_func_docstring.py として出力されます。