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 という設定が、既定で無効になっているためです)。
この性質を使えば、段階的に導入できます。
進め方の例を示します。
- まず
mypyを動かし、現状の指摘数を把握する。 - 新しく書く関数と、変更する関数から注釈を付ける。
- 外部との境界(APIの入出力、設定の読み込み)を優先して注釈を付ける。
- 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で指摘がない状態を保つ形が現実的です。
厳しい設定も、検査を止める設定も、範囲をモジュール単位に限ると、検査の効果を保てます。