◾️前提：データ処理系のツールの場合
setup.pyに以下の記述があることを前提とします。
|
1 2 |
install_requires=[...]: 依存ライブラリ一覧 entry_points={...}: コマンドの入り口 |
これらがあることが特定できれば、プロジェクトの全貌を掴むための「具体的なアクション」に移れます。
次にやるべきことを「2つの調査」と「1つの追跡」に分けてメモしておきます。
Action 1: install_requires で「武器」を知る
まずは install_requires のリストを見て、このプロジェクトが「何を使って戦っているか」を把握します。
これらを知らないままコードを読むと、呪文に見えて挫折します。
以下は例として、有名ライブラリを記載しています。
1. CLI（コマンドライン）操作系
これが「入り口の扉」を作っています。
-
click,typer,fire,argparse -
意味: コマンドの引数（
--inputや--verbose）を解析するライブラリです。entry_pointsで指定された関数の直前に、これらのデコレータ（@click.commandなど）がついているはずです。
2. データ処理系
これが「材料の調理」を担当します。
-
pandas,numpy(Excelや大量データ処理) -
pydantic,marshmallow(データのバリデーション・型定義) -
sqlalchemy(データベース接続)
3. 生成・描画系（ここが核心！）
これが「ドキュメントの出力」を担当します。
-
jinja2,mako(テンプレートエンジン：HTMLやテキストの穴埋め) -
reportlab,fpdf,weasyprint(PDF生成) -
openpyxl,xlwings(Excel生成) -
python-docx(Word生成)
ポイント:
知らないライブラリがあれば、ググって「あ、これはPDFを作るやつね」と1行で言えるレベルまで把握しておくと良い。参画当初の時点では、深い使い方はまだ覚えなくて良い。
Action 2: entry_points で「最初のドミノ」を見つける
setup.py の entry_points に書かれている文字列は、「ファイルの場所」と「関数名」の住所です。ここを読み解きましょう。
読み方
|
1 2 3 4 5 |
<span class="hljs-string">"console_scripts"</span>: [ <span class="hljs-comment"># コマンド名 = パッケージ.モジュール : 関数名</span> <span class="hljs-string">"doc-gen = src.cli:main"</span>, ] |
この記述があった場合、次の手順でファイルを開きます。
-
フォルダ構成の
src/を開く。 -
その中の
cli.py(またはcli/__init__.py) を開く。 -
その中の
def main():という関数を探す。
ここが、プログラムが動き出す「最初のドミノ」です。
Action 3: 「main」から「ロジック」への橋渡しを追う
ここからがコードリーディングの本番です。
ただし、main 関数の中に「ドキュメント生成のロジック」が全部書いてあることは稀です。通常、main は司令塔に過ぎません。
以下の「3層構造」を意識して、コードの参照先（ジャンプ）を追いかけます。
1. Interface Layer (司令塔)
-
場所: Action 2で見つけた
main関数周辺。 -
やっていること:
-
「ユーザーが
--format pdfと言っているな」と判断する。 -
「じゃあ、PDF生成係（ロジック）を呼ぼう」と決める。
-
-
チェック: ここでビジネスロジックを探そうとせず、「次はどのファイル（クラス）を呼び出しているか？」だけを見ます。
2. Application Layer (監督)
-
場所:
mainから呼び出されたクラス（例:DocumentGeneratorやUseCase）。 -
やっていること:
-
データの取得メソッドを呼ぶ。
-
取得したデータを加工メソッドに渡す。
-
最後に保存メソッドを呼ぶ。
-
-
チェック: ここが一番重要です。「処理全体の流れ」がここに書かれています。
3. Domain/Infrastructure Layer (職人)
-
場所: データの取得や、実際のPDF書き出しを行うクラス。
-
やっていること: SQLを投げたり、ライブラリを使ってファイルを保存したりする。
まとめ：次にやる具体的な作業
-
install_requiresを見る:「このプロジェクトは、テンプレートエンジンに
Jinja2を使って、PDF化にはWeasyPrintを使う構成なんだな」といった「技術スタック」をメモします。 -
entry_pointsの先へ行く:指定されたファイルを開き、その関数（例：
main）にブレークポイントを貼ります。 -
デバッガを起動:
実際にツールを動かし、そのブレークポイントで止まることを確認します。
ここまで一旦できれば、「コードの動きを追える状態」になります。
