Zenn
😺

Pythonのプロジェクトのフォルダ構造

に公開
Python
プロジェクト
プロジェクト管理
フォルダ構成
tech

Pythonのプロジェクトを開発する際に推奨される標準的なフォルダ構造を紹介します。

以下は、一般的なPythonプロジェクトの構成です：

project-name/
│
├── README.md                # プロジェクト概要、使い方、環境構築方法
├── LICENSE                  # ライセンスファイル
├── .gitignore               # Gitで無視するファイルを指定
├── requirements.txt         # 必要なPythonパッケージのリスト
├── setup.py                 # パッケージ化するためのセットアップファイル
├── pyproject.toml           # 現代的なビルド設定・依存関係管理（任意）
│
├── src/                     # ソースコードを格納するフォルダ
│   └── your_package/
│       ├── __init__.py      # パッケージ化のための初期化ファイル
│       ├── main.py          # アプリケーションのメイン処理
│       ├── module1.py       # 各種モジュール
│       └── module2.py
│
├── tests/                   # ユニットテストを格納するフォルダ
│   ├── __init__.py
│   ├── test_module1.py
│   └── test_module2.py
│
├── docs/                    # ドキュメントを保存（任意）
│   ├── usage.md
│   └── api_reference.md
│
├── examples/                # 使用例やサンプルスクリプト（任意）
│   └── demo.py
│
└── data/                    # データファイルや外部リソースを保存（任意）
    └── sample_data.csv

各フォルダ・ファイルの詳細な説明

① 基本ファイル

  • README.md

    • プロジェクト概要、導入方法、使い方、開発環境設定方法を記載。

  • LICENSE

    • ソフトウェアのライセンス情報。

  • .gitignore

    • Git管理対象外のファイルを指定（キャッシュファイルやログ、設定ファイル等）。

② Python依存関係の管理

  • requirements.txt

    • プロジェクトに必要なPythonパッケージをリストアップ。
    numpy==1.26.3
torch==2.3.0
opencv-python==4.11.0

  • setup.py

    • パッケージとして公開したり、他のプロジェクトで再利用したりする際に利用。
    from setuptools import setup, find_packages

setup(
    name="your_package",
    version="0.1.0",
    packages=find_packages(where="src"),
    package_dir={"": "src"},
    install_requires=[
        "numpy",
        "torch",
        "opencv-python"
    ],
)

  • pyproject.toml

    • モダンな依存関係管理に使用する場合（PoetryやPDM等）。

③ ソースコードフォルダ (src/)

  • Pythonのソースコードを格納。
  • プロジェクトが大きくなっても整理しやすいようにパッケージ形式を採用。
  • __init__.py は空でもよく、Pythonがフォルダをパッケージとして認識するために使用。
# src/your_package/module1.py
def foo():
    pass

# 利用時
from your_package.module1 import foo

④ テストコード (tests/)

  • pytest などを使ってユニットテストを行う。
  • 実際のソースコードと分けることで、コードの明確化やテスト管理を容易にする。
# tests/test_module1.py
from your_package.module1 import foo

def test_foo():
    assert foo() is None

⑤ ドキュメント (docs/)

  • Markdownなどでプロジェクトの詳細なドキュメントを作成。
  • 将来的にSphinxなどを使ったAPIドキュメント化も可能。

⑥ サンプル・実行例 (examples/)

  • 実際のコードの使い方を示すためのサンプルコード。
# examples/demo.py
from your_package.module1 import foo

print(foo())

⑦ データフォルダ (data/)

  • CSVやJSONファイル、画像データ等を格納。
  • 特にデータ分析や機械学習系プロジェクトでよく利用される。

推奨ベストプラクティス

  • ソースコードは必ず src/ フォルダ内にまとめる。
  • テストコードを充実させる。
  • 依存関係を requirements.txt または pyproject.toml に明確に記載する。
  • プロジェクト直下には、主要なファイルや設定ファイルのみを置き、整理する。

この構造のメリット

  • 他人や未来の自分が理解しやすい。
  • 再利用やメンテナンスが容易。
  • GitHub等での公開やパッケージ化も簡単。

このような構成を参考にしてプロジェクトを進めると、管理性が向上し、可読性・再利用性の高いプロジェクトになります。

参考資料

https://www.jetbrains.com/help/pycharm/configuring-project-structure.html#mark-dir-settings

Discussion