Zenn
🍣

【Python】typingモジュール完全ガイド（初心者向け解説付き）

に公開
Python
typing
tech

Pythonのtypingモジュールは、関数や変数に対して静的な型ヒントを与えることで、
コードの可読性・保守性・バグ防止に大きく寄与します。
ちなみにただヒントなので、従わなくても通常はエラーは発生しません。

今回はよく使う型ヒントを "どう使うか" を具体例付きで整理しました。

✅ List

from typing import List

def get_tags() -> List[str]:
    return ["python", "backend", "AI"]
  • 意味：リスト（配列）で、各要素は文字列型（str）であることを示す
  • 使いどころ：複数の同じ型の値を順番に持ちたいとき

✅ Dict

from typing import Dict

def get_user_scores() -> Dict[str, int]:
    return {"alice": 85, "bob": 92}
  • 意味：キーが文字列、値が整数の辞書型
  • 使いどころ：名前→スコアのような、対応関係を持つデータ構造

✅ Optional

from typing import Optional

def get_title(article: dict) -> Optional[str]:
    return article.get("title")
  • 意味：戻り値は str または None の可能性がある
  • 使いどころ：値が存在しないかもしれない場合（null相当）

✅ Any

from typing import Any, Dict

def get_settings() -> Dict[str, Any]:
    return {
        "theme": "dark",
        "autosave": True,
        "timeout": 30,
        "extensions": ["vim", "emacs"]
    }
  • 意味：値の型が何でも許される（文字列、数値、リストなど）
  • 使いどころ：構造が決まっていない辞書（設定ファイルや外部APIのレスポンス）

✅ Tuple

from typing import Tuple

def get_position() -> Tuple[int, int]:
    return (10, 20)
  • 意味：決まった長さ・順番・型を持つタプル（固定長の配列）
  • 使いどころ：座標 (x, y) やRGBなどの、構造が固定された複数値の返却

✅ Union

from typing import Union

def parse_flag(value: str) -> Union[bool, None]:
    if value.lower() == "yes":
        return True
    elif value.lower() == "no":
        return False
    return None
  • 意味：bool か None のいずれかになる可能性がある
  • 使いどころ：戻り値の型が複数の可能性を持つとき（例えば成功ならTrue、失敗ならNone）

✅ Literal

from typing import Literal

def get_status() -> Literal["open", "closed"]:
    return "open"
  • 意味：戻り値が決まった文字列（定数）のどれかであると保証
  • 使いどころ：ステータスやフラグなど、値の選択肢を限定したいとき

✅ Callable

from typing import Callable

def apply_func(x: int, f: Callable[[int], int]) -> int:
    return f(x)
  • 意味：関数 f は int を受け取り int を返す関数であることを明示
  • 使いどころ：関数を引数として受け取りたいとき（高階関数）

✅ TypedDict（構造化されたDict）

from typing import TypedDict

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

def get_user() -> User:
    return {"name": "Taro", "age": 20}
  • 意味：各キーと型を固定した辞書の定義（名前付きのDict）
  • 使いどころ：明確な構造の辞書型を使いたいとき。エディタ補完も効くようになる。

✅ Final

from typing import Final

PI: Final = 3.14
  • 意味：この変数は再代入しない（定数として使う）
  • 使いどころ：定数として値を固定したいとき。mypyで警告が出るようにできる。

✅ Annotated（補足的な型情報）

from typing import Annotated

def id_number(n: Annotated[int, "must be positive"]) -> int:
    return abs(n)
  • 意味：型に注釈（メタ情報）を与える
  • 使いどころ：FastAPIやPydanticなどで型に追加情報をつけて使いたいとき

少しでも助力になれたら嬉しいです

Discussion