型ヒント — : 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 つの場面