Pythonのタイプヒント入門：変数や関数に型情報を付与して可読性を高める方法

2025年11月29日

Pythonは「動的型付け言語」であり、変数の型（整数、文字列など）を宣言せずにコードを書ける手軽さが魅力です。しかし、大規模な開発やチーム開発においては、「この関数にはどんなデータを渡せばいいの？」「戻り値は何？」といった混乱が生じやすく、バグの原因にもなります。

そこでPython 3.5から導入されたのが**「タイプヒント（Type Hints）」**です。これは変数や関数の引数・戻り値に「期待される型」を注釈（アノテーション）として記述できる機能です。

この記事では、タイプヒントの基本的な書き方と、そのメリットについて解説します。

タイプヒントとは

タイプヒントは、あくまで「ヒント」であり、Pythonの実行時には無視されます。型が違っていてもエラーにはならず、プログラムは動きます。

しかし、VS CodeやPyCharmなどのエディタや、静的解析ツール（mypyなど）を使用することで、コードを書いている段階で「型が間違っています」と警告を出してくれるようになり、バグを未然に防ぐことができます。

変数への型アノテーション

変数を定義する際、変数名の後ろに : 型名 を記述します。

# ゲームのキャラクターステータスを定義する例

# 文字列型 (str)
hero_name: str = "Arthur"

# 整数型 (int)
current_hp: int = 2500

# ブール型 (bool)
is_poisoned: bool = False

print(f"名前: {hero_name} (HP: {current_hp}) 毒状態: {is_poisoned}")

このように書くことで、「current_hp には数値が入るべきであり、文字列を入れてはいけない」という意図がコード上で明確になります。

関数への型アノテーション

関数の引数と戻り値にも型を指定できます。

引数: 引数名: 型名
戻り値: def 関数名(...) -> 型名:

具体的なコード例

攻撃力と防御力を受け取り、ダメージ計算を行って結果のメッセージ（文字列）を返す関数を作成します。

def calculate_battle_result(attacker_atk: int, target_def: int, is_critical: bool) -> str:
    """
    戦闘結果のメッセージを作成する関数
    """
    # ダメージ計算（単純な引き算）
    damage = attacker_atk - target_def
    
    # クリティカルヒットの場合は2倍
    if is_critical:
        damage *= 2
    
    # ダメージが負にならないように調整
    if damage < 0:
        damage = 0
    
    return f"敵に {damage} のダメージを与えました！"

# --- 関数の呼び出し ---

# 正しい型で呼び出す
# 攻撃力: 100, 防御力: 40, クリティカル: True
message = calculate_battle_result(100, 40, True)
print(message)

# (参考) 異なる型を渡しても実行自体は可能だが、エディタで警告が出る
# error_call = calculate_battle_result("最強", 50, "yes")

実行結果:

敵に 120 のダメージを与えました！

解説

def calculate_battle_result(attacker_atk: int, target_def: int, is_critical: bool) -> str:

attacker_atk: int: 攻撃力は整数であることを期待します。
target_def: int: 防御力は整数であることを期待します。
is_critical: bool: クリティカル判定は真偽値であることを期待します。
-> str: この関数は最終的にメッセージ（文字列）を返すことを示しています。

複合的な型の指定 (`list`, `dict`, `Union`, `Optional`)

単純な型だけでなく、リストや辞書の中身、あるいは「複数の型の可能性がある」場合も表現できます。これには typing モジュール（Python 3.9以降は標準の組み込み型）を使用します。

from typing import List, Dict, Union, Optional

# 整数のリスト（スコア履歴など）
high_scores: List[int] = [5000, 8200, 10500]
# Python 3.9以降なら list[int] = [...] と書ける

# 文字列または数値を許容する (Union) - IDなど
player_id: Union[int, str] = "P-999"
# Python 3.10以降なら int | str = "P-999" と書ける

# 文字列または None を許容する (Optional) - ギルド名など
guild_name: Optional[str] = None