Pythonでパッケージ構成を組む基本を解説します

結論から言うと、パッケージ構成は、関連するモジュールを1つのフォルダにまとめ、役割ごとに探しやすくするための整理方法です。

自作モジュールが増えてくると、同じフォルダに .py ファイルが並び、どこに何があるのか分かりにくくなることがあります。
そのようなときは、関連するファイルをフォルダにまとめて、パッケージとして扱うと管理しやすくなります。
この記事では、売上レポートを作る小さな例を使って、パッケージ構成の基本を整理します。

この記事でわかること

完成コード

完成コードは次の通りです。

# sales/report.py に置く想定の処理
def calculate_total(items: list[dict[str, int]]) -> int:
    return sum(item["price"] * item["quantity"] for item in items)


def create_report(items: list[dict[str, int]]) -> str:
    total = calculate_total(items)
    return f"売上合計: {total:,}円"


# main.py に置く想定の処理
orders = [
    {"price": 1200, "quantity": 2},
    {"price": 800, "quantity": 3},
]

print(create_report(orders))

実際にパッケージとして分ける場合は、次のような構成にします。

project/
  main.py
  sales/
    __init__.py
    report.py

main.py では、次のように読み込みます。

from sales.report import create_report

コードのポイント

このコードでは、売上レポートに関する処理を sales パッケージにまとめる想定で書いています。

• sales フォルダがパッケージのまとまりになります
• report.py に売上レポート用の関数を置いています
• main.py から sales.report を指定して関数を読み込んでいます
• __init__.py は、そのフォルダをパッケージとして扱うために置きます

パッケージは、難しい設計を最初から入れるためのものではありません。
まずは「関連するモジュールをフォルダにまとめる」と考えると理解しやすいです。

コードを順番に説明します

主要な処理を分けて説明します。

1. 関連するモジュールをフォルダにまとめます

sales/
  __init__.py
  report.py

sales フォルダには、売上に関係する処理をまとめます。
今回の例では report.py だけですが、あとから csv_reader.py や formatter.py のようなファイルを増やすこともできます。

__init__.py は、パッケージの入口になるファイルです。
最近のPythonでは空でも動く場面がありますが、初学者のうちは置いておくと「ここはPythonのパッケージです」と明示できて分かりやすくなります。

2. パッケージ内に処理を置きます

def create_report(items: list[dict[str, int]]) -> str:
    total = calculate_total(items)
    return f"売上合計: {total:,}円"

この関数は、売上データから表示用のレポート文字列を作ります。
売上レポートに関する処理なので、sales/report.py に置くと役割が自然です。

パッケージ構成では、フォルダ名とファイル名の両方で役割を表します。
sales.report と読むだけで、売上関連のレポート処理だと想像しやすくなります。

3. メイン処理から読み込んで使います

from sales.report import create_report

print(create_report(orders))

from sales.report import create_report は、sales パッケージの中にある report モジュールから、create_report 関数を読み込む書き方です。
ドットでつないで、フォルダとファイルの位置をたどっています。

この形にすると、main.py には大きな処理の流れだけを残せます。
レポート作成の詳しい処理を直したいときは、sales/report.py を見ればよくなります。

実務で使うときのポイント

実務では、パッケージ構成はツールやアプリが少し大きくなってきた段階で役立ちます。
たとえば、CSVを読み込み、集計し、レポートを出力する処理を作るなら、入出力、集計、表示を別モジュールに分けられます。

最初から細かく分けすぎる必要はありません。
まずは1つのファイルで動く形を作り、処理が増えてきたら関連するものをパッケージにまとめる流れが扱いやすいです。

第5章の前半で扱った自作モジュールの考え方は、パッケージ構成にもそのままつながります。
モジュールが増えたときに、フォルダで整理する選択肢を持っておくと、コードの見通しを保ちやすくなります。

よくある勘違い・注意点

まとめ