Python ディレクトリ構造のガイドライン (cline-rule sample)

目的

Python プロジェクトにおけるディレクトリ構造と、パッケージの設定に必要なファイルの書き方についてのガイドラインをまとめる。
この資料は Cline の助けになるよう、議論、技術的な詳細、技巧的な表現は避け、シンプルな説明で構成される。

用語

• module: Python ファイル (.py) 1 つに対応する、Python コードの基本単位。
• import(ing): ある module のPythonコードが、別の module が公開する機能を使えるようにするための処理。
• import path: import する module を検索するパスのリスト。
• package: submodule, subpackage を階層的に含むことができる module.
• regular package: __init__.py を含むディレクトリである、通常の package. より特殊な namespace package と区別して呼ばれる。
• namespace: コード上の名前と、オブジェクトを対応づける仕組み。

See Python3.13 用語集.

使用するツール

• プロジェクト管理: uv
• テスト: pytest
• 静的解析: ruff
• リンティング: pre-commit

ディレクトリ構造

以下のディレクトリ構造をベースに、Python プロジェクトを構築する。
pyproject.toml にパッケージ情報を記載するため setup.py は作成しない。

project-name/
├── CHANGELOG
├── docs
│   ├── changelog.rst
│   ├── conf.py
│   ├── index.rst
│   ├── Makefile
│   ├── readme.rst
│   └── ...
├── examples
│   ├── example1.py
│   └── ...
├── .gitignore
├── LICENSE
├── pyproject.toml
├── README.md
├── src
│   └── public_package_name
│       ├── __init__.py
│       ├── sub_package_name1
│       │   ├── __init__.py
│       │   ├── module_name1.py
│       │   └── ...
│       ├── sub_package_name2
│       │   ├── __init__.py
│       │   ├── module_name2.py
│       │   └── ...
│       ├── module_name3.py
│       └── ...
├── tests
│   ├── __init__.py
│   ├── test_integration1.py
│   ├── test_integration2.py
│   └── ...
└── uv.lock

ディレクトリ構造に関する議論は以下を参照。

• src layout vs flat layout
• ionel's codelog - Packaging a python library

__init__.py の書き方

__init__.py を必ず配置する

Python の regular package は __init__.py ファイルを含むディレクトリであると想定される。
特別な理由が無い限り、すべてのディレクトリに __init__.py ファイルを配置する。

__init__.py の内容

__init__.py はパッケージがインポートされるときに暗黙的に実行され、加えて __init__.py で定義されているオブジェクトが、パッケージの名前空間に追加される。
__init__.py にはパッケージのインポート時に実行したい初期化処理、および外部に公開したいオブジェクトを定義する。

サブパッケージのインポートは相対パスを使い from .sub_package_name import object_name as object_name のように記述する。
一方で from .sub_package_name import * は使用すべきでない。
__all__ および __version__ は使用しない。

from .sub_package_name1 import Class1 as Class1
from .module_name3 import function_name1 as function_name1
# ...

# if necessary, write initialization code here. 
# (e.g., add paths, environment variables to system)

example scripts の書き方

パッケージの使い方を示すためのスクリプトは examples ディレクトリに配置する。
src で定義したパッケージをインポートするためには、以下のコマンドで、パッケージをローカルにインストールする必要がある。

uv pip install -e .

インストールしたパッケージは、 __init__.py が適切に設定されていれば、以下のようにインポートできる。

from public_package_name import Class1
from public_package_name import function_name1

TODO

• pyproject.toml の書き方
• import に関するエラー文への対処
  • https://qiita.com/u943425f/items/bd94a30b52c9296e942d#本題自作モジュールのimportで発生するエラーを解消する
    • python -m <module> オプションで実行する、など。