もろえのお気に召すまま。
記事一覧に戻る

Django プロジェクトにコード品質チェックを導入して開発効率アップする方法

僕はフロントエンド開発をメインに経験してきました。ESLint や Prettierといった静的解析ツールやフォーマッターが導入されていたプロジェクトを経験した後で導入されていないプロジェクトにアサインされるとストレスを強く感じてしまいます。これらのツールはプロジェクトの初期段階で導入しておかないと大幅にコードが変更されたり、変更されたことで画面表示に影響が及ぶ可能性があったりするため、途中から利用できないんですよね。
今年に入って Django 環境のプロジェクトを経験しているのですが、静的解析ツールやフォーマッターが利用されている形跡もなく、Python でもそのようなツールがあるのか気になって調べてみました。自分が学習用に進めている環境に導入して実際に利用してみた以下の5つのツールについて紹介していきます。

  • flake8：コードスタイルとバグ検出のLinter
  • black：Prettierのようなコードフォーマッター
  • isort：import文を整理整頓
  • mypy：型ヒントをもとに静的な型チェックを行うツール
  • pre-commit：コミット前にツールを自動で実行するための仕組み

flake8

コードスタイルと潜在的なバグを検出するためのLinter。JavaScriptでいうESLint的立ち位置。以下の項目を自動でチェックします。

  • PEP8（Pythonの公式スタイルガイド）違反
  • 未使用の変数・import
  • 曖昧な構文・可読性の低いコード
  • 潜在的なバグ（プラグイン追加で対応可能）

インストール方法

pip install flake8

設定ファイル

Gitリポジトリのルートに.flake8ファイルを作成して、以下のような設定を記載します。うっかりDjangoプロジェクトの直下に配置しないように注意してください。

[flake8]
max-line-length = 120
exclude = .git,__pycache__,migrations,venv
ignore = E203, W503
  • max-line-length: 行の最大長（デフォルト79文字 → 120文字に拡張）
  • exclude: 対象から外すディレクトリ
  • ignore: 警告コードを無視。E203は: の前の空白など細かいフォーマット。W503は、改行位置でのバイナリ演算子。

使い方

ファイル単位でチェックしたい場合

flake8 your_file.py

ディレクトリ全体でチェックする場合

flake8 .

black

Pythonコードの見た目を強制的に統一する自動整形ツール。JavaScriptでいうPrettier的立ち位置。blackのルールに従った整形が行われる。

インストール方法

pip install black

使い方

ファイル単位に実行したい場合

black your_file.py

ディレクトリ全体に適用する場合

black .

isort

isortはimport sortの略でimport文を自動整列、グループ化が可能です。標準ライブラリ → サードパーティ → ローカルモジュールの順に並べ替えを行えます。

インストール方法

pip install isort

使い方

ファイル単位に実行したい場合

isort your_file.py

ディレクトリ全体に適用する場合

isort .

mypy

コードの型チェックを静的に行うツール。変数や関数の使い方のミスを事前に検出できる。

型ヒントとは？

Python では関数や変数に対して「この値はこの型です」という型ヒント（type hint）を記述することができます。mypy はこれをもとに型の不一致をチェックします。

def greet(name: str) -> str:
  return "Hello " + name

この例では name は文字列（str）、戻り値も文字列型であることを表しています。
もう少し複雑な例：

from typing import List, Optional, Dict

def total(numbers: List[int]) -> int:
  return sum(numbers)

def find_user(uid: int) -> Optional[Dict[str, str]]:
  ...

このように型ヒントを活用することで、エディタの補完が賢くなったり、意図しない型のバグを mypy によって実行前に検出できます。

インストール方法

pip install mypy

設定ファイル

プロジェクトルートのディレクトリに mypy.ini ファイルを作成して、以下のような設定を記載します。

[mypy]
python_version = 3.11
ignore_missing_imports = True
exclude = (^|/)migrations/
  • ignore_missing_imports: 型情報がないライブラリのエラーを無視
  • exclude: migrations/ など自動生成ファイルを除外

使い方

ファイル単位にチェックしたい場合

mypy your_file.py

ディレクトリ全体にチェックする場合

mypy .

pre-commit

前述したLinterや静的解析ツールを導入してコミット前に実行するルールをチームで作ったとしても人間なので実行忘れがあると思います。
pre-commitはGitのフック機能を利用して、コミット前にコードを自動チェック・整形・検証するツールです。Pythonだけではなく、多言語対応しています。

インストール方法

pip install pre-commit

有効化

以下のコマンドを実行して.git/hooks/pre-commit を有効にします。

pre-commit install

設定ファイル

Gitリポジトリのルートに .pre-commit-config.yaml ファイルを作成して、以下のような設定を記載します。

repos:
  - repo: https://github.com/pre-commit/mirrors-isort
    rev: v5.10.1
    hooks:
      - id: isort

  - repo: https://github.com/psf/black
    rev: 25.1.0
    hooks:
      - id: black

  - repo: https://github.com/pycqa/flake8
    rev: 7.2.0
    hooks:
      - id: flake8

  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.15.0
    hooks:
      - id: mypy
        args:
          - "--config-file=mypy.ini"
          - "--disable-error-code=var-annotated" # 自動生成で出る型注釈エラーを無視
  • --config-file=mypy.ini: デフォルトではmypyはmypy.ini を参照するが、明示的に指定しています。
  • --disable-error-code=var-annotated : 特定のエラー（var-annotated）を無視します。

使い方

手動で全ファイルチェックしたい場合

pre-commit run --all-files

注意点

整形が発生した場合はcommitが行われないため、修正ファイルを再度ステージングしてコミットする必要があります。

最後に

プロジェクトのメンバーが複数いたり、メンバーが入れ替わったりするとエンジニアによって書き方が分かれて統一感のないソースコードが生まれてしまいます。
今後アサインされるメンバーのためにもスタート時から導入してそういうところで余計な考えを起こさず、開発に集中できる環境づくりが大事だと思います。