Pythonの型ヒントとmypyで実行前に誤りを見つける

開発2026年11月22日公開読了目安 約8分

目次
  1. 型ヒントと静的型チェッカーの関係
  2. 型ヒントの基本の書き方
  3. mypyを動かす
  4. 実行前に見つかる誤りの例
  5. 既存のコードに段階的に導入する
  6. 注意点と落とし穴
  7. まとめ

Pythonは変数に型を宣言しなくても動くため、手軽に書ける言語です。
その一方で、関数に想定外の型の値を渡してしまう誤りは、実行してみるまで気付けないことがあります。
とくに、めったに通らない分岐の中にある誤りは、本番で初めて例外になることもあります。
この記事では、型ヒントの基本的な書き方と、mypyで実行前に誤りを見つける手順、導入時に気を付けたい点を整理します。
コード例はPython 3.10以降を前提にしています。

型ヒントと静的型チェッカーの関係

型ヒント(type hints)は、変数や関数の引数・戻り値にどんな型を想定しているかを書き添える記法です。
Pythonの標準仕様として定義されており、関数の注釈の書き方はPEP 484で定められています。

大事な点は、型ヒントそのものが実行時に型を強制しないことです。
次のように書いても、Pythonは注釈を見て処理を止めることはありません。

def double(n: int) -> int:
    return n * 2

print(double("ab"))  # 実行時はエラーにならず、"abab" が表示される

この注釈を読んで、コードを実行せずに矛盾を探すのが、静的型チェッカー(static type checker)です。
代表的なものにmypyがあります。
同様の役割のツールはほかにもありますが、この記事ではmypyを例に説明します。

型ヒントを書く価値は、主に3つあります。

  • 実行前に、型の取り違えを機械的に検出できる。
  • 関数の入出力が注釈として残り、読む人が仕様を推測しなくてよい。
  • エディタの補完やリファクタリングの精度が上がる。

型ヒントの基本の書き方

変数・引数・戻り値

変数や引数には 名前: 型、戻り値には -> 型 を書きます。

name: str = "Celalink"
count: int = 0

def total_price(unit_price: int, quantity: int) -> int:
    return unit_price * quantity

戻り値がない関数には -> None を書きます。

コレクションの型

リストや辞書は、中身の型まで書けます。
Python 3.9以降では、組み込みの list や dict をそのまま使えます。

def average(scores: list[int]) -> float:
    return sum(scores) / len(scores)

def count_words(words: list[str]) -> dict[str, int]:
    result: dict[str, int] = {}
    for w in words:
        result[w] = result.get(w, 0) + 1
    return result

「または」とNone

値が None になりうる場合は、str | None のように書きます。
この | による書き方は、Python 3.10以降で使えます(PEP 604)。
それ以前のバージョンでは、typing モジュールの Optional[str] や Union[str, int] を使います。

def find_user_name(user_id: int) -> str | None:
    users = {1: "佐藤", 2: "鈴木"}
    return users.get(user_id)

mypyを動かす

mypyはpipで導入できます。
プロジェクトの仮想環境に、開発用の依存として入れるのが一般的です。

pip install mypy
mypy app/

指定したファイルやディレクトリを読み込み、型の矛盾があれば行番号つきで表示します。
先ほどの total_price に文字列を渡すと、次のような指摘が出ます。

total_price("100", 3)
error: Argument 1 to "total_price" has incompatible type "str"; expected "int"

文言はバージョンで変わることがあります。

実行前に見つかる誤りの例

型チェックが効果を発揮しやすいのが、None の扱いです。
先ほどの find_user_name は、存在しないIDでは None を返します。
その結果をそのまま文字列として扱うコードを書くと、mypyが指摘します。

name = find_user_name(3)
print(name.upper())  # name は None かもしれない

実行すると、IDが3のときに AttributeError になります。
mypyは、None の可能性を残したまま属性を使っている点を、実行前に報告します。
直し方は、None の場合を先に処理することです。

name = find_user_name(3)
if name is None:
    print("該当するユーザーがいません")
else:
    print(name.upper())

if で None を除いた後の枝では、mypyは name を str として扱います。
このように、条件分岐で型が絞り込まれることを、型の絞り込み(narrowing)と呼びます。

既存のコードに段階的に導入する

すでに動いているコードに、一度にすべての注釈を付けるのは現実的ではありません。
mypyは既定では、注釈のない関数の中身を検査しません(check_untyped_defs という設定が、既定で無効になっているためです)。
この性質を使えば、段階的に導入できます。

進め方の例を示します。

  1. まず mypy を動かし、現状の指摘数を把握する。
  2. 新しく書く関数と、変更する関数から注釈を付ける。
  3. 外部との境界(APIの入出力、設定の読み込み)を優先して注釈を付ける。
  4. CIで mypy を実行し、注釈を付けたモジュールから順に、指摘がない状態を保つ。

設定は pyproject.toml などに書けます。
たとえば、次のように設定します(例として3.11を指定)。

[tool.mypy]
python_version = "3.11"
warn_return_any = true
warn_unused_ignores = true

注釈のない関数そのものを指摘させたいときは、disallow_untyped_defs = true を加えます。
ただし、最初から全体で有効にすると指摘が大量に出るため、モジュール単位で段階的に適用するほうが現実的です。
たとえば、新しく作るパッケージから先に厳しくするには、次のように書きます。

[[tool.mypy.overrides]]
module = "app.api.*"
disallow_untyped_defs = true

末尾の .* で、app.api の配下のモジュールが対象になり、それ以外のモジュールには全体の設定が適用されます。

注意点と落とし穴

型ヒントは実行時の検証の代わりにならない

冒頭で見たとおり、外部から届く値(HTTPリクエストの本文、ファイル、環境変数)は、注釈どおりの型とは限りません。
境界では、入力検証を別に行う必要があります。
FastAPIのようにフレームワークが注釈を使って検証する場合は、その仕組みが検証を担っています。

Anyや型チェックを外すコメントの使いすぎ

Any は「どんな型でもよい」という意味で、チェックを実質的に止めます。
# type: ignore も、その行の指摘を黙らせます。
どちらも、使うこと自体は間違いではありません。
ただし、増えるほど型チェックの効果が薄れるため、理由をコメントに残し、数を把握しておきます。
前述の warn_unused_ignores を有効にすると、不要になった type: ignore を見つけられます。

ライブラリの型情報

型情報を提供していないライブラリを読み込むと、mypyは「型情報(stub)が見つからない」という趣旨の指摘を出します(例: Library stubs not installed for "requests")。
型情報が別パッケージで配布されている場合は、それを開発用の依存に加えます(例: requestsにはtypes-requestsがあります)。
別パッケージがない場合は、そのライブラリだけ指摘を止めます。

[[tool.mypy.overrides]]
module = ["somelib.*"]
ignore_missing_imports = true

この場合、somelib は Any として扱われ、その使い方の誤りは検出されなくなります。
設定はプロジェクト全体ではなく、該当するモジュールに限って書くと、他の箇所の検査は弱まりません。

まとめ

型ヒントは、実行時の挙動を変えず、コードに入出力の約束を書き添える仕組みです。
その約束をmypyで機械的に検査することで、型の取り違えや None の扱い漏れを実行前に見つけられます。

導入は、新しく書く関数と外部との境界から始め、注釈を付けたモジュールから順にCIで指摘がない状態を保つ形が現実的です。
厳しい設定も、検査を止める設定も、範囲をモジュール単位に限ると、検査の効果を保てます。

参考資料・出典

コラム一覧を見る »