Python
PR

Pythonの型ヒント入門|typingの書き方とmypyで型の間違いを見つける方法

Pythonの型ヒント入門|typingの書き方とmypyで型の間違いを見つける方法
hr
記事内に商品プロモーションを含む場合があります

Python のコードで def add(a: int, b: int) -> int: のような書き方を見たことはありませんか。: int や -> int の部分を型ヒントといいます。「この引数には整数を渡してほしい」「この関数は整数を返す」という目印をコードに書いておく仕組みです。

この記事では、型ヒントが実行時には何もチェックしないことを実際に確かめたうえで、関数・変数・リスト・辞書への書き方、int | None と Optional の関係、Union・Callable・TypedDict、Python 3.12 で入った type 文、そして mypy で型の間違いを見つける方法と、既存のコードに少しずつ入れていく考え方までを説明します。載せている出力は、Windows 11・Python 3.12.6・mypy 2.4.0 で実際に実行して確かめたものです。

型ヒントとは

Python は、変数に入れる値の種類(型)を前もって決めなくてよい言語です。同じ変数に数値を入れたあと文字列を入れても動きます。手軽な反面、「この関数に何を渡せばよいのか」がコードから読み取りにくく、間違った型を渡しても実行するまで気づけません。

そこで Python 3.5 で、型を書き添えるための決まりが PEP 484 として作られました。PEP は Python の仕様を提案・記録する文書です。PEP 484 には「Python は動的型付けの言語のままであり、型ヒントを必須にするつもりはない」とはっきり書かれています。型ヒントはあくまで任意の目印です。

実行時にはチェックされない

ここが一番大事な点です。次のコードを sample.py という名前で保存します。add は整数を受け取る関数ですが、2 回目は文字列を渡しています。

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

print(add(1, 2))
print(add("1", "2"))
print(add.__annotations__)

PowerShell で、sample.py を保存したフォルダーに移動してから実行します。

py sample.py
3
12
{'a': <class 'int'>, 'b': <class 'int'>, 'return': <class 'int'>}

文字列を渡してもエラーにならず、"1" + "2" がつながって 12 になりました。型ヒントは __annotations__ という属性に記録されるだけで、Python 本体は中身を確かめません。公式ドキュメントの typing のページにも「Python のランタイムは、関数と変数の型注釈を強制しない。型チェッカーや IDE、リンターなどのサードパーティーのツールが使うためのものだ」という趣旨の注意書きがあります。

それでも書く理由

  • 実行する前に間違いが見つかる:mypy などの型チェッカー(型ヒントを読んでコードの矛盾を探すツール)にかけると、上の add("1", "2") をエラーとして教えてくれます
  • 読む人に意図が伝わる:関数の 1 行目を見るだけで、何を渡して何が返るのかが分かります
  • エディターが手伝いやすくなる:VS Code などが変数の型を知る手がかりになります

基本の書き方

関数の引数と戻り値

引数は 引数名: 型、戻り値(関数が返す値)は閉じかっこのあとに -> 型 と書きます。既定値がある引数は times: int = 1 のように型のあとに書きます。何も返さない関数の戻り値は None です。

def greet(name: str, times: int = 1) -> None:
    print(("こんにちは、" + name + "さん ") * times)

def is_adult(age: int) -> bool:
    return age >= 18

greet("田中", times=2)
print(is_adult(20))
こんにちは、田中さん こんにちは、田中さん
True

変数

変数にも count: int = 0 のように書けます。ただし、count = 0 と書けば型チェッカーは右辺から int だと推測(型推論)してくれるので、すべての変数に書く必要はありません。変数に書くのは、空のリストや辞書のように右辺だけでは中身の型が分からないときが中心です。

list[int]・dict[str, int](3.9 から組み込み型で書ける)

リストや辞書は、中に入る値の型を角かっこで書きます。list[int] は「整数のリスト」、dict[str, int] は「キーが文字列で値が整数の辞書」です。

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

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

print(total([100, 200, 300]))
print(count_words(["a", "b", "a"]))
point: tuple[int, int] = (3, 4)
tags: set[str] = {"python"}
print(point, tags)
600
{'a': 2, 'b': 1}
(3, 4) {'python'}

古い記事やコードでは from typing import List, Dict として List[int]・Dict[str, int] と書いていることがあります。Python 3.9 から組み込みの list や dict にそのまま角かっこを付けられるようになり(PEP 585)、公式ドキュメントでは typing.List や typing.Dict は「3.9 から非推奨」とされています。今から書くなら小文字の list[int] で十分です。

よく使う書き方を表にまとめます。

書き方意味使える版
int・str・float・bool整数・文字列・小数・真偽値3.5 以降
list[int]整数のリスト3.9 以降
dict[str, int]キーが文字列、値が整数の辞書3.9 以降
tuple[int, int]整数 2 つの組3.9 以降
str | None文字列または None3.10 以降
Callable[[int], str]int を受け取り str を返す関数—
type 名前 = 型型に名前を付ける3.12 以降

None かもしれない値:X | None と Optional

「見つかれば名前、見つからなければ None を返す」関数はよくあります。この戻り値は str | None(文字列または None)と書きます。| で型をつなぐ書き方は Python 3.10 で入りました(PEP 604)。

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

name = find_user(3)
print(name)
print(name.upper())
None
Traceback (most recent call last):
  ...
AttributeError: 'NoneType' object has no attribute 'upper'

ID が 3 のユーザーはいないので name は None になり、upper() でエラーになりました。テストで ID 3 を試さない限り見逃しがちなバグですが、後で説明する mypy なら実行せずに見つけられます。直すには、None のときの処理を先に書きます。

name = find_user(3)
if name is None:
    print("見つかりません")
else:
    print(name.upper())

こう分けると、型チェッカーは else の中の name を str と判断します。

Optional との関係

3.9 以前のコードでは、同じ意味を Optional[str] と書きます。公式ドキュメントには「Optional[X] は X | None(または Union[X, None])と同じ」とあります。実際に比べると等しくなりました。

from typing import Optional, Union

print(Optional[int] == (int | None))
print(Union[int, float] == (int | float))
print(isinstance(3, int | str))
True
True
True

3 行目のように、int | str は isinstance にも渡せます(PEP 604)。3.10 以降で動かすなら、import が要らない X | None がおすすめです。

Union と Callable

Union[int, float] は「int か float のどちらか」という意味で、3.10 以降は int | float と書けます。上で確かめたとおり、2 つは同じものです。

Callable:関数を受け取る引数

関数を引数に渡すときは Callable[[引数の型, ...], 戻り値の型] と書きます。公式ドキュメントでは typing.Callable は非推奨とされ、collections.abc から import する形が勧められています。

from collections.abc import Callable

def apply(func: Callable[[int], int], value: int) -> int:
    return func(value)

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

print(apply(double, 5))
print(apply(lambda x: x + 1, 5))
print(apply(str, 5))
10
6
5

3 行目の apply(str, 5) は、int を返すはずの場所で文字列 "5" を返していますが、実行時は何事もなく表示されます。mypy にかけると次のように指摘されました。

sample.py:11: error: Argument 1 to "apply" has incompatible type "type[str]"; expected "Callable[[int], int]"  [arg-type]

TypedDict:辞書のキーと値の型を決める

JSON を読み込んだ辞書のように、「name は文字列、age は整数」とキーごとに型が違う辞書には TypedDict を使います。公式ドキュメントにあるとおり、実行時の中身は普通の辞書で、チェックするのは型チェッカーだけです。

from typing import TypedDict

class User(TypedDict):
    name: str
    age: int

u: User = {"name": "田中", "age": 25}
print(u, type(u))
bad: User = {"name": "佐藤", "age": "30"}
missing: User = {"name": "鈴木"}
print(u["email"])

実行すると、1 行目の print は {'name': '田中', 'age': 25} <class 'dict'> と表示され、age が文字列の辞書やキーが足りない辞書もそのまま作られます。最後の行で初めて KeyError: 'email' になりました。mypy では、3 つとも実行前に見つかります。

sample.py:9: error: Incompatible types (expression has type "str", TypedDict item "age" has type "int")  [typeddict-item]
sample.py:10: error: Missing key "age" for TypedDict "User"  [typeddict-item]
sample.py:11: error: TypedDict "User" has no key "email"  [typeddict-item]
Found 3 errors in 1 file (checked 1 source file)

キーを省略してよいことにしたいときは class User(TypedDict, total=False): と書きます。値を書き換えたりメソッドを持たせたりするなら、辞書ではなく dataclass のほうが向いています。

type 文で型に名前を付ける(3.12 から)

dict[str, list[int]] のような長い型を何度も書くのは大変です。Python 3.12 から、type 文で型に名前(型エイリアス)を付けられるようになりました(PEP 695)。

type UserId = int
type Scores = dict[str, list[int]]

def average(scores: Scores, name: str) -> float:
    values = scores[name]
    return sum(values) / len(values)

data: Scores = {"田中": [80, 90], "佐藤": [70]}
print(average(data, "田中"))
print(UserId, type(UserId), UserId.__value__)
85.0
UserId <class 'typing.TypeAliasType'> <class 'int'>

type 文で作った名前は TypeAliasType という特別なオブジェクトになり、中身は __value__ で取り出せます。PEP 695 によると、中身は使われるまで評価されないので、あとで定義するクラスの名前も引用符なしで書けます。type 文は 3.11 以前では使えないため、古い版でも動かす必要があるコードでは Scores = dict[str, list[int]] のような普通の代入で代用します。

mypy で型の間違いを見つける

mypy は、型ヒントを読んでコードの矛盾を探す、代表的な型チェッカーです。コードは実行せず、読むだけで調べます(これを静的なチェックといいます)。PyPI(Python のパッケージ置き場)では、2026 年 10 月 19 日時点の最新版は 2.4.0 で、Python 3.10 以上が必要です。

仮想環境に入れる

プロジェクトの仮想環境(venv)に入れるのがおすすめです。プロジェクトのフォルダーで、次の 3 つを順に実行します。

py -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install mypy

2 つ目でスクリプトの実行が止められる場合や、venv そのものの説明は「Pythonの仮想環境venvの使い方」を見てください。入ったかどうかは次のコマンドで確かめます。

mypy --version
mypy 2.4.0 (compiled: yes)

実行してエラーを読む

最初の「実行時にはチェックされない」で使った sample.py(add("1", "2") を含むもの)を調べます。

mypy sample.py
sample.py:5: error: Argument 1 to "add" has incompatible type "str"; expected "int"  [arg-type]
sample.py:5: error: Argument 2 to "add" has incompatible type "str"; expected "int"  [arg-type]
Found 2 errors in 1 file (checked 1 source file)

1 行は「ファイル名:行番号: error: 内容 [エラーの種類]」の形で、「add の 1 つ目の引数の型 str は合わない。int のはず」という意味です。[arg-type] はエラーの種類の名前(エラーコード)で、後で説明する「このエラーだけ無視する」ときに使います。問題がなければ Success: no issues found in 1 source file と表示されます。

None の章の name.upper() のコードを調べると、次のように出ました。「str | None のうち None のほうには upper がない」という意味です。if name is None: で分けたコードでは Success になりました。

sample.py:7: error: Item "None" of "str | None" has no attribute "upper"  [union-attr]
Found 1 error in 1 file (checked 1 source file)

ほかに、よく見るエラーを集めたコードです。7 行目は、何も返さない関数(-> None)の結果を変数に入れようとしているという指摘です。

def greet(name: str, times: int = 1) -> None:
    print(("こんにちは、" + name + "さん ") * times)

greet("田中")
greet(42)
count: int = "ten"
result: str = greet("佐藤")
sample.py:5: error: Argument 1 to "greet" has incompatible type "int"; expected "str"  [arg-type]
sample.py:6: error: Incompatible types in assignment (expression has type "str", variable has type "int")  [assignment]
sample.py:7: error: "greet" does not return a value (it only ever returns None)  [func-returns-value]
sample.py:7: error: Incompatible types in assignment (expression has type "None", variable has type "str")  [assignment]
Found 4 errors in 1 file (checked 1 source file)

型ヒントのない関数は、既定ではチェックされない

mypy の公式ドキュメントには「型ヒントのない関数は動的型付けとみなし、既定ではチェックしない」とあります。次のコードは明らかにおかしいのですが、そのまま mypy にかけるとエラーになりません。

def add(a, b):
    return a + b

def main():
    x: int = "abc"
    return add(1, "2")
sample.py:5: note: By default the bodies of untyped functions are not checked, consider using --check-untyped-defs  [annotation-unchecked]
Success: no issues found in 1 source file

note(お知らせ)のとおり --check-untyped-defs を付けると、型ヒントのない関数の中も調べます。

mypy --check-untyped-defs sample.py
sample.py:5: error: Incompatible types in assignment (expression has type "str", variable has type "int")  [assignment]
Found 1 error in 1 file (checked 1 source file)

厳しいチェックをまとめて有効にする --strict を付けると、型ヒントを書き忘れた関数まで指摘されます。

mypy --strict sample.py

実行すると、上の assignment のエラーに加えて Function is missing a type annotation [no-untyped-def](関数に型ヒントがない)など 3 つのエラーが増え、合計 4 つになりました。

オプションは、プロジェクトのフォルダーの pyproject.toml に次のように書いておくこともできます。この状態で mypy sample.py を実行すると、--check-untyped-defs を付けたときと同じエラーが出ました。

[tool.mypy]
check_untyped_defs = true

VS Code で型ヒントを生かす

VS Code の公式ドキュメントによると、Python 拡張の既定の言語サーバー(補完やエラー表示を受け持つ部品)である Pylance は、Microsoft の型チェッカー Pyright をもとにしていて、補完(IntelliSense)を提供します。型ヒントがあれば、たとえば str | None と書いた変数がどの型なのかをエディターが判断する材料になります。

型の間違いをエディター上にも表示させたいときは、設定の python.analysis.typeCheckingMode を使います。公式の設定一覧では既定値は off で、basic・strict の順に厳しくなると説明されています。まずは basic から試すとよいでしょう。設定画面の開き方などは「VS Codeの便利なショートカットキー」も参考にしてください。

段階的に導入する考え方

型ヒントは「全部に書くか、まったく書かないか」ではありません。書いたところだけがチェックされ、書いていない関数は既定では素通りするので、少しずつ増やしていけます。mypy の公式ドキュメントでも、既存のコードには一度に全部ではなく少しずつ型ヒントを足していくほうが楽だとされています。進め方の例です。

  1. 新しく書く関数と、よく呼ばれる共通の関数の引数・戻り値から書き始める
  2. まず一部のファイルだけ mypy が Success になる状態を作り、毎回同じコマンド(できれば設定ファイル)で実行する
  3. 慣れてきたら check_untyped_defs = true を有効にする(mypy のドキュメントでも早めの有効化を強く勧めています)
  4. 最終的に --strict で通ることを目標にする

今は直せない行は、行末に # type: ignore[assignment] のようにエラーコードを付けて書くと、その行のそのエラーだけを無視できます。試したところ、付けた行のエラーだけが消えました。使いすぎないようにしましょう。

よくある間違い

Optional は「省略できる引数」ではない

Optional[str] は「None も入れてよい」という意味で、引数を省略してよいという意味ではありません。

from typing import Optional

def greet(name: Optional[str]) -> str:
    return f"こんにちは、{name or 'ゲスト'}さん"

print(greet(None))
print(greet())

1 つ目は「こんにちは、ゲストさん」と表示されますが、2 つ目は TypeError: greet() missing 1 required positional argument: 'name' になりました。mypy も Missing positional argument "name" in call to "greet" [call-arg] と指摘します。省略できるようにするには name: str | None = None と既定値を付けます。

空のリストに型が付かない

関数の中で result = [] と書いてそのまま返すと、mypy は中身の型を決められず、次のエラーになります。ヒントのとおり result: list[int] = [] と書けば消えます。

sample.py:10: error: Need type annotation for "result" (hint: "result: list[<type>] = ...")  [var-annotated]

return を書き忘れた道がある

次の関数は、code が見つからないときに何も返さず、実際には None が返ります。戻り値を -> int にしていると、mypy が見つけてくれます。

def get_price(code: str) -> int:
    prices = {"A": 100, "B": 200}
    if code in prices:
        return prices[code]
sample.py:1: error: Missing return statement  [return]

見つからないときに例外を出すか、戻り値を int | None にして呼び出し側で None を扱うかを決めて直します。

よくある質問

型ヒントを書くと、実行時に型が強制されますか?

型は強制されません。最初に確かめたとおり、間違った型を渡してもそのまま動きます(PEP 484 にも「実行時には型チェックは行われない」とあります)。実行時にも値を確かめたいときは、isinstance で自分で調べるか、dataclass の __post_init__ などで確認する処理を書きます。

古い Python でも list[int] や int | None は使えますか?

公式ドキュメントでは、組み込みの list などに角かっこを付けられるのは 3.9 から、X | Y の書き方は 3.10 から、type 文は 3.12 からです。それより古い版で動かす必要がある場合は、typing.List・Optional・Union を使います(この記事では 3.12 以外の版では試していません)。

まとめ

  • 型ヒントは目印で、Python は実行時にチェックしない。間違いは mypy などの型チェッカーで見つける
  • 引数は name: str、戻り値は -> int、中身の型は list[int]・dict[str, int]
  • None かもしれない値は str | None(Optional[str] と同じ)。使う前に is None で分ける
  • mypy は型ヒントのない関数を既定では調べない。少しずつ書き足して、check_untyped_defs、--strict へ進める

関連する記事・ツール

ABOUT ME
hr
hr
エンジニアとして働いている hr です。仕事や資格勉強で「こんなツールがあれば」と感じたものを、無料Webツールと解説記事にして発信しています。
記事URLをコピーしました