Pythonのモジュールとパッケージの違いとは？フォルダ構成で迷う初心者へ
Pythonを学んでいると、よくモジュールやパッケージという言葉が出てきます。 そんなとき、以下のような疑問を持ったことはありませんか？
モジュールってなに？ パッケージってなに？ そもそも両者の違いはなんなのか？
結論から言うと、Pythonでは 1つのPythonファイルがモジュール、複数のモジュールをまとめるフォルダがパッケージ と考えると理解しやすいです。
この記事では、Pythonのモジュールとパッケージの違いを、IT初心者にもわかりやすく解説します。
Pythonのモジュールとは¶
まずは、モジュールから見ていきましょう。
モジュールという言葉は少し難しく聞こえますが、Pythonではかなり身近なものです。
モジュールはPythonファイルのこと¶
モジュールとは、プログラムやシステムを機能ごとに分割した独立した部品のことです。
Pythonにおけるモジュールは、基本的に .py で終わるPythonファイルのことを指します。
たとえば、次のようなファイルがあるとします。
calculator.py
この calculator.py は、Pythonのモジュールです。
ファイルの中に関数や変数、クラスを書いておくと、別のファイルから読み込んで使えます。
# calculator.py
def add(a, b):
return a + b
このファイルを別のPythonファイルから使う場合は、次のようにimportします。
import calculator
result = calculator.add(3, 5)
print(result)
実行結果は次の通りです。
8
このように、よく使う処理を別ファイルに分けておくと、コードを整理しやすくなります。
モジュールを使う理由¶
モジュールを使う理由は、コードを分けて管理しやすくするためです。
すべての処理を1つのファイルに書くと、最初は簡単でも、だんだん読みにくくなります。
たとえば、ユーザー登録、ログイン、計算処理、ファイル保存、画面表示などを1つのファイルに全部書いたらどうでしょうか。
最初は動いていても、あとから修正するときにかなり大変です。
そこで、役割ごとにファイルを分けます。これがモジュールを使う大きな理由です。
Pythonのパッケージとは¶
次に、パッケージについて見ていきましょう。
モジュールがファイルなら、パッケージは何なのでしょうか。
パッケージはモジュールをまとめるフォルダ¶
Pythonのパッケージは、複数のモジュールをまとめるフォルダのことです。
たとえば、次のような構成を考えます。
my_app/
utils/
string_utils.py
file_utils.py
この utils フォルダの中に、string_utils.py や file_utils.py というモジュールがあります。
このように、関連するモジュールをフォルダでまとめたものがパッケージです。
実際には、パッケージとして扱うために __init__.py というファイルを置くことがあります。
my_app/
utils/
__init__.py
string_utils.py
file_utils.py
__init__.py は空でも構いません。
初心者のうちは、パッケージとして認識させるための目印のようなものと考えるとわかりやすいです。
パッケージを使う理由¶
パッケージを使う理由は、モジュールが増えてきたときに整理しやすくするためです。
ファイルが数個のうちは、同じフォルダに置いても困りません。
しかし、アプリが大きくなると、認証関連、データベース関連、画面関連、便利関数など、役割ごとに分けたくなります。
そのときに、パッケージが役立ちます。
フォルダでまとめることで、どこに何があるのかを把握しやすくなります。
モジュールとパッケージの違い¶
ここで、モジュールとパッケージの違いを表で整理してみましょう。
用語だけで覚えるより、ファイルとフォルダの違いで見ると理解しやすいです。
| 項目 | モジュール | パッケージ |
|---|---|---|
| 実体 | .py ファイル |
モジュールをまとめるフォルダ |
| 例 | calculator.py |
utils/ |
| 役割 | 関数やクラスをまとめる | 関連するモジュールをまとめる |
| import例 | import calculator |
import utils.string_utils |
| 初心者向けの理解 | 1つの部品ファイル | 部品を入れる箱 |
この表のように、モジュールはファイル、パッケージはフォルダと考えるとかなり楽です。
細かい仕様を見ると例外もありますが、初心者の段階ではこの理解で十分です。
importの基本を理解しよう¶
モジュールやパッケージを理解するには、importの基本も大切です。
importは、別のファイルやライブラリの機能を読み込むための仕組みです。
import モジュール名¶
一番基本的な書き方は、import モジュール名 です。
import math
print(math.sqrt(16))
このコードでは、Python標準の math モジュールを読み込んでいます。
sqrt() は平方根を求める関数です。math.sqrt(16) の結果は 4.0 になります。
このように、モジュールをimportすると、モジュール名.関数名 の形で使えます。
from モジュール import 関数¶
特定の関数だけを読み込みたい場合は、次のように書けます。
from math import sqrt
print(sqrt(16))
この場合、math.sqrt() ではなく、sqrt() と直接書けます。
便利ですが、初心者のうちはどこから来た関数なのかわかりにくくなることがあります。
最初は import math のように、モジュール名を残す書き方の方が読みやすい場面も多いです。
【関連記事】Pythonで円周率を使うには？math.piの基本から計算例まで初心者向けに解説
フォルダ構成で考えるモジュールとパッケージ¶
ここからは、初心者が特に迷いやすいフォルダ構成を見ていきます。
実際にファイルがどう並んでいるかを見ると、理解しやすくなります。
小さなアプリの構成¶
最初は、次のような小さな構成で十分です。
my_app/
main.py
calculator.py
calculator.py に計算用の関数を書きます。
# calculator.py
def add(a, b):
return a + b
main.py から読み込みます。
# main.py
import calculator
print(calculator.add(10, 20))
この場合、calculator.py はモジュールです。
同じフォルダにあるので、初心者でも比較的わかりやすい構成です。
フォルダで整理する構成¶
少し大きくなってきたら、役割ごとにフォルダを分けます。
my_app/
main.py
utils/
__init__.py
calculator.py
この場合、utils がパッケージで、calculator.py がモジュールです。
main.py から使うときは、次のように書けます。
from utils import calculator
print(calculator.add(10, 20))
または、関数だけを読み込むこともできます。
from utils.calculator import add
print(add(10, 20))
どちらも正しい書き方です。
ただし、プロジェクトが大きくなるほど、どこから何をimportしているのかがわかる書き方を選ぶことが大切になります。
init.pyとは何か¶
パッケージの話でよく出てくるのが __init__.py です。
このファイルを見て、何のためにあるのか疑問に思った人も多いのではないでしょうか。
パッケージの初期化ファイル¶
__init__.py は、パッケージを読み込むときに使われる特別なファイルです。
昔のPythonでは、このファイルがあるフォルダがパッケージとして扱われる、という意味が強くありました。
今のPythonでは、__init__.py がなくてもパッケージのように扱えるケースがあります。
ただ、初心者のうちは、明示的に __init__.py を置いておく方がわかりやすいです。
utils/
__init__.py
calculator.py
このようにしておくと、このフォルダはPythonのパッケージなんだなと判断しやすくなります。
init.pyは空でもよい¶
__init__.py は、最初は空で大丈夫です。
何かを書かなければいけないと思うかもしれませんが、学習段階では空ファイルとして置くだけで問題ありません。
慣れてくると、パッケージをimportしたときに使いたい処理を書いたり、よく使う関数をまとめて読み込めるようにしたりできます。
ただし、最初から難しい使い方をする必要はありません。
まずは、パッケージの目印になるファイルと考えておきましょう。
初心者がハマりやすいimportエラー¶
モジュールやパッケージを扱っていると、importエラーに出会うことがあります。
ここでは、よくある原因を整理します。
ファイル名とimport名が合っていない¶
まず多いのが、ファイル名とimport名の違いです。
たとえば、ファイル名が calc.py なのに、次のように書くとエラーになります。
import calculator
Pythonは、calculator.py というファイルを探します。
実際のファイル名が calc.py なら見つかりません。
この場合は、ファイル名に合わせて次のように書く必要があります。
import calc
初心者のうちは、ファイル名とimport名が一致しているかをまず確認しましょう。
実行する場所が違う¶
次に多いのが、実行する場所の問題です。
同じコードでも、どのフォルダから実行するかによってimportできたりできなかったりすることがあります。
たとえば、次のような構成があるとします。
my_app/
main.py
utils/
__init__.py
calculator.py
基本的には、my_app フォルダを基準にして実行するとわかりやすいです。
python main.py
別のフォルダから無理に実行すると、Pythonがモジュールを見つけられず、ModuleNotFoundErrorになることがあります。
【関連記事】PythonのModuleNotFoundErrorって何？解決するにはどうしたらいいの？
標準ライブラリと同じ名前にしてしまう¶
ファイル名にも注意が必要です。
たとえば、random.py や math.py のような名前のファイルを作ると、Python標準ライブラリと名前がぶつかることがあります。
my_app/
random.py
この状態で import random と書くと、自分の random.py が読み込まれてしまう場合があります。
すると、思ったように標準ライブラリが使えず、原因がわかりにくいエラーになります。
初心者のうちは、標準ライブラリと同じ名前のファイルを作らないようにしましょう。
実務でよく見るフォルダ構成¶
ここからは、実務でよく見るフォルダ構成を紹介します。
最初から真似する必要はありませんが、全体像を知っておくと学習の見通しがよくなります。
小規模なPythonアプリ¶
小規模なアプリでは、次のような構成でも十分です。
todo_app/
main.py
models.py
services.py
utils.py
この構成では、ファイルごとに役割を分けています。
models.py はデータの形、services.py は処理の流れ、utils.py は便利関数というように分けるイメージです。
ファイル数が少ないうちは、無理に細かいパッケージに分けなくても大丈夫です。
少し大きなWebアプリ¶
アプリが大きくなると、フォルダで分ける方が管理しやすくなります。
web_app/
app/
__init__.py
models/
__init__.py
user.py
services/
__init__.py
user_service.py
routes/
__init__.py
user_routes.py
run.py
この構成では、models、services、routes がそれぞれパッケージです。
その中に、役割ごとのモジュールがあります。
初心者には少し複雑に見えるかもしれません。
でも、考え方は同じです。ファイルがモジュール、フォルダがパッケージです。
フォルダ構成のコツ¶
ここで、少し実務目線の話をします。
エンジニア歴10年の中で、フォルダ構成がわかりやすいプロジェクトと、迷いやすいプロジェクトの両方を見てきました。
最初から分けすぎない¶
初心者がやりがちなのが、最初からきれいな設計を目指してフォルダを分けすぎることです。
もちろん、整理する意識は大切です。
ただ、最初から models、services、repositories、controllers、utils のように細かく分けすぎると、どこに何を書けばよいのかわからなくなります。
最初は、1つか2つのファイルで始めても大丈夫です。
コードが増えてきて、読みづらいと感じたタイミングで分ける方が自然です。
名前をわかりやすくする¶
フォルダやファイルの名前は、とても大切です。
aaa.py や test2.py のような名前では、あとから見たときに何のファイルかわかりません。
user.py、auth.py、file_utils.py、calculator.py のように、役割が想像できる名前にしましょう。
実務では、コードを書く時間より読む時間の方が長いことも多いです。
名前を見るだけで役割がわかると、未来の自分もチームの人も助かります。
importが複雑になったら構成を見直す¶
import文が長くなりすぎたり、どこから読み込んでいるのかわからなくなったりしたら、フォルダ構成を見直すサインです。
from app.services.user_service import create_user
このくらいならよくあります。
ただ、何階層も深くなり、似たような名前のファイルが増えてきたら注意が必要です。
初心者のうちは、動くことも大切ですが、少しずつ読みやすさも意識していきましょう。
モジュールとパッケージを学ぶ練習方法¶
最後に、モジュールとパッケージを理解するための練習方法を紹介します。
読むだけではなく、自分で小さく作ってみると理解が進みます。
まずは2ファイル構成で試す¶
最初は、ファイルを2つ作るだけで十分です。
practice/
main.py
message.py
message.py に関数を書きます。
# message.py
def hello(name):
return name + "さん、こんにちは"
main.py から読み込みます。
# main.py
import message
print(message.hello("Taro"))
これで、別ファイルの関数を使う感覚がつかめます。
次にフォルダを作って試す¶
次に、フォルダを1つ増やしてみます。
practice/
main.py
messages/
__init__.py
greeting.py
greeting.py に関数を書きます。
# messages/greeting.py
def hello(name):
return name + "さん、こんにちは"
main.py から使います。
# main.py
from messages.greeting import hello
print(hello("Hanako"))
これで、パッケージとモジュールの関係がかなり見えやすくなります。
まとめ¶
Pythonのモジュールとパッケージは、初心者が混乱しやすいテーマです。
でも、最初はシンプルに考えて大丈夫です。
モジュールは1つの.pyファイル、パッケージはモジュールをまとめるフォルダ です。
モジュールを使うと、関数やクラスを別ファイルに分けて整理できます。パッケージを使うと、関連するモジュールをフォルダでまとめて管理できます。
また、__init__.py はパッケージの目印として考えると理解しやすいです。
importでエラーが出たときは、ファイル名、実行場所、フォルダ構成、標準ライブラリとの名前の衝突を確認しましょう。
エンジニア歴10年の経験から見ても、フォルダ構成は最初から完璧にする必要はありません。
小さく作り、コードが増えてきたら少しずつ分ける。それくらいの感覚で大丈夫です。
まずは、2つのファイルに分けてimportしてみるところから始めてみましょう。
