Python typingモジュールとは？型ヒントの書き方を初心者向けに解説

Pythonのtypingモジュールは、変数や関数に「どんな型が入るか」を書き添えるための仕組みです。

書いても実行時の動作は変わりません。代わりに、エディタの補完とエラー検出が効くようになり、型チェッカーがバグを見つけてくれます。

型ヒントは実行時に強制されない

ここを最初に理解しておくと、以降の話が一本の線でつながります。

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

print(greet("佐藤"))
print(greet(123))

実行結果：

Hello, 佐藤
TypeError: can only concatenate str (not "int") to str

エラーは出ましたが、これは型ヒントが止めたのではありません。文字列と数値を+でつなごうとして失敗しただけです。

Pythonはname: strを見ても何もチェックしません。実際、書き込まれるのは辞書1つだけです。

def f(a: int, b: str = "x") -> bool: ...

print(f.__annotations__)

実行結果：

{'a': <class 'int'>, 'b': <class 'str'>, 'return': <class 'bool'>}

価値を生むのは型チェッカーです。代表的なのがmypyで、コードを実行せずに矛盾を見つけます。

# a1.py
def greet(name: str) -> str:
    return "Hello, " + name

greet(123)

$ mypy a1.py
a1.py:4: error: Argument 1 to "greet" has incompatible type "int"; expected "str"  [arg-type]

実行する前に間違いが分かりました。テストを通さないと気づけなかったバグを、書いた瞬間に潰せます。

age: int = 28
name: str = "佐藤"
scores: list = []

def add(a: int, b: int) -> int:
    return a + b

def show(msg: str) -> None:
    print(msg)

def total(nums: list[int]) -> int:
    return sum(nums)

print(total([1, 2, 3]))

実行結果：

listだけでは「リストである」としか伝わりません。list[int]と書けば中身が整数だと分かります。

$ mypy a9.py
a9.py:5: error: List item 0 has incompatible type "str"; expected "int"  [list-item]

この書き方はPython 3.9以降で使えます。詳しくは「Python list[int]・dict[str, int]とは？コレクションの型ヒントの書き方」で解説しています。

型ヒントは仕様の変化が速く、ネットの記事が古い書き方のままということがよくあります。

やりたいこと	古い書き方	新しい書き方	使える版
整数のリスト	`List[int]`	`list[int]`	3.9以降
文字列か数値	`Union[int, str]`	`int \| str`	3.10以降
Noneを許す	`Optional[str]`	`str \| None`	3.10以降

Python 3.9で|を使うとエラーになります。

x = int | str

実行結果（Python 3.9）：

TypeError: unsupported operand type(s) for |: 'type' and 'type'

対象とするPythonのバージョンで書き方を決めてください。古い環境も想定するライブラリでは、typingからimportする書き方のほうが安全です。

$ pip install mypy
$ mypy your_script.py

いきなり全ファイルに適用するとエラーが大量に出て心が折れます。次の順序がおすすめです。

型ヒントは全部書かなくても効果があります。書いた部分だけチェックされ、書いていない部分は素通りするだけです。