型ヒント — : int -> str でコードに意図を残す

コードに 「ここには何が入るか」 という意図を残す道具 — 型ヒント（type hints） を整理します。Python 3.5 で導入され、バージョンアップごとに表現力が拡張されてきました。

動的型付け言語ゆえの「型が見えない」問題

Python は 動的型付け言語 です。value = 10 とすれば int、value = "HELLO" と書き直せばその瞬間から str。同じ変数に いつでも違う型 を入れ直せる柔軟さがある反面、規模が大きくなったりチームで触ったりするにつれ、「この変数には何が入っているのか」「この関数は何を返すのか」が コードを読むだけでは分からなくなる という課題が生じます。

型ヒントは、この情報を注釈として残すためのもので、実行時の挙動は変わりません。代わりに、人間が読むときの手がかり と、IDE / 静的解析ツールが事前にエラーを発見するヒント として大きな価値を持ちます。

関数シグネチャに型ヒントを書く

型ヒントの メイン舞台は関数シグネチャ です。引数は 引数名: 型 の形でコロンの後に型を書き、戻り値は -> 型 という矢印で関数定義の末尾に書きます。

# ❌ 型ヒントなし — シグネチャから何を渡すか読み取れない
def calc_tax(price, rate):
    return int(price * (1 + rate))


# ✅ 型ヒントあり — int を渡して int が返ることが一目瞭然
def calc_tax(price: int, rate: float) -> int:
    return int(price * (1 + rate))


print(calc_tax(price=1000, rate=0.1))   # 1100

ECサイトの税込み価格を計算する calc_tax に、引数と戻り値の型ヒント を追加します。

① def calc_tax(price, rate): の引数部分に price: int と rate: float の型ヒントを付けてください。

② 関数の戻り値の型として、): の前に -> int を付けてください。

③ 関数の中身は return int(price * (1 + rate)) のままにしてください。

④ print(calc_tax(price=1000, rate=0.1)) で動作確認をしてください（1100 が表示される想定）。

（正しく実行できれば解説が表示されます）

変数注釈 — 書くべき場面と書かない方がよい場面

型ヒントは 変数の宣言 にも書けます。書き方は関数引数と同じく 変数名: 型 = 値 の形式です。ただし変数注釈は 書きすぎるとコードが冗長 になり、可読性をむしろ下げます。

# ❌ 冗長な書き方 — 値を見れば型は明らかなので注釈は不要
name: str = "Alice"
age:  int = 30

# ✅ 注釈する価値のある書き方 — 中身が空 / 後で代入される / 型が読み取りにくい
results: list = []                       # 後で何かを append する空リスト
cache:   dict = {}                       # 値の型まで書きたければ後で詳述
user_id: int  = fetch_id_from_session()  # 戻り値の型を呼び出し側でも明示

迷ったら「関数は必須・変数は控えめ」

実プロジェクトでは 関数とメソッドのシグネチャには必ず 型ヒントを書き、変数注釈は推測しづらいときだけ 添えるのが標準的なバランスです。age = 30 のような自明な代入は型ヒントを足してもノイズになるだけ、と覚えておきましょう。

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

型ヒントは あくまでヒント です。Python は実行時に型を チェックも強制もしません。def f(x: int) と書いてある関数に f("abc") を渡しても、関数は 普通に呼び出されます — その後で 計算ロジック側で型が合わないとき に初めて TypeError などのランタイムエラーが出るだけで、型ヒント自体が「違反」を検出することはありません。

では何のために書くのか — それは 関数を呼び出す前に エディタや静的解析ツール が型不一致を発見できるからです。VS Code の Pylance / PyCharm / mypy / pyright といったツールは、型ヒントを根拠に 赤線で警告 を出してくれて、実行する前にバグの芽を摘めます。

ブラウザの Python ランナーでは IDE の警告は見えない

このページのコンソールは コードを実行するだけ で、VS Code のような 静的型チェック機能は持ちません。そのため、型ヒントを書いても／違反する値を渡しても、画面上に赤線や事前警告は 一切表示されません。

ユーザー情報を扱う User クラスと、それを使う関数 describe_user の 両方 に型ヒントを付けます。

① class User: を定義し、__init__(self, name: str, age: int) で self.name = name / self.age = age を代入してください（コンストラクタの引数 にも型ヒントを付ける）。

② インスタンスメソッド greet(self) -> str を定義し、return f"こんにちは、{self.name}さん" を返してください（戻り値の型注釈 を忘れずに）。

③ クラスの外側に関数 describe_user(user: User) -> str を定義し、User 型 を引数に取り、return f"{user.name}さん（{user.age}歳）" を返してください。

④ user = User("田中", 30) を作り、print(user.greet()) と print(describe_user(user)) を順に呼んで動作確認をしてください。

型ヒントが効く 3 つの場面