[Python] 小規模ツールのディレクトリ構造

はじめに

Pythonを用いた作成物を開発する際に
自分が採用しているディレクトリ構造についてまとめたものです。

ディレクトリの名称や構造が適切なものでないと
保守性が低下し、引き継ぎを行う際の大きな障害となり得ます。
その苦い経験もあり自分なりに考えた構造の共有です。

ディレクトリ構造図

.
└── project_dir
    ├── config
    ├── data
    │   ├── input
    │   ├── output
    │   └── working
    ├── log
    └── src
        ├── errors
        ├── lib
        ├── models
        ├── services
        ├── typings
        └── utils

各ディレクトリの利用用途

config

プログラムの処理中で利用する固定値や
パラメーターを記載したファイルを格納するディレクトリです。

data

処理の中で利用するファイル群を配置するディレクトリです。
役割により分割した、以下の子ディレクトリも利用します。
子ディレクトリの名称は、作成物によってより具体的なものに変更する場合もあります。

• input

  • 処理で利用する入力ファイルを配置するディレクトリです。

• output

  • 処理で作成した出力ファイルを配置するディレクトリです。

• working

  • 一般的にワーキングディレクトリと呼ばれるものであり、
    処理の途中・加工中のファイルを入れておくディレクトリです。

log

ログファイルを格納するディレクトリです。

src

処理を記載したファイル群を格納するディレクトリです。
src配下に処理を記載したコードが入っていると直感的にわかるようにします。

errors

自作エラークラスを記載したファイルを格納するディレクトリです。

lib

自作ライブラリを格納するディレクトリです。

models

dataclassを定義したファイルを格納するディレクトリです。
作生物によっては利用しない場合もあるので、その際は削除しておく。

services

作成物における、ビジネスロジック・コアロジックを記載した
ファイルを格納しておくディレクトリです。

typings

型定義を記載したファイルを格納するディレクトリです。
Python3.10以降は、型定義がより便利に行えるようになったのもあり
別ファイルに定義し呼び出せるようにします。

なぜ、「typings」という名称にしたか？

当初は「types」というディレクトリ名も候補にしていましたが、
配下に型定義ファイルと一緒に入れておく、init.pyファイル内を開いてみると
オレンジ色で以下の警告が表示されており、候補から外した背景があります。

"~/src/types/__init__.py" は stdlib モジュール "types" をオーバーライドしています

utils

自作ユーティリティを格納するディレクトリです。

あとがき

記載した構造は、主に小規模なツールを作成する場合を想定しています。
しかし、小規模であってもディレクトリ構造の設計がよく考えられていないと
後から自分で保守する場合や後任に引き継ぐ際の支障となります。

逆に設計が上手くなされていた場合には、
直感的に、どこにどの役割のファイルが配置されているかがわかりますし
引き継ぎを行う際の説明も話しやすくなるので大事なポイントだと考えています。